OpenFang 搭建教程

难度：入门级 | 时长：15 分钟 | 收获：掌握 OpenFang 部署与模型配置

前言

如果你正在寻找一个轻量级、功能强大的 AI Agent 框架，OpenFang 值得你关注。这是一个用 Rust 编写的开源 Agent Operating System，整个系统编译后只有约 32MB，却内置支持 20+ 主流 LLM 提供商，包括 Anthropic Claude、Google Gemini、OpenAI GPT、DeepSeek、Groq 等。

与传统框架不同，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    # 配置示例

快速安装

方式一：官方一键安装（推荐）

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.

方式二：手动编译

如果你想从源码构建，或者在不支持一键安装的环境：

# 克隆仓库
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（半价）先体验：

# 方式一：Groq（免费，有速率限制）
export GROQ_API_KEY="gsk_你的Groq密钥"

# 方式二：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 提供了多个内置 Agent 模板，位于 agents/ 目录：

# 列出可用模板
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 提供免费 tier，速度极快，适合开发和测试：

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

环境变量：

export GROQ_API_KEY="gsk_你的密钥"

[!TIP]
Groq 免费 tier 有速率限制，适合开发测试。生产环境建议使用其他提供商。

配置 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-你的密钥"

常见问题排查

Q1: API Key 似乎没有生效

检查步骤：

确认环境变量已正确导出：echo $GROQ_API_KEY
重启 OpenFang 服务：openfang restart
查看提供商状态：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	Web 自动化、表单填写、多步骤工作流

# 激活 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 运行平台！下一步可以尝试：

激活一个 Hands，体验自动化工作能力
创建自定义 Agent，定义自己的工具和能力
探索 MCP 集成，连接更多外部服务

祝你玩得开心！

[!TIP]
生产环境建议使用 Defapi（半价）或配置多 Provider 实现故障转移，保证服务稳定性。

前言