Moltbot 文件

Appearance

引導精靈（CLI） ​

引導精靈是在 macOS、Linux 或 Windows（透過 WSL2；強烈建議）上設定 Moltbot 的建議方式。 它在一個引導流程中配置本地閘道或遠端閘道連線，以及頻道、技能和工作區預設值。

主要入口點：

bash
moltbot onboard

最快速的首次聊天：開啟控制介面（不需要頻道設定）。執行 moltbot dashboard 並在瀏覽器中聊天。文件：儀表板。

後續重新配置：

bash
moltbot configure

建議：設定 Brave Search API 金鑰，以便代理可以使用 web_search（web_fetch 不需要金鑰即可運作）。最簡單的方式：moltbot configure --section web，它會儲存 tools.web.search.apiKey。文件：網路工具。

快速開始 vs 進階 ​

精靈從快速開始（預設值）與進階（完全控制）開始。

快速開始保持預設值：

  • 本地閘道（loopback）
  • 工作區預設值（或現有工作區）
  • 閘道埠 18789
  • 閘道驗證 Token（自動產生，即使在 loopback 上）
  • Tailscale 暴露 關閉
  • Telegram + WhatsApp 私訊預設為 allowlist（會提示你輸入電話號碼）

進階暴露每個步驟（模式、工作區、閘道、頻道、守護程式、技能）。

精靈的功能 ​

**本地模式（預設）**引導你完成：

  • 模型/驗證（OpenAI Code（Codex）訂閱 OAuth、Anthropic API 金鑰（建議）或 setup-token（貼上），以及 MiniMax/GLM/Moonshot/AI Gateway 選項）
  • 工作區位置 + 啟動檔案
  • 閘道設定（埠/綁定/驗證/tailscale）
  • 提供者（Telegram、WhatsApp、Discord、Google Chat、Mattermost（外掛）、Signal）
  • 守護程式安裝（LaunchAgent / systemd 使用者單元）
  • 健康檢查
  • 技能（建議）

遠端模式僅配置本地客戶端以連接到其他地方的閘道。 它不會在遠端主機上安裝或變更任何內容。

要新增更多隔離代理（獨立工作區 + 會話 + 驗證），請使用：

bash
moltbot agents add <name>

提示：--json 不意味著非互動模式。使用 --non-interactive（和 --workspace）進行腳本化。

流程詳情（本地） ​

  1. 現有配置檢測

    • 如果 ~/.clawdbot/moltbot.json 存在，選擇 保留 / 修改 / 重置。
    • 重新執行精靈不會清除任何內容，除非你明確選擇 重置（或傳遞 --reset）。
    • 如果配置無效或包含舊金鑰，精靈會停止並要求你在繼續之前執行 moltbot doctor。
    • 重置使用 trash（從不使用 rm）並提供範圍：
      • 僅配置
      • 配置 + 憑證 + 會話
      • 完全重置（也移除工作區）

  2. 模型/驗證

    • Anthropic API 金鑰（建議）：如果存在則使用 ANTHROPIC_API_KEY，否則提示輸入金鑰，然後儲存以供守護程式使用。
    • Anthropic OAuth（Claude Code CLI）：在 macOS 上，精靈檢查 Keychain 項目「Claude Code-credentials」（選擇「永遠允許」以便 launchd 啟動不會阻塞）；在 Linux/Windows 上，如果存在則重複使用 ~/.claude/.credentials.json。
    • Anthropic token（貼上 setup-token）：在任何機器上執行 claude setup-token，然後貼上權杖（你可以命名它；空白 = 預設）。
    • OpenAI Code（Codex）訂閱（Codex CLI）：如果 ~/.codex/auth.json 存在，精靈可以重複使用它。
    • OpenAI Code（Codex）訂閱（OAuth）：瀏覽器流程；貼上 code#state。
      • 當模型未設定或為 openai/* 時，將 agents.defaults.model 設定為 openai-codex/gpt-5.2。
    • OpenAI API 金鑰：如果存在則使用 OPENAI_API_KEY，否則提示輸入金鑰，然後儲存到 ~/.clawdbot/.env 以便 launchd 可以讀取。
    • OpenCode Zen（多模型代理）：提示輸入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，在 https://opencode.ai/auth 取得）。
    • API 金鑰：為你儲存金鑰。
    • Vercel AI Gateway（多模型代理）：提示輸入 AI_GATEWAY_API_KEY。
    • 更多詳情：Vercel AI Gateway
    • MiniMax M2.1：自動寫入配置。
    • 更多詳情：MiniMax
    • Synthetic（Anthropic 相容）：提示輸入 SYNTHETIC_API_KEY。
    • 更多詳情：Synthetic
    • Moonshot（Kimi K2）：自動寫入配置。
    • Kimi Code：自動寫入配置。
    • 更多詳情：Moonshot AI（Kimi + Kimi Code）
    • 跳過：尚未配置驗證。
    • 從檢測到的選項中選擇預設模型（或手動輸入提供者/模型）。
    • 精靈執行模型檢查，如果配置的模型未知或缺少驗證，則發出警告。
    • OAuth 憑證位於 ~/.clawdbot/credentials/oauth.json；驗證設定檔位於 ~/.clawdbot/agents/<agentId>/agent/auth-profiles.json（API 金鑰 + OAuth）。
    • 更多詳情：/concepts/oauth

  3. 工作區

    • 預設 ~/clawd（可配置）。
    • 為代理啟動儀式所需的工作區檔案做種子。
    • 完整工作區佈局 + 備份指南：代理工作區

  4. 閘道

    • 埠、綁定、驗證模式、tailscale 暴露。
    • 驗證建議：即使對於 loopback 也保持 Token，以便本地 WS 客戶端必須驗證。
    • 僅在你完全信任每個本地程序時才停用驗證。
    • 非 loopback 綁定仍然需要驗證。

  5. 頻道

    • WhatsApp：選用 QR 登入。
    • Telegram：機器人權杖。
    • Discord：機器人權杖。
    • Google Chat：服務帳戶 JSON + webhook 受眾。
    • Mattermost（外掛）：機器人權杖 + 基礎 URL。
    • Signal：選用 signal-cli 安裝 + 帳戶配置。
    • iMessage：本地 imsg CLI 路徑 + DB 存取。
    • 私訊安全：預設為配對。首則私訊發送代碼；透過 moltbot pairing approve <channel> <code> 批准或使用 allowlist。

  6. 守護程式安裝

    • macOS：LaunchAgent
      • 需要已登入的使用者會話；對於無頭，使用自訂 LaunchDaemon（未附帶）。
    • Linux（和透過 WSL2 的 Windows）：systemd 使用者單元
      • 精靈嘗試透過 loginctl enable-linger <user> 啟用 lingering，以便閘道在登出後保持運作。
      • 可能會提示 sudo（寫入 /var/lib/systemd/linger）；它首先嘗試不使用 sudo。
    • **執行時期選擇：**Node（建議；WhatsApp/Telegram 必需）。不建議使用 Bun。

  7. 健康檢查

    • 啟動閘道（如有需要）並執行 moltbot health。
    • 提示：moltbot status --deep 將閘道健康探測新增到狀態輸出（需要可到達的閘道）。

  8. 技能（建議）

    • 讀取可用技能並檢查需求。
    • 讓你選擇節點管理器：npm / pnpm（不建議使用 bun）。
    • 安裝選用相依性（某些在 macOS 上使用 Homebrew）。

  9. 完成

    • 摘要 + 下一步，包括用於額外功能的 iOS/Android/macOS 應用程式。
    • 如果未檢測到 GUI，精靈會列印控制介面的 SSH 埠轉發說明，而不是開啟瀏覽器。
    • 如果控制介面資源缺失，精靈會嘗試建置它們；後備是 pnpm ui:build（自動安裝 UI 相依性）。

遠端模式 ​

遠端模式配置本地客戶端以連接到其他地方的閘道。

你需要設定：

  • 遠端閘道 URL（ws://...）
  • 如果遠端閘道需要驗證，則需要 Token（建議）

注意事項：

  • 不執行遠端安裝或守護程式變更。
  • 如果閘道僅為 loopback，請使用 SSH 通道或 tailnet。
  • 發現提示：
    • macOS：Bonjour（dns-sd）
    • Linux：Avahi（avahi-browse）

新增另一個代理 ​

使用 moltbot agents add <name> 建立具有自己工作區、會話和驗證設定檔的獨立代理。不使用 --workspace 執行會啟動精靈。

它設定：

  • agents.list[].name
  • agents.list[].workspace
  • agents.list[].agentDir

注意事項：

  • 預設工作區遵循 ~/clawd-<agentId>。
  • 新增 bindings 以路由入站訊息（精靈可以執行此操作）。
  • 非互動標誌：--model、--agent-dir、--bind、--non-interactive。

非互動模式 ​

使用 --non-interactive 自動化或腳本化引導：

bash
moltbot onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

新增 --json 以獲得機器可讀的摘要。

精靈寫入的內容 ​

~/.clawdbot/moltbot.json 中的典型欄位：

  • agents.defaults.workspace
  • agents.defaults.model / models.providers（如果選擇 Minimax）
  • gateway.*（模式、綁定、驗證、tailscale）
  • channels.telegram.botToken、channels.discord.token、channels.signal.*、channels.imessage.*
  • 當你在提示期間選擇時的頻道 allowlist（Slack/Discord/Matrix/Microsoft Teams）（名稱在可能時解析為 ID）。
  • skills.install.nodeManager
  • wizard.lastRunAt

moltbot agents add 寫入 agents.list[] 和選用的 bindings。

WhatsApp 憑證位於 ~/.clawdbot/credentials/whatsapp/<accountId>/。 會話儲存在 ~/.clawdbot/agents/<agentId>/sessions/ 下。

相關文件 ​

基於 MIT 授權發布

Copyright © 2026 Moltbot Taiwan