Clawdbot (Moltbot) 操作詳細指南

歡迎使用 Clawdbot (Moltbot)。這是一個強大的 AI 自動化工具，旨在幫助你自動化日常任務，對接多種消息平台，並賦能你的 AI 代理「實操」能力。

👋 快速開始

Clawdbot 不僅僅是一個對話機器人，它是你的數位操作員。通過本指南，你將學會如何從零開始部署、配置並擴展它的能力。

💡 小撇步： 建議新手從左側的「安裝與更新」開始閱讀，確保你的本地環境已正確設置。

🚀 安裝與更新

了解如何安裝 Clawdbot 並始終保持在最新狀態。

📥 初始安裝

推薦使用官方一鍵安裝腳本，它會自動處理環境依賴（Node.js 22+）：

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

第一次啟動：Onboarding

執行以下指令進入引導式設置，這將幫你初始化 Workspace：

clawdbot onboard

🔄 更新方法

全局更新：

clawdbot update

原始碼 (Git) 安裝更新：

git pull && pnpm install && pnpm build && pnpm ui:build

⚙️ 配置與環境

深度定制你的運行環境。

📁 配置文件與路徑

核心配置: ~/.clawdbot/moltbot.json
技能目錄: ~/.clawdbot/skills
日誌目錄: /tmp/moltbot/

🌍 關鍵環境變數

變數名	描述	預設值
`CLAWDBOT_CONFIG_PATH`	強制定制配置文件路徑	`~/.clawdbot/moltbot.json`
`CLAWDBOT_STATE_DIR`	數據狀態目錄	`~/.clawdbot`
`CLAWDBOT_GATEWAY_PORT`	Gateway 監聽端口	`18789`
`LOG_LEVEL`	日誌級別 (info, debug, warn, error)	`info`

📑 JSON 配置示例

{
  "channels": {
    "whatsapp": { "dmPolicy": "pairing" },
    "telegram": { "accounts": [ { "id": "me", "token": "..." } ] }
  },
  "logging": { "consoleStyle": "pretty" }
}

💻 指令參考大全

Clawdbot / Moltbot 完整指令速查表。

💬 聊天常用 (Slash Commands)

指令	功能描述
`/help`	顯示指南與幫助
`/status`	查看運行狀態與配額
`/model <name>`	即時切換 AI 模型
`/reset`	重置對話上下文 (New Session)
`/think <level>`	調整模型思考深度
`/elevated on\|off`	開啟/關閉高權限模式

🛠️ CLI 管理指令

指令	功能描述
`moltbot onboard`	啟動圖形/引導式設置嚮導
`moltbot doctor`	診斷環境依賴與修復
`moltbot gateway`	手動啟動後端 Gateway
`moltbot channels login`	登錄 WhatsApp/渠道 (掃碼)

🧩 技能與插件系統

透過高度可擴展的機制強化 AI 代理的能力。

💡 Skills vs Plugins

Type	描述	適用場景
技能 (Skill)	具備具體功能的工具集 (Tools)	搜網、跑代碼、查文檔
插件 (Plugin)	底層核心擴展	傳輸渠道、攔截消息、系統掛鉤

🛒 ClawdHub 技能管理

使用官方技能管理器輕鬆安裝：

clawdhub install <skill-name>
clawdhub update --all

🔑 如何配置 API Key

安裝技能後，若需要 API Key（如 OpenAI, GitHub），請在 moltbot.json 的 skills.entries 中配置：

{
  "skills": {
    "entries": {
      "github": {
        "apiKey": "你的_TOKEN_HERE",
        "env": { "CUSTOM_VAR": "value" }
      }
    }
  }
}

⚖️ 載入優先順序 (Precedence)

Workspace 局部技能 (Workspace Skills)
用戶全域技能 (~/.clawdbot/skills)
內置核心技能 (Bundled Skills)

🌐 技能生態系 (Ecosystem)

探索由社群參與貢獻的豐富技能庫。Moltbot (原 Clawdbot) 的能力由你定義。

🌟 更多技能： 訪問 Awesome Moltbot Skills 獲取完整清單並參與貢獻。

🤖 Telegram 與代理管理

連接消息平台並管理多個 AI 身份。

✈️ Telegram 連接

從 @BotFather 獲取 Token。
運行 clawdbot onboard 並填入 Token。
啟動 Gateway 即可通訊。

💬 會話與代理管理

理解會話隔離、多代理路由與子代理系統。

🧠 會話概念

Clawdbot 使用會話隔離來管理不同對話的上下文：

主會話： 所有私聊共用同一個會話（預設行為），保持連續性。
群組會話： 每個群組/頻道獨立會話，互不干擾。
子代理： 在背景啟動獨立會話處理長任務。

📋 會話範圍控制

{
  "session": {
    "dmScope": "main",  // main | per-peer | per-channel-peer
    "mainKey": "main"
  }
}

dmScope 選項：

main（預設）：所有私聊共用主會話
per-peer：按發送者隔離
per-channel-peer：按頻道+發送者隔離（推薦多用戶收件匣）

🔧 子代理系統

使用 /subagents 指令管理子代理：

指令	功能
`/subagents list`	列出所有運行中的子代理
`/subagents stop <id>`	停止指定的子代理
`/subagents log <id>`	查看子代理日誌
`/subagents send <id> <msg>`	向子代理發送消息

🔄 會話重置策略

{
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 120
    }
  }
}

重置模式：

daily：每天指定時間重置
idle：空閒指定分鐘數後重置
同時設置時，先到期者觸發

⏰ 自動化與定時任務

使用 Cron 和 Heartbeat 實現自動化工作流。

📅 Cron 定時任務

Cron 是 Gateway 內建的定時器，支援一次性提醒和週期性任務：

一次性提醒

# 20 分鐘後提醒
moltbot cron add --name "提醒" --at "20m" --session main \\
  --system-event "提醒我：提交報告" --wake now

週期性任務

# 每天早上 7 點發送 WhatsApp 摘要
moltbot cron add --name "晨間摘要" --cron "0 7 * * *" \\
  --session isolated --message "總結今天的重要資訊" \\
  --deliver --channel whatsapp --to "+15551234567"

💓 Heartbeat 心跳機制

Heartbeat 是週期性檢查的批次處理機制，適合多個輕量級任務：

特性	Cron	Heartbeat
精確時間	✅	❌
批次處理	❌	✅
主會話上下文	選擇性	✅
獨立隔離	✅	❌

使用 Cron 當：

需要精確時間（"每天 9:00 AM"）
一鍵提醒（"20 分鐘後提醒我"）
需要完全隔離的會話

使用 Heartbeat 當：

多個檢查可以批次處理
需要對話上下文
時間可以輕微漂移

🔧 Cron 管理指令

# 列出所有任務
moltbot cron list

# 手動執行任務
moltbot cron run <jobId> --force

# 編輯任務
moltbot cron edit <jobId> --message "新提示" --model "opus"

# 刪除任務
moltbot cron remove <jobId>

🚀 高級功能模組

探索 Canvas、Nodes、瀏覽器控制等強大功能。

🖼️ Canvas 系統

Canvas 可以在節點上展示 HTML 頁面並進行快照：

# 展示網頁
moltbot nodes canvas present --node <id> --target https://example.com

# 快照截圖
moltbot nodes canvas snapshot --node <id> --format png

# 導航到新 URL
moltbot nodes canvas navigate --node <id> https://example.com

📱 Nodes 節點管理

Nodes 是連接到 Gateway 的設備（iOS/Android/macOS）：

# 列出所有節點
moltbot nodes list

# 查看節點詳情
moltbot nodes describe --node <id>

# 相機拍照
moltbot nodes camera snap --node <id> --facing front

# 錄製屏幕
moltbot nodes screen record --node <id> --duration 10s

🌐 瀏覽器控制

透過瀏覽器工具自動化網頁操作：

# 啟動瀏覽器
moltbot browser start

# 導航到網頁
moltbot browser open https://example.com

# 快照頁面
moltbot browser snapshot

# 執行動作
moltbot browser act --kind click --targetId "submit-btn"

🔊 語音合成 (TTS)

使用 ElevenLabs 生成自然語音：

# 對話中開啟 TTS
/tts always

# 標記需要語音
/message "這段話用語音說" --tts

🔌 渠道深度配置

詳細配置各個消息平台的功能與限制。

✈️ Telegram 配置

Telegram 支援豐富的功能：

內聯按鈕： 發送帶按鈕的訊息
投票： 創建投票並收集結果
回覆： 回覆指定訊息
表情反應： 添加表情反應

💬 WhatsApp 配置

WhatsApp 使用 Web 協議連接：

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

🎮 Discord 配置

Discord 支援伺服器和語音頻道：

{
  "channels": {
    "discord": {
      "token": "YOUR_BOT_TOKEN",
      "commands": {
        "native": true
      }
    }
  }
}

🧠 記憶系統

理解短期記憶與長期記憶的區別與使用方法。

📋 記憶類型

類型	位置	用途
Daily Notes	`memory/YYYY-MM-DD.md`	原始日誌，詳細記錄
Long-term	`MEMORY.md`	策展記憶，精煉智慧

💡 最佳實踐

記錄重要事件： 決策、偏好、教訓
定期整理： 每幾天審查 daily notes 並更新 MEMORY.md
安全考量： 主會話載入，群聊不載入（防止洩密）

🔍 記憶檢索

AI 會自動檢索相關記憶：

# 搜尋關鍵字
memory_search "關於 X 的決策"

# 讀取特定行
memory_get MEMORY.md --from 1 --lines 50

🔧 故障排查與調試

常見問題與解決方案。

🩺 診斷工具

# 檢查狀態
moltbot status

# 健康檢查
moltbot health

# 安全審計
moltbot security audit

❓ 常見問題

Gateway 無法啟動

檢查端口是否被佔用：

lsof -i :18789

訊息無回應

檢查認證配置：

moltbot pairing list
moltbot pairing approve <channel> <code>

技能無法載入

檢查依賴：

moltbot doctor

💻 開發者指南

如何開發自定義技能與插件。

📝 開發自定義技能

技能是包含 SKILL.md 的目錄：

my-skill/
├── SKILL.md
├── package.json
└── index.js

SKILL.md 格式：

---
name: my-skill
description: 我的自定義技能
metadata: {"moltbot":{"requires":{"bins":["node"]}}}
---

這是技能的指令內容...

🔌 開發插件

插件擴展核心功能（新增渠道等）：

my-plugin/
├── moltbot.plugin.json
├── package.json
└── src/
    └── channel.js

🧪 測試與調試

# 本地測試技能
moltbot skill test ./my-skill

# 查看日誌
tail -f /tmp/moltbot/moltbot-*.log

🔒 安全與合規

保護你的資料與系統安全。

🛡️ 安全審計

定期運行安全審計：

moltbot security audit
moltbot security audit --deep
moltbot security audit --fix

📜 安全規則

訪問控制優先： 先決定誰可以對話，再決定可以做什麼
沙箱執行： 敏感工具在沙箱中運行
最小權限： 只給予必要的訪問權限
日誌審計： 定期檢查工具調用日誌

🚨 事故響應

如果懷疑被入侵：

停止 Gateway
鎖定訪問控制
輪換所有金鑰
審計日誌
重新審計安全