Clawdbot - 个人 AI 助手文档

1. 项目简介

Clawdbot 是一个自托管的个人 AI 助手，可连接多个消息平台。它采用本地优先的设计，通过基于 WebSocket 的网关作为控制平面，让用户无需依赖云服务即可部署自己的 AI 助手。

该平台提供"多渠道收件箱"功能，用户可通过自己偏好的消息服务进行交互，包括 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、BlueBubbles、Microsoft Teams、Matrix、Zalo 和 WebChat。

核心能力

多渠道收件箱 - 支持 13+ 消息平台
本地优先网关 - WebSocket 控制平面
多代理路由 - 工作区隔离
语音唤醒 + 对话模式 - 通过 ElevenLabs 支持 macOS/iOS/Android
实时画布 - A2UI 可视化工作区
浏览器自动化 - 专用 Chrome/Chromium 实例
设备节点 - 摄像头、屏幕录制、位置访问
自动化 - 定时任务、Webhook、Gmail Pub/Sub
技能平台 - 内置/托管/工作区技能
模型故障转移 - 会话清理
配套应用 - macOS 菜单栏、iOS/Android 节点

2. 系统架构

Clawdbot 采用中心辐射模型，单个网关（clawdbot gateway）作为中央协调器。所有消息渠道都通过该网关汇集，然后通过 WebSocket 连接将请求路由到代码代理、CLI、UI 应用和移动节点。

[消息平台]
    |
    v
[网关 WS 控制平面]
(ws://127.0.0.1:18789)
    |
    +-- Pi 代理运行时 (RPC 模式)
    +-- CLI 接口
    +-- WebChat UI
    +-- macOS 应用
    +-- iOS/Android 节点

关键组件

网关 - 本地优先的 WebSocket 服务器，管理会话、在线状态、配置和 Webhook
CLI - 网关、代理、消息发送、引导向导和诊断接口
Pi 代理 - 支持工具流和块流的运行时
多渠道收件箱 - 支持 13+ 平台

网络设计

推荐每台主机使用一个网关。本地回环优先，默认为 ws://127.0.0.1:18789。对于分布式访问，系统支持 SSH 隧道、Tailscale 和 VPN 配置。远程节点通过 WebSocket 连接到网关的控制平面。

3. 安装配置

系统要求：Node.js ≥ 22

快速安装

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

clawdbot onboard --install-daemon

启动网关

# 启动网关
clawdbot gateway --port 18789 --verbose

# 发送消息
clawdbot message send --to +1234567890 --message "你好，来自 Clawdbot"

# 查询助手
clawdbot agent --message "发货清单" --thinking high

# 诊断配置
clawdbot doctor

从源码安装

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm ui:build
pnpm build
pnpm clawdbot onboard --install-daemon
pnpm gateway:watch  # 开发模式，支持自动重载

发布渠道

渠道	说明	npm dist-tag
stable	正式版本 (vYYYY.M.D)	latest
beta	预发布版 (vYYYY.M.D-beta.N)	beta
dev	main 分支最新提交	dev

clawdbot update --channel stable|beta|dev

4. 配置说明

配置文件位置：~/.clawdbot/clawdbot.json

最小配置

{
  agent: {
    model: "anthropic/claude-opus-4-5"
  }
}

模型订阅

Clawdbot 支持通过 OAuth 认证使用 Anthropic（Claude）和 OpenAI 模型。项目强烈推荐使用 Anthropic Pro/Max 配合 Opus 4.5，以获得长上下文能力和更好的提示注入防护。

工作区结构

根目录：~/clawd（可通过 agents.defaults.workspace 配置）
注入的提示文件：AGENTS.md、SOUL.md、TOOLS.md
技能目录：~/clawd/skills/<skill>/SKILL.md

5. 支持的消息渠道

pnpm clawdbot channels login
# 凭证存储于 ~/.clawdbot/credentials

通过 channels.whatsapp.allowFrom 配置允许列表

{
  channels: {
    telegram: {
      botToken: "123456:ABCDEF"
    }
  }
}

或设置 TELEGRAM_BOT_TOKEN 环境变量。

Slack

需要 SLACK_BOT_TOKEN + SLACK_APP_TOKEN（环境变量或配置文件）。

Discord

{
  channels: {
    discord: {
      token: "1234abcd"
    }
  }
}

或设置 DISCORD_BOT_TOKEN 环境变量。

Signal

需要安装 signal-cli 并配置 channels.signal 部分。

iMessage

仅限 macOS；需要已登录 Messages 应用。通过 channels.imessage.groups 配置群组允许列表。

Microsoft Teams

需要 Teams 应用 + Bot Framework 设置及 msteams 配置。自 2026.1.15 起，需要 @clawdbot/msteams 插件。

其他渠道

Google Chat
BlueBubbles
Matrix（@clawdbot/matrix 插件）
Zalo（@clawdbot/zalo 插件）
Zalo 个人版（@clawdbot/zalouser 插件）
WebChat

6. 聊天指令

可在 WhatsApp、Telegram、Slack、Google Chat、Microsoft Teams 和 WebChat 中使用：

指令	说明
`/status`	显示会话状态（模型、Token、费用）
`/new` 或 `/reset`	清除会话历史
`/compact`	压缩会话上下文
`/think <级别>`	设置思考深度（off\|minimal\|low\|medium\|high\|xhigh）
`/verbose on\|off`	切换详细输出
`/usage off\|tokens\|full`	配置用量统计显示
`/restart`	重启网关（群组中仅管理员可用）
`/activation mention\|always`	切换群组通知模式

7. 安全机制

私信访问策略

默认将入站私信视为不可信输入：

配对模式 (dmPolicy="pairing")

未知发送者会收到配对码；机器人不处理初始消息。

clawdbot pairing approve <渠道> <配对码>

开放模式 (dmPolicy="open")

需要在 allowFrom 配置中显式设置 "*" 允许列表。

诊断：运行 clawdbot doctor 检测有风险的私信策略配置。

沙箱安全

针对群组/频道会话：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main"
      }
    }
  }
}

沙箱默认允许列表：bash、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn

沙箱默认拒绝列表：browser、canvas、nodes、cron、discord、gateway

8. 工具与能力

核心工具

浏览器控制 - 专用 Chrome/Chromium 实例
画布 - A2UI push/reset/eval/snapshot
节点 - 摄像头拍照/录像、屏幕录制、位置获取、通知
定时任务 - 计划自动化
Webhook - 外部触发器
Gmail Pub/Sub - 邮件触发器
技能平台 - 内置、托管、工作区级别

代理间协调

工具	说明
`sessions_list`	发现活跃会话及元数据
`sessions_history`	获取会话记录
`sessions_send`	向另一会话发送消息（可选回复）
`sessions_spawn`	创建新会话

9. 插件系统

插件通过模块化代码组件扩展 Clawdbot 功能。它们可以注册指令、工具、网关 RPC 方法、后台服务和消息渠道——全部在网关进程内运行。

CLI 指令

clawdbot plugins list
clawdbot plugins info <id>
clawdbot plugins install <路径>              # 本地文件/目录
clawdbot plugins install ./plugin.tgz        # tarball
clawdbot plugins install -l ./extensions/my  # 开发用符号链接
clawdbot plugins install @clawdbot/voice-call  # npm
clawdbot plugins update <id>
clawdbot plugins update --all
clawdbot plugins enable <id>
clawdbot plugins disable <id>
clawdbot plugins doctor

官方插件

Memory (Core) - 内置搜索（默认）
Memory (LanceDB) - 长期记忆，支持自动召回
Voice Call - @clawdbot/voice-call
Zalo 个人版 - @clawdbot/zalouser
Matrix - @clawdbot/matrix
Nostr - @clawdbot/nostr
Zalo - @clawdbot/zalo
Microsoft Teams - @clawdbot/msteams

插件配置

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } }
    }
  }
}

插件 API

插件可导出函数或对象：

// 函数形式
export default function (api) { ... }

// 对象形式
export default {
  id: "my-plugin",
  name: "My Plugin",
  configSchema: { ... },
  register(api) { ... }
}

注册网关 RPC 方法

export default function (api) {
  api.registerGatewayMethod("myplugin.status", ({ respond }) => {
    respond(true, { ok: true });
  });
}

注册自动回复指令

export default function (api) {
  api.registerCommand({
    name: "mystatus",
    description: "显示插件状态",
    handler: (ctx) => ({
      text: `插件运行中！渠道: ${ctx.channel}`,
    }),
  });
}

10. 钩子机制

钩子提供可扩展的事件驱动系统，用于响应代理指令和事件自动执行操作。它们是在特定事件发生时执行的小型脚本。

钩子发现

钩子按优先级从以下三个位置自动发现：

工作区专属钩子：<workspace>/hooks/
用户安装的钩子：~/.clawdbot/hooks/
内置钩子：随 Clawdbot 分发

内置钩子

session-memory - 执行 /new 时保留会话上下文
command-logger - 记录所有指令到 ~/.clawdbot/logs/commands.log
boot-md - 网关启动时执行 BOOT.md 中的指令
soul-evil - 引导期间条件性替换 SOUL.md 内容

事件类型

指令事件：command:new、command:reset、command:stop。其他事件类别包括代理引导事件和网关启动事件。

CLI 管理

clawdbot hooks list
clawdbot hooks enable <id>
clawdbot hooks info <id>

11. 测试体系

Clawdbot 实现了三套 Vitest 测试套件外加 Docker 运行器来验证功能。

测试套件

套件	指令	文件	说明
单元/集成	`pnpm test`	`src/*/.test.ts`	纯单元测试、进程内集成
E2E（网关）	`pnpm test:e2e`	`src/*/.e2e.test.ts`	多实例网关行为
线上	`pnpm test:live`	`src/*/.live.test.ts`	真实提供商/模型验证

快速开始

# 完整检查（提交前）
pnpm lint && pnpm build && pnpm test

# 带覆盖率
pnpm test:coverage

# E2E 套件
pnpm test:e2e

# 线上测试（需要凭证）
CLAWDBOT_LIVE_TEST=1 pnpm test:live

线上测试配置

# 单模型（直接）
CLAWDBOT_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts

# 单模型（网关）
CLAWDBOT_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

# 多提供商
CLAWDBOT_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-flash-preview" pnpm test:live

Docker 运行器

pnpm test:docker:live-models       # 直接模型
pnpm test:docker:live-gateway      # 网关 + 开发代理
pnpm test:docker:onboard           # 引导向导
pnpm test:docker:gateway-network   # 网关网络
pnpm test:docker:plugins           # 插件

12. Tailscale 集成

自动配置 Tailscale 以远程访问网关仪表板：

{
  gateway: {
    tailscale: {
      mode: "off|serve|funnel"
    },
    bind: "loopback"  // 必须保持 loopback
  }
}

模式说明

模式	说明
off	不启用 Tailscale 自动化（默认）
serve	仅限 Tailnet 的 HTTPS（默认启用身份头）
funnel	公开 HTTPS（需要密码认证）

13. 开发指南

仓库结构

.agent/workflows - 代理自动化工作流
apps/ - 应用源代码
src/ - 核心源文件
ui/ - 用户界面组件
skills/ - 技能模块
extensions/ - 渠道扩展
docs/ - 文档
test/ - 测试套件

技术栈

运行时：Node ≥22
包管理器：pnpm（推荐）、npm、bun
前端：React + TypeScript
构建工具：tsx、vitest
代码质量：Oxlint、Oxfmt

渠道 SDK

Baileys（WhatsApp）
grammY（Telegram）
Bolt（Slack）
discord.js（Discord）
signal-cli（Signal）
imsg（iMessage）

常用脚本

# 开发
pnpm gateway:watch    # 开发模式，支持自动重载
pnpm ui:dev          # UI 开发服务器
pnpm build           # 构建全部

# 测试
pnpm test            # 单元测试
pnpm test:coverage   # 带覆盖率
pnpm test:e2e        # 端到端
pnpm test:live       # 线上测试

# 代码质量
pnpm lint            # 代码检查
pnpm format          # 代码格式化