Clawd（个人助理方案）

概览

Clawdbot 将 WhatsApp/Telegram/Discord/iMessage 接入 Pi 代理。此文档是“个人助理”路线：一个专用 WhatsApp 号码。

安全优先

• 务必设置 channels.whatsapp.allowFrom
• 使用单独的 WhatsApp 号码
• 心跳默认 30 分钟；在确认安全前可设为 agents.defaults.heartbeat.every: "0m"

前置条件

• Node 22+
• PATH 可用的 clawdbot
• 第二个手机号（SIM/eSIM）

npm install -g clawdbot@latest
# 或 pnpm add -g clawdbot@latest

双手机方案（推荐）

个人手机 → 助理号码 → 扫码绑定到 Clawdbot。不要用个人号绑定，否则所有消息都会变成 agent 输入。

5 分钟快速开始

clawdbot login
clawdbot gateway --port 18789

最小配置（示例）：

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"]
    }
  }
}

工作区与配置

默认工作区 ~/clawd，首次运行会生成 AGENTS/IDENTITY/USER/SOUL 等文件。

将其配置为“助理”样式（示例）：

{
  "agent": {
    "heartbeat": { "every": "0m" }
  },
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"],
      "groups": { "*": { "requireMention": true } }
    }
  },
  "routing": {
    "groupChat": { "mentionPatterns": ["@clawd", "clawd"] }
  },
  "session": {
    "scope": "per-sender",
    "resetTriggers": ["/new", "/reset"],
    "idleMinutes": 10080
  }
}

会话与记忆

• 会话：~/.clawdbot/agents/<agentId>/sessions/<SessionId>.jsonl
• 元信息：~/.clawdbot/agents/<agentId>/sessions/sessions.json
• /new 或 /reset 可开始新会话
• /compact [instructions] 压缩上下文

心跳（主动模式）

默认每 30 分钟触发；返回 HEARTBEAT_OK 会抑制输出。间隔越短消耗越多。

{
  "agent": {
    "heartbeat": { "every": "30m" }
  }
}

媒体收发

• 入站模板：{{MediaPath}} / {{MediaUrl}} / {{Transcript}}
• 出站媒体：在回复中单独一行 MEDIA:<path-or-url>

运维检查

clawdbot status
clawdbot status --deep
clawdbot health --json

日志默认在 /tmp/clawdbot/。