OpenFang 安裝與初始化指南：從零到運行第一個 Agent

Slug: openfang-install-setup-guide 分類: usage-guides (使用指南) 目標關鍵詞: OpenFang 安裝, OpenFang 配置教學, OpenFang 入門指南 搜尋意圖: 資訊型（用戶想部署 OpenFang） 目標字數: ~1800 字語言: tw

什麼是 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 免受攻擊