打赏

**超详细的 OpenFang 安装使用教程**，从 0 开始，新手小白也能懂。

超详细的 OpenFang 安装使用教程，从 0 开始，新手小白也能懂。

OpenFang 完全新手教程

开源 AI Agent 操作系统 - 安装与使用指南

什么是 OpenFang？

OpenFang 是一个用 Rust 编写的开源 Agent 操作系统，不是简单的聊天机器人框架，而是一个完整的智能体操作系统：

  • 单文件部署：只有一个 ~32MB 的二进制文件，零依赖
  • 40+ 通讯渠道：TG、Discord、Slack、WhatsApp、邮件等
  • 7 个自主 Hands：自动运行的智能代理（研究、收集、预测等）
  • 16 层安全机制：WASM 沙盒、审计追踪、SSRF 防护等
  • 支持 26 个 LLM 提供商：OpenAI、Claude、Gemini、Groq、DeepSeek 等

第一部分：安装 OpenFang

系统要求

  • 操作系统：Linux (Ubuntu/Debian/CentOS)、macOS、Windows
  • 内存：最低 512MB，推荐 1GB+
  • 硬盘：100MB 可用空间
  • 网络：需要连接 LLM API（OpenAI、Claude 等）

安装步骤

Linux/macOS 安装（推荐）

# 一键安装命令
curl -fsSL https://openfang.sh/install | sh

安装过程会自动：

  1. 检测你的系统架构（x86_64/ARM64）
  2. 从 GitHub 下载对应版本的二进制文件
  3. 安装到 ~/.openfang/bin/ 目录
  4. 添加环境变量到 ~/.bashrc 或 ~/.zshrc

验证安装

# 重新加载环境变量（重要！）
source ~/.bashrc

# 或者手动添加 PATH
export PATH=/root/.openfang/bin:$PATH

# 检查版本
openfang --version

# 查看帮助
openfang --help

常见问题：如果提示 command not found，执行 export PATH=/root/.openfang/bin:$PATH 即可解决。

第二部分：初始化配置

步骤 1：初始化工作目录

# 创建配置文件和目录结构
openfang init

这会创建以下目录结构：

~/.openfang/
├── config.toml          # 主配置文件
├── data/                # 数据库和运行时数据
├── agents/              # Agent 清单文件
└── .env                 # 环境变量（API 密钥等）

步骤 2：配置 LLM 提供商

OpenFang 需要至少一个 LLM API 密钥才能工作。这里以 Groq（免费额度大、速度快）为例：

获取 API 密钥

  1. 访问 console.groq.com
  2. 注册账号
  3. 创建 API Key
  4. 复制密钥（格式：gsk_...）

设置环境变量

# 临时设置（当前会话有效）
export GROQ_API_KEY="你的Groq API密钥"

# 永久设置（推荐）
echo 'export GROQ_API_KEY="你的Groq API密钥"' >> ~/.bashrc
source ~/.bashrc

编辑配置文件

# 使用 nano 编辑（或 vim）
nano ~/.openfang/config.toml

默认配置如下，修改为 Groq：

[default_model]
provider = "groq"
model = "llama-3.3-70b-versatile"
# api_key 从环境变量读取，不需要硬编码

[providers.groq]
api_key_env = "GROQ_API_KEY"

其他常用提供商配置：

# OpenAI 配置
[default_model]
provider = "openai"
model = "gpt-4o-mini"

[providers.openai]
api_key_env = "OPENAI_API_KEY"

# Anthropic Claude 配置
[default_model]
provider = "anthropic"
model = "claude-3-5-sonnet-20241022"

[providers.anthropic]
api_key_env = "ANTHROPIC_API_KEY"

步骤 3：验证配置

# 运行诊断检查
openfang doctor

正常输出应显示：

  • ✅ Config file exists
  • ✅ API keys are set
  • ✅ Database is accessible
  • ✅ Toolchain available

第三部分：启动与基础使用

启动守护进程

# 启动 OpenFang（前台运行，按 Ctrl+C 停止）
openfang start

# 后台运行（Linux）
nohup openfang start > openfang.log 2>&1 &

# 或者使用 systemd（推荐用于服务器）

启动后会显示：

Starting OpenFang daemon...
OpenFang daemon running on http://127.0.0.1:4200

访问 Web 界面

打开浏览器访问：

http://localhost:4200

界面功能：

  • 查看运行中的 Agents
  • 实时聊天（WebSocket）
  • 查看 Token 使用量
  • 管理 Hands 和 Workflows

基础命令速查

# 查看守护进程状态
openfang status

# 停止守护进程
openfang stop

# 查看日志
openfang logs

# 实时查看日志
openfang logs -f

# 交互式终端界面
openfang tui

第四部分：创建你的第一个 Agent

方式 1：使用内置模板（推荐新手）

# 查看可用模板
openfang agent list-templates

# 创建 coder 代理（程序员助手）
openfang agent spawn coder

# 创建 researcher 代理（研究员）
openfang agent spawn researcher

# 查看运行中的代理
openfang agent list

输出示例：

ID                                      NAME        STATE    PROVIDER   MODEL
a1b2c3d4-e5f6-7890-abcd-ef1234567890   coder       Running  groq       llama-3.3-70b-versatile

方式 2：与 Agent 聊天

# 快速聊天（自动选择第一个可用代理）
openfang chat

# 指定代理聊天
openfang chat coder

# 使用 Agent ID 聊天
openfang chat a1b2c3d4-e5f6-7890-abcd-ef1234567890

聊天示例：

Chat session started (daemon mode). Type 'exit' or Ctrl+C to quit.
you> 你好，你能做什么？
agent> 我是 coder 代理，我可以：
- 读取和分析代码文件
- 列出目录内容
- 搜索网络资源
- 执行代码审查
请告诉我你需要什么帮助！

you> 查看当前目录的文件
agent> 当前目录文件：
- main.py
- README.md
- requirements.txt

[tokens: 142 in / 87 out | iterations: 1]
you> exit

方式 3：创建自定义 Agent

创建文件 my-agent.toml：

name = "my-assistant"
description = "我的个人助手"

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

[capabilities]
tools = ["read_file", "list_directory", "web_search"]
max_iterations = 10

[system_prompt]
content = """
你是一个有用的 AI 助手。你会说中文，性格友好。
回答问题时请简洁明了。
"""

然后加载：

openfang agent spawn --manifest ./my-agent.toml

第五部分：配置 TG 机器人（消息通知）

这是实际使用中最常用的功能，让 Agent 能通过 TG 与你互动。

步骤 1：创建 TG Bot

  1. 打开 TG，搜索 @BotFather
  2. 发送 /newbot 创建新机器人
  3. 设置名称（如 MyOpenFangBot）和用户名（必须以 bot 结尾，如 myopenfang_bot）
  4. 保存 Bot Token（格式：123456789:ABCdefGHIjklMNOpqrsTUVwxyz）

步骤 2：交互式配置（推荐）

# 运行配置向导
openfang channel setup TG

按提示输入：

  • Bot Token
  • 是否允许所有用户（建议先允许，之后可限制）
  • 其他选项默认即可

步骤 3：手动配置（备选）

如果交互式配置失败，手动编辑：

# 编辑配置文件
nano ~/.openfang/config.toml

添加：

[channels.TG]
enabled = true
bot_token_env = "TG_BOT_TOKEN"  # 环境变量名
default_agent = "coder"  # 默认处理的 Agent

# 可选：限制允许的用户（留空表示允许所有人）
allowed_users = []

设置环境变量：

export TG_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
echo 'export TG_BOT_TOKEN="你的Token"' >> ~/.bashrc
source ~/.bashrc

步骤 4：重启生效

# 停止再启动
openfang stop
openfang start

# 或者如果支持 restart（视版本而定）
openfang stop && openfang start

步骤 5：测试

  1. 在 TG 中搜索你的 Bot 用户名
  2. 发送 /start 或任意消息（如 你好）
  3. Agent 应该会回复你！

首次使用配对：
如果配置了 allowed_users，首次使用时会收到配对码，运行：

openfang pairing approve TG <配对码>

第六部分：使用 Hands（自主代理）

Hands 是 OpenFang 的独特功能，无需你发送消息，自动定时运行。

查看可用 Hands

openfang hand list

内置 7 个 Hands：

Hand 功能
Researcher 深度研究，自动查证，生成引用报告
Collector 情报收集，监控目标，构建知识图谱
Lead 潜在客户发现，评分，去重
Predictor 超级预测，置信度校准
Clip YouTube 视频转短视频，自动发布
Twitter Twitter 账号管理，内容发布
Browser 网页自动化，表单填写（购买需审批）

激活 Researcher Hand（示例）

# 激活
openfang hand activate researcher

# 查看状态
openfang hand status researcher

# 暂停（不丢失状态）
openfang hand pause researcher

# 停止
openfang hand stop researcher

Researcher Hand 工作流程

  1. 自动运行：每 X 分钟检查一次配置的研究主题
  2. 深度搜索：使用 BrowseComp 技术交叉验证多个来源
  3. 可信度评估：使用 CRAAP 标准（时效性、相关性、权威性、准确性、目的性）
  4. 生成报告：带 APA 引用的结构化报告
  5. 通知用户：通过 TG/Discord 发送摘要

第七部分：进阶配置

配置多个渠道（Discord + TG）

[channels.TG]
enabled = true
bot_token_env = "TG_BOT_TOKEN"
default_agent = "researcher"

[channels.discord]
enabled = true
token = "你的Discord Bot Token"
allowed_users = ["你的Discord用户ID"]
default_agent = "coder"

配置定时任务（Cron）

# 查看定时任务
openfang cron list

# 创建定时任务（让 Agent 每小时检查邮件）
openfang cron create --name "check-email" --schedule "0 * * * *" --agent "coder" --prompt "检查我的邮件并总结重要内容"

使用工作流（Workflow）

创建 research-workflow.toml：

name = "每日研究报告"
description = "自动研究并发送报告"

[[steps]]
name = "research"
agent = "researcher"
prompt = "研究今日 AI 领域最新进展"

[[steps]]
name = "summarize"
agent = "coder"
prompt = "将研究结果总结为 3 点，用中文"
depends_on = ["research"]

[[steps]]
name = "notify"
channel = "TG"
message = "📊 今日 AI 报告：\n{{steps.summarize.output}}"
depends_on = ["summarize"]

运行：

openfang workflow create --file research-workflow.toml
openfang workflow run research-workflow

第八部分：Docker 部署（可选）

适合服务器环境：

# 拉取镜像
docker pull ghcr.io/rightnow-ai/openfang:latest

# 初始化配置（只需一次）
docker run -v ~/.openfang:/root/.openfang --rm \
  ghcr.io/rightnow-ai/openfang:latest init

# 编辑配置
nano ~/.openfang/config.toml

# 运行守护进程
docker run -d \
  -v ~/.openfang:/root/.openfang \
  -p 4200:4200 \
  -p 50051:50051 \
  -e GROQ_API_KEY="你的密钥" \
  --name openfang \
  ghcr.io/rightnow-ai/openfang:latest start

第九部分：故障排除

1. 命令找不到

# 手动添加 PATH
export PATH=/root/.openfang/bin:$PATH
echo 'export PATH=/root/.openfang/bin:$PATH' >> ~/.bashrc

2. API 密钥错误

# 检查环境变量是否设置
echo $GROQ_API_KEY

# 检查配置
openfang config show

3. 端口被占用

# 修改配置文件中的端口
nano ~/.openfang/config.toml
# 修改 api_listen = "0.0.0.0:4201"

4. TG 无响应

# 检查日志
openfang logs

# 验证 Token 是否正确
curl https://api.TG.org/bot<你的Token>/getMe

5. 诊断工具

# 全面检查
openfang doctor

# 检查守护进程健康
openfang health

# 查看系统信息
openfang system info

第十部分：常用命令速查表

命令 功能
openfang init 初始化配置
openfang start 启动守护进程
openfang stop 停止守护进程
openfang status 查看状态
openfang logs 查看日志
openfang doctor 诊断检查
openfang chat 快速聊天
openfang agent list 列出 Agents
openfang agent spawn <模板> 创建 Agent
openfang hand list 列出 Hands
openfang hand activate <name> 激活 Hand
openfang channel setup <平台> 配置渠道
openfang config show 显示配置
openfang tui 交互式界面
openfang dashboard 打开 Web 界面

总结

你现在应该已经：

  • ✅ 成功安装 OpenFang
  • ✅ 配置了 LLM 提供商（Groq/OpenAI/Claude）
  • ✅ 启动了守护进程并访问 Web 界面
  • ✅ 创建了第一个 Agent 并与之对话
  • ✅ 配置了 TG 机器人通知
  • ✅ 了解了 Hands 自主代理系统

下一步建议：

  1. 尝试不同的 Agent 模板（coder, writer, analyst）
  2. 激活 Researcher Hand 体验自动研究
  3. 配置 Discord/Slack 等其他渠道
  4. 探索 Workflow 实现多 Agent 协作

遇到问题随时查看官方文档：openfang.sh/docs 或运行 openfang doctor 诊断！

posted @ 2026-03-04 22:37  gyc567  阅读(2874)  评论(0)    收藏  举报