OpenFang 설치 및 초기화 가이드

12분 읽기

OpenFang은 Rust 기반의 프로덕션급 Agent 운영체제입니다. 본 가이드에서는 시스템 요구 사항 확인을 시작으로 Rust 툴체인 설치, OpenFang 설치, 설정 파일 초기화, Anthropic API Key 구성, 채널 어댑터 선택 및 첫 번째 Agent 실행 과정을 단계별로 안내합니다.

OpenFang 설치 및 초기화 가이드: 제로에서 첫 번째 Agent 실행까지

Slug: openfang-install-setup-guide 분류: usage-guides (사용 가이드) 목표 키워드: OpenFang 설치, OpenFang 설정 튜토리얼, OpenFang 입문 가이드 검색 의도: 정보형 (사용자가 OpenFang 배포를 원함) 목표 글자 수: ~1800자 언어: ko

OpenFang이란 무엇인가요?

OpenFang은 Rust로 구축된 프로덕션급 Agent 운영체제입니다. 기존 AI 채팅 프레임워크와 달리, OpenFang은 180ms의 콜드 스타트, 40MB의 메모리 점유율, 16단계 보안 보호, 40개의 채널 어댑터를 갖춘 완벽한 Agent 런타임 환경을 제공합니다. 로컬에서 간단한 자동화 작업을 실행하든, 크로스 플랫폼 7×24시간 자율 Agent 클러스터를 구축하든 OpenFang은 최적의 선택입니다.

본 가이드에서는 OpenFang의 설치, 초기화, 그리고 첫 번째 Agent 실행까지의 전 과정을 처음부터 차근차근 안내해 드립니다.

시스템 요구 사항

설치를 시작하기 전에 시스템이 다음 최소 요구 사항을 충족하는지 확인하세요:

구성 요소최소 요구 사항권장 사양
운영체제Linux / macOS / Windows (WSL2)Ubuntu 22.04+
메모리512 MB2 GB+
디스크 공간100 MB1 GB+
런타임Rust 1.75+Rust 1.80+
네트워크아웃바운드 HTTPS안정적인 인터넷 연결

OpenFang의 설계 철학은 "경량 우선"입니다. 라즈베리 파이 4(4GB 버전)에서도 원활하게 실행됩니다.

1단계: Rust 툴체인 설치

OpenFang은 Rust로 작성되었으므로, 먼저 Rust 툴체인을 설치해야 합니다:

bash
# Rustup(Rust 툴체인 관리자) 설치curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh# 환경 변수 다시 로드source "$HOME/.cargo/env"# 설치 확인rustc --versioncargo --version

이미 Rust가 설치되어 있다면 최신 안정 버전으로 업데이트하는 것을 권장합니다:

bash
rustup update stable

2단계: OpenFang 설치

OpenFang은 다양한 설치 방법을 제공하며, Cargo를 통한 직접 설치를 권장합니다:

bash
# crates.io에서 최신 버전 설치cargo install openfang# 설치 확인openfang --version

소스 코드에서 직접 빌드하는 것을 선호하신다면(고급 사용자용):

bash
git clone https://github.com/openfang/openfang.gitcd openfangcargo build --release./target/release/openfang --version

Docker 사용자는 공식 이미지를 사용할 수 있습니다:

bash
docker pull openfang/openfang:latestdocker run -d --name openfang -v ./config:/app/config openfang/openfang

3단계: 설정 초기화

설치가 완료되면 초기화 명령을 실행하여 설정 파일을 생성합니다:

bash
# 기본 설정 디렉토리 생성openfang init# 설정 파일 위치# Linux/macOS: ~/.config/openfang/config.toml# Windows:     %APPDATA%\openfang\config.toml

초기화 후 생성되는 config.toml 파일의 핵심 설정 항목은 다음과 같습니다:

toml
[core]name = "my-first-agent"          # Agent 이름workspace = "./workspace"         # 작업 디렉토리log_level = "info"                # 로그 레벨: trace, debug, info, warn, error[claude]api_key = "${ANTHROPIC_API_KEY}"  # 환경 변수에서 읽기model = "claude-sonnet-5"         # 기본 모델max_tokens = 4096[security]sandbox_mode = "strict"           # 샌드박스 모드: off, basic, strictnetwork_policy = "allowlist"      # 네트워크 정책allowed_domains = ["api.anthropic.com"][channels]# 최소 하나 이상의 채널 어댑터 설정 필요

주요 설정 설명:

  • api_key: 환경 변수 참조(${VAR_NAME} 형식)를 지원합니다. 설정 파일에 직접 API key를 입력하지 마세요.
  • sandbox_mode: 프로덕션 환경에서는 strict 모드를 권장합니다.
  • network_policy: allowlist 모드는 화이트리스트 도메인만 허용하며, blocklist 모드는 블랙리스트 도메인을 차단합니다.
  • channels: 최소 하나 이상의 채널 어댑터가 설정되어야 Agent가 외부와 상호작용할 수 있습니다.

4단계: Anthropic API Key 구성

OpenFang은 Claude API(Anthropic 경유)를 사용하므로 API key 설정이 필요합니다:

bash
# 환경 변수 설정export ANTHROPIC_API_KEY="sk-ant-..."# 셸 설정 파일에 추가 권장echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrcsource ~/.bashrc

API key는 Anthropic Console에서 발급받을 수 있습니다.

5단계: 채널 어댑터 선택 및 설정

OpenFang은 40여 가지의 채널 어댑터를 지원하여 다양한 플랫폼에서 사용자와 상호작용할 수 있습니다. 자주 사용되는 어댑터는 다음과 같습니다:

어댑터용도설정 난이도
CLI명령줄 상호작용⭐
WhatsAppWhatsApp을 통한 Agent 사용⭐⭐
TelegramTelegram Bot 연동⭐⭐
DiscordDiscord Bot 연동⭐⭐⭐
SlackSlack 워크스페이스 연동⭐⭐⭐
Web Chat웹 채팅 위젯⭐⭐

Telegram을 예로 들어 채널을 설정하는 방법입니다:

toml
[channels.telegram]enabled = truebot_token = "${TELEGRAM_BOT_TOKEN}"allowed_users = ["@your_username"]

6단계: 첫 번째 Agent 실행

설정이 완료되면 Agent를 실행합니다:

bash
# 기본 실행openfang start# 설정 파일 지정openfang start --config ./my-config.toml# 백그라운드 실행openfang start --daemon# 실행 로그 확인openfang logs --follow

실행에 성공하면 다음과 같이 표시됩니다:

text
⚡ OpenFang v1.0.0├─ Agent: my-first-agent├─ Model: claude-sonnet-5├─ Sandbox: strict├─ Channels: cli└─ Ready. Type /help for commands.

CLI 채널에서 바로 Agent와 대화할 수 있습니다:

text
> /help> 오늘 날씨 알려줘> 이 GitHub 저장소의 코드 구조를 분석해줘

7단계: 설치 검증

내장 진단 명령어를 실행하여 모든 것이 정상인지 확인합니다:

bash
# 상태 점검openfang doctor# 다음과 같이 출력되어야 합니다:# ✅ Rust toolchain: 1.80.0# ✅ Config file: valid# ✅ API key: configured# ✅ Network: ok (latency 45ms)# ✅ Workspace: writable# All checks passed.

자주 묻는 질문

설치 중 "error: linker `cc` not found" 오류가 발생하면 어떻게 하나요?
C 컴파일러가 없어서 발생하는 문제입니다. Ubuntu/Debian에서는 다음을 실행하세요:

``bash
sudo apt update && sudo apt install build-essential
`

macOS에서는 Xcode Command Line Tools를 설치하세요:

`bash
xcode-select --install
``

실행 시 "API key not configured" 오류가 발생합니다.
다음 사항을 확인하세요:
1. 환경 변수 ANTHROPIC_API_KEY가 설정되었는지 확인: echo $ANTHROPIC_API_KEY
2. 설정 파일에서 "${ANTHROPIC_API_KEY}" 형식(따옴표 포함)으로 참조했는지 확인
3. 설정 파일 다시 로드: openfang reload
라즈베리 파이에서 OpenFang을 실행하려면 어떻게 하나요?
OpenFang의 경량 설계는 ARM 아키텍처에 최적화되어 있습니다:

``bash
# 라즈베리 파이에 Rust 설치
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 의존성 설치
sudo apt install libssl-dev pkg-config

# 컴파일 및 설치 (ARM 최적화)
cargo install openfang --features arm-optimized
``

라즈베리 파이 4(4GB)에서 3~5개의 경량 Agent를 동시에 실행할 수 있습니다.

설정 파일로 YAML을 사용할 수 있나요?
현재는 TOML 형식만 지원합니다. 필요 시 온라인 도구를 사용하여 YAML을 TOML로 변환하세요.
OpenFang을 최신 버전으로 업그레이드하려면 어떻게 하나요?
``bash
cargo install openfang --force
openfang migrate # 설정 형식 변경 사항이 있을 경우
``

다음 단계

OpenFang 설치 및 초기화를 완료하신 것을 축하드립니다! 다음 가이드를 읽어보시는 것을 추천합니다: