Moltbot 🦞

"EXFOLIATE! EXFOLIATE!" — 某隻太空龍蝦，大概

支援任何作業系統 + WhatsApp/Telegram/Discord/iMessage 的 AI 代理閘道（Pi）。
透過擴充功能支援 Mattermost 等更多平台。 從你的口袋發送訊息，獲得 AI 助理回應。

GitHub · 版本發布 · 文件 · Moltbot 助理設定

Moltbot 橋接 WhatsApp（透過 WhatsApp Web / Baileys）、Telegram（Bot API / grammY）、Discord（Bot API / channels.discord.js）與 iMessage（imsg CLI）到程式碼助理，例如 Pi。擴充功能支援 Mattermost（Bot API + WebSocket）等更多平台。 Moltbot 也是 Clawd（太空龍蝦助理）的核心技術。

從這裡開始

• 全新安裝： 快速開始
• 引導式設定（推薦）： 設定精靈（moltbot onboard）
• 開啟控制台（本地 Gateway）： http://127.0.0.1:18789/（或 http://localhost:18789/）

如果 Gateway 在同一台電腦上運行，該連結會立即開啟瀏覽器控制介面。如果無法開啟，請先啟動 Gateway：moltbot gateway。

控制台（瀏覽器控制介面）

控制台是用於聊天、設定、節點、會話等的瀏覽器控制介面。 本地預設：http://127.0.0.1:18789/ 遠端存取：Web 介面 與 Tailscale

運作原理

WhatsApp / Telegram / Discord / iMessage (+ 擴充功能)
        │
        ▼
  ┌───────────────────────────┐
  │          Gateway          │  ws://127.0.0.1:18789 (僅限本地回送)
  │      (單一來源)           │
  │                           │  http://<gateway-host>:18793
  │                           │    /__moltbot__/canvas/ (Canvas 主機)
  └───────────┬───────────────┘
              │
              ├─ Pi 代理 (RPC)
              ├─ CLI (moltbot …)
              ├─ 聊天介面 (SwiftUI)
              ├─ macOS 應用程式 (Moltbot.app)
              ├─ iOS 節點（透過 Gateway WS + 配對）
              └─ Android 節點（透過 Gateway WS + 配對）

大多數操作都透過 Gateway（moltbot gateway）進行，這是一個長時間運行的程序，負責管理頻道連接和 WebSocket 控制平面。

網路架構

• 每台主機一個 Gateway（推薦）：它是唯一被允許擁有 WhatsApp Web 會話的程序。如果需要備援機器人或嚴格隔離，請使用隔離的設定檔和端口運行多個 Gateway；參見 多個 Gateway。
• 本地回送優先：Gateway WS 預設為 ws://127.0.0.1:18789。
  • 設定精靈現在預設會生成 Gateway token（即使是本地回送）。
  • 若要透過 Tailnet 存取，請執行 moltbot gateway --bind tailnet --token ...（非本地回送綁定需要 token）。
• 節點：連接到 Gateway WebSocket（視需要使用 LAN/tailnet/SSH）；舊版 TCP 橋接已棄用/移除。
• Canvas 主機：在 canvasHost.port（預設 18793）上運行的 HTTP 檔案伺服器，為節點 WebView 提供 /__moltbot__/canvas/；參見 Gateway 設定（canvasHost）。
• 遠端使用：SSH 隧道或 tailnet/VPN；參見 遠端存取 與 發現。

功能特色（概覽）

• 📱 WhatsApp 整合 — 使用 Baileys 實現 WhatsApp Web 協定
• ✈️ Telegram Bot — 透過 grammY 支援私訊 + 群組
• 🎮 Discord Bot — 透過 channels.discord.js 支援私訊 + 伺服器頻道
• 🧩 Mattermost Bot（擴充功能） — Bot token + WebSocket 事件
• 💬 iMessage — 本地 imsg CLI 整合（macOS）
• 🤖 代理橋接 — Pi（RPC 模式）與工具串流
• ⏱️ 串流 + 分塊 — 區塊串流 + Telegram 草稿串流詳情（/concepts/streaming）
• 🧠 多代理路由 — 將提供者帳號/對等方路由到隔離的代理（工作區 + 每個代理的會話）
• 🔐 訂閱認證 — Anthropic（Claude Pro/Max）+ OpenAI（ChatGPT/Codex）透過 OAuth
• 💬 會話 — 直接聊天預設合併到共享的 main；群組則隔離
• 👥 群組聊天支援 — 預設基於提及；擁有者可切換 /activation always|mention
• 📎 媒體支援 — 傳送和接收圖片、音訊、文件
• 🎤 語音訊息 — 選用的轉錄鉤子
• 🖥️ WebChat + macOS 應用程式 — 本地介面 + 選單列工具，用於操作和語音喚醒
• 📱 iOS 節點 — 配對為節點並提供 Canvas 介面
• 📱 Android 節點 — 配對為節點並提供 Canvas + 聊天 + 相機

注意：舊版 Claude/Codex/Gemini/Opencode 路徑已移除；Pi 是唯一的程式碼助理路徑。

快速開始

執行環境需求：Node ≥ 22。

# 推薦：全域安裝（npm/pnpm）
npm install -g moltbot@latest
# 或：pnpm add -g moltbot@latest

# 引導設定 + 安裝服務（launchd/systemd 使用者服務）
moltbot onboard --install-daemon

# 配對 WhatsApp Web（顯示 QR 碼）
moltbot channels login

# 引導後 Gateway 透過服務運行；仍可手動執行：
moltbot gateway --port 18789

在 npm 和 git 安裝之間切換很簡單：安裝另一種方式，然後執行 moltbot doctor 更新 Gateway 服務入口點。

從原始碼安裝（開發用）：

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

如果尚未全域安裝，請從 repo 使用 pnpm moltbot ... 執行引導步驟。

多實例快速開始（選用）：

CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json \
CLAWDBOT_STATE_DIR=~/.clawdbot-a \
moltbot gateway --port 19001

發送測試訊息（需要 Gateway 正在運行）：

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

設定（選用）

設定檔位於 ~/.clawdbot/moltbot.json。

• 如果你什麼都不做，Moltbot 會在 RPC 模式下使用內建的 Pi binary，每個發送者有獨立會話。
• 如果你想鎖定它，從 channels.whatsapp.allowFrom 開始，以及（對於群組）提及規則。

範例：

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  },
  messages: { groupChat: { mentionPatterns: ["@clawd"] } }
}

文件

• 從這裡開始：
  • 文件中心（所有頁面連結）
  • 說明 ← 常見修正 + 疑難排解
  • 設定
  • 設定範例
  • 斜線指令
  • 多代理路由
  • 更新 / 回滾
  • 配對（DM + 節點）
  • Nix 模式
  • Moltbot 助理設定（Clawd）
  • 技能
  • 技能設定
  • 工作區範本
  • RPC 適配器
  • Gateway 操作手冊
  • 節點（iOS/Android）
  • Web 介面（控制 UI）
  • 發現 + 傳輸
  • 遠端存取
• 提供者與使用者體驗：
  • WebChat
  • 控制 UI（瀏覽器）
  • Telegram
  • Discord
  • Mattermost（擴充功能）
  • iMessage
  • 群組
  • WhatsApp 群組訊息
  • 媒體：圖片
  • 媒體：音訊
• 配套應用程式：
  • macOS 應用程式
  • iOS 應用程式
  • Android 應用程式
  • Windows（WSL2）
  • Linux 應用程式
• 操作與安全：
  • 會話
  • Cron 工作
  • Webhooks
  • Gmail 鉤子（Pub/Sub）
  • 安全性
  • 疑難排解

名字由來

Moltbot = CLAW + TARDIS — 因為每隻太空龍蝦都需要一台時空機器。

---

「我們都只是在玩自己的提示詞。」 — 某個 AI，可能吃了太多 tokens

致謝

• Peter Steinberger（@steipete）— 創始人，龍蝦語者
• Mario Zechner（@badlogicc）— Pi 創造者，安全滲透測試員
• Clawd — 要求更好名字的太空龍蝦

核心貢獻者

• Maxim Vovshin（@Hyaxia, 36747317+Hyaxia@users.noreply.github.com）— Blogwatcher 技能
• Nacho Iacovino（@nachoiacovino, nacho.iacovino@gmail.com）— 位置解析（Telegram + WhatsApp）

授權

MIT — 像海洋中的龍蝦一樣自由 🦞

---

「我們都只是在玩自己的提示詞。」 — 某個 AI，可能吃了太多 tokens