OpenFang 구축 튜토리얼

난이도: 입문 | 소요 시간: 15분 | 목표: OpenFang 배포 및 모델 설정 마스터

서론

가볍고 강력한 AI Agent 프레임워크를 찾고 있다면 OpenFang을 주목해 보세요. 이는 Rust로 작성된 오픈 소스 Agent Operating System으로, 시스템 전체를 컴파일해도 크기가 약 32MB에 불과하지만 Anthropic Claude, Google Gemini, OpenAI GPT, DeepSeek, Groq 등 20개 이상의 주요 LLM 제공업체를 기본적으로 지원합니다.

기존 프레임워크와 달리 OpenFang은 단순한 Chatbot 래퍼가 아니라, 사용자를 위해 실제로 일하는 자율형 Agent 시스템입니다. 미리 정해진 계획에 따라 실행되며 지식 그래프 구축, 목표 모니터링, 잠재 고객 생성, 소셜 미디어 관리 등을 도와주고 결과를 Dashboard에 자동으로 보고합니다.

오늘 함께 구축해 봅시다.

---

대상 독자

• 1~5년 차 경력의 개발자
• AI Agent에 관심이 있는 기술 인력
• 로컬 AI 기능을 빠르게 배포하고 싶은 기술 애호가

---

핵심 의존성 및 환경

시작하기 전에 시스템이 다음 조건을 충족하는지 확인하세요.

• 운영체제: Linux, macOS, Windows (WSL2 또는 PowerShell)
• Rust: 1.75+ (rustup 사용 권장)
• 메모리: 최소 4GB RAM
• 디스크: 최소 500MB 여유 공간

Rust 설치 (미설치 시)

# Linux/macOS
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Windows (PowerShell 사용)
irm https://sh.rustup.rs | iex

설치 완료 후 rustc --version을 실행하여 버전을 확인합니다.

---

프로젝트 구조

openfang/
├── agents/                 # Agent 템플릿 디렉토리
│   ├── hello-world/
│   ├── coder/
│   ├── researcher/
│   └── ...
├── crates/                # Rust crates (14개)
│   ├── openfang-cli/      # CLI 커맨드라인
│   ├── openfang-runtime/  # 런타임 코어
│   ├── openfang-api/      # REST API
│   └── ...
├── docs/                  # 공식 문서
├── sdk/                   # 다국어 SDK
│   ├── python/
│   └── javascript/
└── config.toml.example    # 설정 예시

---

빠른 설치

방법 1: 공식 원클릭 설치 (권장)

Linux/macOS:

curl -fsSL https://openfang.sh/install | sh

Windows PowerShell:

irm https://openfang.sh/install.ps1 | iex

설치가 완료되면 다음과 같은 메시지가 표시됩니다:

✅ OpenFang installed successfully!
Run 'openfang init' to get started.

방법 2: 수동 컴파일

소스 코드에서 직접 빌드하거나 원클릭 설치를 지원하지 않는 환경의 경우:

# 저장소 복제
git clone https://github.com/RightNow-AI/openfang.git
cd openfang

# release 버전 컴파일
cargo build --release

# 또는 CLI만 컴파일
cargo build --release -p openfang-cli

컴파일이 완료되면 바이너리 파일은 target/release/openfang(또는 target/release/openfang.exe)에 위치합니다.

---

초기 설정

설정 파일 생성

초기화 명령을 실행합니다:

openfang init

사용자 홈 디렉토리에 설정 폴더가 생성됩니다:

~/.openfang/
└── config.toml    # 메인 설정 파일

설정 파일 구조

~/.openfang/config.toml을 열면 기초 설정은 다음과 같습니다:

# API 서비스 설정
host = "127.0.0.1"
port = 4200

# API 키 (선택 사항, 운영 환경에서는 설정을 권장)
api_key = ""

# 기본 모델 설정
[default_model]
provider = "groq"
model = "llama-3.3-70b-versatile"

# Agent 기본 설정
[agents.defaults]

[!TIP]
설정 파일의 모든 필드는 선택 사항이며, 누락된 필드는 기본값을 사용합니다.

API Key 설정

OpenFang은 환경 변수를 통한 API Key 설정을 지원합니다. 먼저 체험해 보려면 Groq(무료 한도)이나 Defapi(반값)를 추천합니다:

# 방법 1: Groq (무료, 속도 제한 있음)
export GROQ_API_KEY="gsk_당신의Groq키"

# 방법 2: Defapi (반값, 권장)
export DEFAPI_API_KEY="당신의Defapi키"

[!WARNING]
API Key를 설정 파일에 직접 작성하지 말고, 환경 변수를 참조하도록 하세요.

---

서비스 시작

OpenFang 실행

openfang start

다음과 유사한 출력이 표시됩니다:

🚀 Starting OpenFang daemon...
📡 Server listening on http://127.0.0.1:4200
🌐 Dashboard: http://127.0.0.1:4200
✅ OpenFang is ready!

서비스 확인

# 상태 확인
curl http://127.0.0.1:4200/api/health

# 사용 가능한 모델 확인
curl http://127.0.0.1:4200/api/models

# 제공업체 상태 확인
curl http://127.0.0.1:4200/api/providers

Dashboard 접속

브라우저에서 http://127.0.0.1:4200에 접속하면 OpenFang의 Web Dashboard를 볼 수 있습니다.

---

첫 번째 Agent

내장 템플릿 사용

OpenFang은 agents/ 디렉토리에 여러 내장 Agent 템플릿을 제공합니다:

# 사용 가능한 템플릿 목록 확인
openfang template list

주요 템플릿:

• hello-world: 가장 단순한 대화형 Agent
• coder: 코드 작성 도우미
• researcher: 연구 보조
• assistant: 범용 비서

Agent 생성

# hello-world 템플릿을 사용하여 생성
openfang agent create hello-world my-first-agent

메시지 테스트

# CLI를 통해 메시지 전송
openfang agent message my-first-agent "Hello, say hi in 3 words"

또는 REST API를 통해:

curl -X POST http://127.0.0.1:4200/api/agents/{agent-id}/message \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, say hi in 3 words"}'

정상적인 응답이 돌아온다면 Agent가 잘 작동하고 있는 것입니다!

---

모델 설정 실전

Groq 설정 (무료 한도)

Groq은 무료 티어를 제공하며 속도가 매우 빨라 개발 및 테스트에 적합합니다:

# ~/.openfang/config.toml
[default_model]
provider = "groq"
model = "llama-3.3-70b-versatile"

환경 변수:

export GROQ_API_KEY="gsk_당신의키"

[!TIP]
Groq 무료 티어는 속도 제한(Rate Limit)이 있으니 개발 테스트용으로 적합합니다. 운영 환경에서는 다른 제공업체 사용을 권장합니다.

Defapi 설정 (반값 추천)

고성능 모델을 저렴한 가격에 사용하고 싶다면 Defapi가 훌륭한 선택입니다. 가격이 공식가의 50% 수준입니다:

• Gemini 2.5 Pro: 공식 $1.25/M → Defapi 단 $0.625/M
• Claude Sonnet 4: 공식 $3.00/M → Defapi 단 $1.50/M

# ~/.openfang/config.toml

# 커스텀 제공업체 추가
[[providers]]
name = "defapi"
base_url = "https://api.defapi.org/v1"
api_key_env = "DEFAPI_API_KEY"

# 기본 모델 설정
[default_model]
provider = "defapi"
model = "claude-sonnet-4-20250514"

환경 변수:

export DEFAPI_API_KEY="당신의Defapi키"

[!TIP]
Defapi는 v1/chat/completions, v1/messages, v1beta/models/* 등 다양한 프로토콜을 지원하며 OpenFang과 완벽히 호환됩니다.

Anthropic Claude 설정

[default_model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"

export ANTHROPIC_API_KEY="sk-ant-당신의키"

Google Gemini 설정

[default_model]
provider = "gemini"
model = "gemini-2.5-flash"

# GEMINI_API_KEY 또는 GOOGLE_API_KEY 모두 가능
export GEMINI_API_KEY="AIza당신의키"

OpenAI 설정

[default_model]
provider = "openai"
model = "gpt-4o-mini"

export OPENAI_API_KEY="sk-당신의키"

---

자주 묻는 질문(FAQ) 및 문제 해결

Q1: API Key가 적용되지 않는 것 같습니다

확인 단계:

1. 환경 변수가 올바르게 내보내졌는지 확인: echo $GROQ_API_KEY
2. OpenFang 서비스 재시작: openfang restart
3. 제공업체 상태 확인: curl http://127.0.0.1:4200/api/providers

Q2: 모델을 사용할 수 없다고 표시됩니다

가능한 원인:

• API Key 미설정 또는 형식 오류
• 해당 모델이 제공업체 지원 목록에 없음
• 네트워크 연결 문제

해결 방법:

# 상세 모델 목록 확인
curl http://127.0.0.1:4200/api/models | jq

# 특정 제공업체 연결 테스트
curl -X POST http://127.0.0.1:4200/api/providers/groq/test

Q3: 4200 포트가 이미 사용 중입니다

# 점유 중인 프로세스 확인
lsof -i :4200   # Linux/macOS
netstat -ano | findstr :4200  # Windows

# 설정 파일을 수정하여 다른 포트 사용
# ~/.openfang/config.toml
port = 4201

Q4: 컴파일 오류 발생

Rust 버전이 최신인지 확인하세요:

rustup update
rustc --version  # 1.75 이상이어야 함

의존성 문제인 경우 다음을 시도하세요:

cargo clean
cargo build --release

Q5: Windows에서 명령어를 찾을 수 없습니다

OpenFang 바이너리 파일이 PATH에 포함되어 있는지 확인하세요:

# 바이너리 디렉토리를 PATH에 추가 (영구적)
$env:PATH += ";$env:USERPROFILE\.openfang\bin"

# 또는 전체 경로를 직접 사용
~\.openfang\bin\openfang.exe start

Q6: 로그 확인 방법

# 실시간 로그 확인
openfang logs

# 또는 로그 파일 직접 확인
cat ~/.openfang/logs/openfang.log

---

심화 방향

Hands: 7가지 내장 능력 팩

OpenFang의 가장 큰 특징은 7가지 강력한 Hands가 내장되어 있다는 점입니다:

Hand	기능
Clip	YouTube 동영상 다운로드, 편집, 더빙, 소셜 미디어 자동 게시
Lead	일일 리드 생성, 고객 발굴, 점수 산정, 중복 제거
Collector	OSINT 정보 수집, 변경 감지, 지식 그래프 구축
Predictor	예측 엔진, 신뢰 구간, 정확도 추적
Researcher	심층 연구, 다중 소스 교차 검증, APA 형식 보고서
Twitter	자동 트윗, 대댓글 상호작용, 게시 일정 관리
Browser	웹 자동화, 양식 작성, 다단계 워크플로우

# Researcher Hand 활성화
openfang hand activate researcher

# 상태 확인
openfang hand status researcher

# 일시 중지
openfang hand pause researcher

커스텀 Agent 개발

커스텀 Agent를 생성합니다:

# my-agent.toml
name = "my-agent"
version = "0.1.0"
description = "My custom agent"
author = "you"

[model]
provider = "groq"
model = "llama-3.3-70b-versatile"

[capabilities]
tools = ["file_read", "web_fetch", "bash"]
memory_read = ["*"]
memory_write = ["self.*"]

# 커스텀 Agent 배포
openfang agent deploy my-agent.toml

MCP 통합

OpenFang은 MCP (Model Context Protocol)를 지원하여 다양한 외부 서비스와 연결할 수 있습니다:

[[mcp_servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

---

요약

오늘 우리는 OpenFang의 전체 구축 과정을 함께 완료했습니다:

• ✅ OpenFang 설치 (공식 스크립트 또는 수동 컴파일)
• ✅ 초기 설정 (config.toml + 환경 변수)
• ✅ 서비스 시작 및 검증
• ✅ 첫 번째 Agent 생성 및 테스트
• ✅ 다양한 LLM 제공업체 설정 (Groq, Defapi, Claude, Gemini)
• ✅ 일반적인 문제 해결

이제 완전한 AI Agent 실행 플랫폼을 갖게 되었습니다! 다음 단계로 이것들을 시도해 보세요:

1. Hands 중 하나를 활성화하여 자동화 업무 능력을 체험해 보세요.
2. 커스텀 Agent를 생성하여 자신만의 도구와 능력을 정의해 보세요.
3. MCP 통합을 탐구하여 더 많은 외부 서비스를 연결해 보세요.

즐거운 개발 되시길 바랍니다!

[!TIP]
운영 환경에서는 Defapi(반값)를 사용하거나 여러 Provider를 설정하여 장애 조치(Failover)를 구현함으로써 서비스 안정성을 확보하는 것을 권장합니다.

---

확장 읽기

• OpenFang 공식 문서
• LLM Providers 전체 가이드
• Hands 개발 문서
• Defapi 웹사이트