快速開始

目標：從零開始到第一次能運作的聊天（使用合理的預設值），盡可能快速完成。

最快速聊天：開啟控制介面（不需要頻道設定）。執行 moltbot dashboard 在瀏覽器中聊天，或在閘道主機上開啟 http://127.0.0.1:18789/。 文件：儀表板 與 控制介面。

建議路徑：使用 CLI 引導精靈 (moltbot onboard)。它會設定：

• 模型/驗證（建議使用 OAuth）
• 閘道設定
• 頻道（WhatsApp/Telegram/Discord/Mattermost (外掛)/...）
• 配對預設值（安全的私訊）
• 工作區啟動 + 技能
• 選用的背景服務

如果你想要更深入的參考頁面，請跳至：精靈、設定、配對、安全性。

沙盒注意事項：agents.defaults.sandbox.mode: "non-main" 使用 session.mainKey（預設為 "main"）， 因此群組/頻道會話會被沙盒化。如果你希望主代理始終在主機上執行，請設定明確的個別代理覆寫：

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/clawd",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

0) 前置需求

• Node >=22
• pnpm（選用；如果從原始碼建置則建議使用）
• 建議： Brave Search API 金鑰用於網路搜尋。最簡單的方式： moltbot configure --section web（儲存 tools.web.search.apiKey）。 參見 網路工具。

macOS：如果你計劃建置應用程式，請安裝 Xcode / CLT。僅使用 CLI + 閘道的話，Node 就足夠了。 Windows：使用 WSL2（建議使用 Ubuntu）。強烈建議使用 WSL2；原生 Windows 未經測試、問題較多，且工具相容性較差。請先安裝 WSL2，然後在 WSL 中執行 Linux 步驟。參見 Windows (WSL2)。

1) 安裝 CLI（建議）

curl -fsSL https://molt.bot/install.sh | bash

安裝程式選項（安裝方法、非互動式、從 GitHub）：安裝。

Windows（PowerShell）：

iwr -useb https://molt.bot/install.ps1 | iex

替代方案（全域安裝）：

npm install -g moltbot@latest

pnpm add -g moltbot@latest

2) 執行引導精靈（並安裝服務）

moltbot onboard --install-daemon

你需要選擇的項目：

• 本地 vs 遠端閘道
• 驗證：OpenAI Code（Codex）訂閱（OAuth）或 API 金鑰。對於 Anthropic，我們建議使用 API 金鑰；也支援 claude setup-token。
• 提供者：WhatsApp QR 登入、Telegram/Discord 機器人權杖、Mattermost 外掛權杖等。
• 守護程式：背景安裝（launchd/systemd；WSL2 使用 systemd）
  • 執行時期：Node（建議；WhatsApp/Telegram 必需）。不建議使用 Bun。
• 閘道權杖：精靈預設會產生一個（即使在 loopback 上）並儲存在 gateway.auth.token 中。

精靈文件：精靈

驗證：儲存位置（重要）

• **建議的 Anthropic 路徑：**設定 API 金鑰（精靈可以儲存它供服務使用）。如果你想重複使用 Claude Code 憑證，也支援 claude setup-token。

• OAuth 憑證（舊版匯入）：~/.clawdbot/credentials/oauth.json

• 驗證設定檔（OAuth + API 金鑰）：~/.clawdbot/agents/<agentId>/agent/auth-profiles.json

無頭/伺服器提示：先在正常機器上進行 OAuth，然後將 oauth.json 複製到閘道主機。

3) 啟動閘道

如果你在引導期間安裝了服務，閘道應該已經在執行：

moltbot gateway status

手動執行（前景）：

moltbot gateway --port 18789 --verbose

儀表板（本地 loopback）：http://127.0.0.1:18789/ 如果配置了權杖，請將其貼到控制介面設定中（儲存為 connect.params.auth.token）。

⚠️ **Bun 警告（WhatsApp + Telegram）：**Bun 在這些頻道上有已知問題。如果你使用 WhatsApp 或 Telegram，請使用 Node 執行閘道。

3.5) 快速驗證（2 分鐘）

moltbot status
moltbot health
moltbot security audit --deep

4) 配對 + 連接你的第一個聊天介面

WhatsApp（QR 登入）

moltbot channels login

透過 WhatsApp → 設定 → 連結的裝置掃描。

WhatsApp 文件：WhatsApp

Telegram / Discord / 其他

精靈可以為你寫入權杖/配置。如果你偏好手動配置，請從以下開始：

• Telegram：Telegram
• Discord：Discord
• Mattermost（外掛）：Mattermost

**Telegram 私訊提示：**你的第一則私訊會返回配對碼。批准它（參見下一步），否則機器人不會回應。

5) 私訊安全（配對批准）

預設姿態：未知的私訊會收到短碼，在批准前不會處理訊息。 如果你的第一則私訊沒有收到回覆，請批准配對：

moltbot pairing list whatsapp
moltbot pairing approve whatsapp <code>

配對文件：配對

從原始碼（開發）

如果你正在修改 Moltbot 本身，請從原始碼執行：

git clone https://github.com/moltbot/moltbot.git
cd moltbot
pnpm install
pnpm ui:build # 首次執行時自動安裝 UI 相依性
pnpm build
moltbot onboard --install-daemon

如果你還沒有全域安裝，請透過 pnpm moltbot ... 從儲存庫執行引導步驟。 pnpm build 也會打包 A2UI 資源；如果你只需要執行該步驟，請使用 pnpm canvas:a2ui:bundle。

閘道（從此儲存庫）：

node moltbot.mjs gateway --port 18789 --verbose

7) 驗證端到端

在新終端機中，傳送測試訊息：

moltbot message send --target +15555550123 --message "Hello from Moltbot"

如果 moltbot health 顯示「未配置驗證」，請返回精靈並設定 OAuth/金鑰驗證——沒有它，代理將無法回應。

提示：moltbot status --all 是最適合貼上的、唯讀的除錯報告。 健康探測：moltbot health（或 moltbot status --deep）會向執行中的閘道請求健康快照。

下一步（選用，但很棒）

• macOS 選單列應用程式 + 語音喚醒：macOS 應用程式
• iOS/Android 節點（Canvas/相機/語音）：節點
• 遠端存取（SSH 通道 / Tailscale Serve）：遠端存取 與 Tailscale
• 永久線上 / VPN 設定：遠端存取、exe.dev、Hetzner、macOS 遠端