Moltbot 文件

Appearance

使用 Moltbot 建置個人助理（Clawd 風格） ​

Moltbot 是 Pi 代理的 WhatsApp + Telegram + Discord + iMessage 閘道。外掛新增 Mattermost。本指南是「個人助理」設定：一個專用的 WhatsApp 號碼，行為像你永遠線上的代理。

⚠️ 安全第一 ​

你將代理置於可以執行以下操作的位置：

  • 在你的機器上執行指令（取決於你的 Pi 工具設定）
  • 在你的工作區中讀取/寫入檔案
  • 透過 WhatsApp/Telegram/Discord/Mattermost（外掛）發送訊息

從保守開始：

  • 始終設定 channels.whatsapp.allowFrom（切勿在個人 Mac 上開放給全世界）。
  • 為助理使用專用的 WhatsApp 號碼。
  • 心跳現在預設為每 30 分鐘一次。在你信任設定之前停用它，方法是設定 agents.defaults.heartbeat.every: "0m"。

前置需求 ​

  • Node 22+
  • Moltbot 在 PATH 中可用（建議：全域安裝）
  • 助理的第二個電話號碼（SIM/eSIM/預付卡）
bash
npm install -g moltbot@latest
# 或：pnpm add -g moltbot@latest

從原始碼（開發）：

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

雙手機設定（建議） ​

你想要這樣：

你的手機（個人）              第二支手機（助理）
┌─────────────────┐           ┌─────────────────┐
│  你的 WhatsApp  │  ──────▶  │  助理 WA        │
│  +1-555-YOU     │  訊息     │  +1-555-CLAWD   │
└─────────────────┘           └────────┬────────┘
                                       │ 透過 QR 連結
                                       ▼
                              ┌─────────────────┐
                              │  你的 Mac       │
                              │  (moltbot)      │
                              │    Pi 代理      │
                              └─────────────────┘

如果你將個人 WhatsApp 連結到 Moltbot，每則傳送給你的訊息都會成為「代理輸入」。這很少是你想要的。

5 分鐘快速開始 ​

  1. 配對 WhatsApp Web（顯示 QR；使用助理手機掃描）：
bash
moltbot channels login
  1. 啟動閘道（保持執行）：
bash
moltbot gateway --port 18789
  1. 將最小配置放入 ~/.clawdbot/moltbot.json：
json5
{
  channels: { whatsapp: { allowFrom: ["+15555550123"] } }
}

現在從你的 allowlist 手機傳送訊息給助理號碼。

引導完成後，我們會自動開啟儀表板並附上你的閘道權杖，並列印權杖化連結。稍後重新開啟：moltbot dashboard。

為代理提供工作區（AGENTS） ​

Clawd 從其工作區目錄讀取操作說明和「記憶」。

預設情況下，Moltbot 使用 ~/clawd 作為代理工作區，並會在設定/首次代理執行時自動建立它（加上啟動器 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md）。BOOTSTRAP.md 僅在工作區全新時建立（刪除後不應回來）。

提示：將此資料夾視為 Clawd 的「記憶」，並使其成為 git 儲存庫（理想情況下為私有），以便備份你的 AGENTS.md + 記憶檔案。如果已安裝 git，全新工作區會自動初始化。

bash
moltbot setup

完整工作區佈局 + 備份指南：代理工作區 記憶工作流程：記憶

選用：使用 agents.defaults.workspace 選擇不同的工作區（支援 ~）。

json5
{
  agent: {
    workspace: "~/clawd"
  }
}

如果你已經從儲存庫提供自己的工作區檔案，你可以完全停用啟動檔案建立：

json5
{
  agent: {
    skipBootstrap: true
  }
}

將其變成「助理」的配置 ​

Moltbot 預設為良好的助理設定，但你通常會想要調整：

  • SOUL.md 中的角色/指示
  • 思考預設值（如果需要）
  • 心跳（一旦你信任它）

範例：

json5
{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-5",
    workspace: "~/clawd",
    thinkingDefault: "high",
    timeoutSeconds: 1800,
    // 從 0 開始；稍後啟用。
    heartbeat: { every: "0m" }
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }
      }
    }
  },
  routing: {
    groupChat: {
      mentionPatterns: ["@clawd", "clawd"]
    }
  },
  session: {
    scope: "per-sender",
    resetTriggers: ["/new", "/reset"],
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 10080
    }
  }
}

會話與記憶 ​

  • 會話檔案：~/.clawdbot/agents/<agentId>/sessions/.jsonl
  • 會話元資料（權杖使用、最後路由等）：~/.clawdbot/agents/<agentId>/sessions/sessions.json（舊版：~/.clawdbot/sessions/sessions.json）
  • /new 或 /reset 為該聊天啟動新會話（可透過 resetTriggers 配置）。如果單獨發送，代理會以簡短的問候回覆以確認重置。
  • /compact [instructions] 壓縮會話內容並報告剩餘內容預算。

心跳（主動模式） ​

預設情況下，Moltbot 每 30 分鐘執行一次心跳，提示為： Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK. 設定 agents.defaults.heartbeat.every: "0m" 以停用。

  • 如果 HEARTBEAT.md 存在但實際上是空的（僅空白行和 markdown 標題，如 # Heading），Moltbot 會跳過心跳執行以節省 API 呼叫。
  • 如果檔案缺失，心跳仍會執行，模型會決定要做什麼。
  • 如果代理以 HEARTBEAT_OK 回覆（可選地帶有短填充；參見 agents.defaults.heartbeat.ackMaxChars），Moltbot 會抑制該心跳的出站傳遞。
  • 心跳執行完整代理回合——較短的間隔會消耗更多權杖。
json5
{
  agent: {
    heartbeat: { every: "30m" }
  }
}

媒體輸入與輸出 ​

入站附件（圖片/音訊/文件）可以透過範本呈現給你的指令：

  • （本地暫存檔路徑）
  • （偽 URL）
  • （如果啟用音訊轉錄）

代理的出站附件：在自己的行上包含 MEDIA:<path-or-url>（無空格）。範例：

這是截圖。
MEDIA:/tmp/screenshot.png

Moltbot 會提取這些並將它們作為媒體與文字一起發送。

操作檢查清單 ​

bash
moltbot status          # 本地狀態（憑證、會話、排隊事件）
moltbot status --all    # 完整診斷（唯讀、可貼上）
moltbot status --deep   # 新增閘道健康探測（Telegram + Discord）
moltbot health --json   # 閘道健康快照（WS）

日誌位於 /tmp/moltbot/ 下（預設：moltbot-YYYY-MM-DD.log）。

下一步 ​

基於 MIT 授權發布

Copyright © 2026 Moltbot Taiwan