OpenFang 安装与初始化指南：从零到运行第一个 Agent

Slug: openfang-install-setup-guide 分类: usage-guides (使用指南) 目标关键词: OpenFang 安装, OpenFang 配置教程, OpenFang 入门指南 搜索意图: 信息型（用户想部署 OpenFang） 目标字数: ~1800 字语言: zh

什么是 OpenFang？

OpenFang 是基于 Rust 构建的生产级 Agent 操作系统。与传统 AI 聊天框架不同，OpenFang 提供完整的 Agent 运行时环境——180ms 冷启动、40MB 内存占用、16 层安全防护、40 个渠道适配器。无论你是想在本地运行一个简单的自动化任务，还是构建跨平台的 7×24 小时自主 Agent 集群，OpenFang 都能胜任。

本文将从零开始，带你完成 OpenFang 的安装、初始化和第一个 Agent 的运行。

系统要求

在开始安装之前，请确认你的系统满足以下最低要求：

组件	最低要求	推荐配置
操作系统	Linux / macOS / Windows (WSL2)	Ubuntu 22.04+
内存	512 MB	2 GB+
磁盘空间	100 MB	1 GB+
运行时	Rust 1.75+	Rust 1.80+
网络	出站 HTTPS	稳定的互联网连接

OpenFang 的设计哲学是"轻量优先"——即使是树莓派 4（4GB 版本）也能流畅运行。

第一步：安装 Rust 工具链

OpenFang 使用 Rust 编写，首先需要安装 Rust 工具链：

# 安装 Rustup（Rust 工具链管理器）curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh# 重新加载环境变量source "$HOME/.cargo/env"# 验证安装rustc --versioncargo --version

如果你已经安装了 Rust，建议更新到最新稳定版：

rustup update stable

第二步：安装 OpenFang

OpenFang 提供多种安装方式，推荐使用 Cargo 直接安装：

# 从 crates.io 安装最新版本cargo install openfang# 验证安装openfang --version

如果你偏好从源码构建（适合需要自定义配置的高级用户）：

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

Docker 用户也可以使用官方镜像：

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

第三步：初始化配置

安装完成后，运行初始化命令创建配置文件：

# 创建默认配置目录openfang init# 配置文件位置# Linux/macOS: ~/.config/openfang/config.toml# Windows:     %APPDATA%\openfang\config.toml

初始化后会生成一个 config.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 无法与外界交互

第四步：配置 Anthropic API Key

OpenFang 依赖 Claude API（通过 Anthropic），需要配置 API key：

# 设置环境变量export ANTHROPIC_API_KEY="sk-ant-..."# 建议写入 shell 配置文件echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrcsource ~/.bashrc

你可以从 Anthropic Console 获取 API key。

第五步：选择和配置渠道适配器

OpenFang 支持 40 余种渠道适配器，让 Agent 能够通过不同平台与用户交互。以下是常用的几种：

适配器	用途	配置复杂度
CLI	命令行交互	⭐
WhatsApp	通过 WhatsApp 使用 Agent	⭐⭐
Telegram	Telegram Bot 集成	⭐⭐
Discord	Discord Bot 集成	⭐⭐⭐
Slack	Slack 工作空间集成	⭐⭐⭐
Web Chat	网页聊天挂件	⭐⭐

以 Telegram 为例配置渠道：

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

第六步：启动你的第一个 Agent

配置完成后，启动 Agent：

# 基础启动openfang start# 指定配置文件openfang start --config ./my-config.toml# 后台运行openfang start --daemon# 查看运行日志openfang logs --follow

启动成功后会显示：

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

在 CLI 渠道中，你可以直接与 Agent 对话：

> /help> 帮我查一下今天的天气> 分析这个 GitHub 仓库的代码结构

第七步：验证安装

运行内置诊断命令确认一切正常：

# 健康检查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 的安装和初始化！接下来建议阅读：

OpenFang Hands 配置指南：了解如何配置不同用途的 Agent 能力模块
OpenFang 多渠道适配器配置：同时配置多个渠道，让你的 Agent 无处不在
OpenFang 安全最佳实践：保护你的 Agent 免受攻击