Clawdbot

从这里开始

• 新手从零安装：入门指南
• 推荐流程：向导（`clawdbot onboard`）
• 打开控制台（本地网关）：127.0.0.1:18789（或 localhost:18789）

如果网关和浏览器在同一台机器上，上述链接会直接打开浏览器控制台；如果打不开，请先执行 `clawdbot gateway`。

控制台（浏览器界面）

控制台是浏览器界面，用于聊天、配置、节点管理、会话查看等。默认本地地址：127.0.0.1:18789。 远程访问可参考网页入口与Tailscale。

工作原理

WhatsApp / Telegram / Discord / iMessage (+ 插件)
        │
        ▼
┌───────────────────────────┐
│           网关            │  ws://127.0.0.1:18789（仅回环）
│       （唯一真源）        │
│                           │  http://<gateway-host>:18793
│                           │    /__clawdbot__/canvas/（画布）
└───────────┬───────────────┘
            │
            ├─ Pi 代理（RPC）
            ├─ 命令行（clawdbot ...）
            ├─ Chat UI（SwiftUI）
            ├─ macOS 应用（Clawdbot.app）
            ├─ iOS 节点（WS + 配对）
            └─ Android 节点（WS + 配对）

大多数操作都通过网关（`clawdbot gateway`）完成：它是唯一持有渠道连接与控制平面的长期进程。

网络模型

• 建议每台主机只运行一个网关（推荐）：它是唯一允许持有 WhatsApp Web 会话的进程。
• 默认回环地址：网关 WS 为 `ws://127.0.0.1:18789`。
• 向导默认会生成网关令牌（即便是回环模式）。
• Tailnet 访问：`clawdbot gateway --bind tailnet --token ...`（非回环必须携带 token）。
• 节点通过网关 WebSocket 接入（LAN/Tailnet/SSH）；旧 TCP 桥已弃用。
• 画布服务由 `canvasHost.port`（默认 18793）提供，路径 `/__clawdbot__/canvas/`。
• 远程访问可用 SSH 隧道或 Tailnet/VPN；可参考远程与发现文档。

功能概览（高层）

• WhatsApp 集成：基于 Baileys 的 WhatsApp Web 协议
• ✈️ Telegram 机器人：通过 grammY 支持私聊与群组
• Discord 机器人：支持私信与频道
• Mattermost 插件：Bot Token + WebSocket 事件
• iMessage：本地 imsg CLI（macOS）
• 代理桥接：Pi（RPC）+ 工具流式输出
• ⏱️ 流式输出：分块流式 + Telegram 草稿流式
• 多代理路由：按工作区/代理隔离
• 订阅授权：Anthropic（Claude Pro/Max）+ OpenAI（ChatGPT/Codex）OAuth
• 会话模型：私聊合并为 main，群聊隔离
• 群聊支持：默认 @ 提及，可切换 `/activation always|mention`
• 多媒体支持：图片/音频/文档
• 语音留言：可选转写钩子
• WebChat + macOS 应用：本地 UI + 菜单栏伴随与语音唤醒
• iOS 节点：配对后提供画布
• Android 节点：画布 + 聊天 + 相机

快速开始

运行环境要求：Node ≥ 22。

# 推荐：全局安装（npm/pnpm）
npm install -g clawdbot@latest
# 或：pnpm add -g clawdbot@latest

# 向导 + 安装后台服务（launchd/systemd user service）
clawdbot onboard --install-daemon

# 配对 WhatsApp Web（展示二维码）
clawdbot channels login

# 网关会随服务启动；也可手动启动：
clawdbot gateway --port 18789

后续切换 npm 与 git 安装很简单：安装另一种方式后运行 `clawdbot doctor` 更新网关服务入口。

源码安装（开发）：

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm ui:build # 首次运行会自动安装 UI 依赖
pnpm build
clawdbot onboard --install-daemon

如果没有全局安装，可以在仓库里用 `pnpm clawdbot ...` 运行向导。

多实例快速启动（可选）：

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

发送测试消息（需要网关运行）：

clawdbot message send --target +15555550123 --message "Hello from Clawdbot"

配置（可选）

配置文件路径：`~/.clawdbot/clawdbot.json`。

• 默认使用打包的 Pi 二进制（RPC 模式），按发送者分离会话。
• 如需限制访问，先设置 `channels.whatsapp.allowFrom`，并为群聊开启提及规则。

示例：

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

文档入口

命名由来

Clawdbot = CLAW + TARDIS — 每一只太空龙虾都需要一台穿越时空的机器。

“我们都在和自己的提示词玩耍。” —— 某位 AI（大概）

致谢

• Peter Steinberger — 创作者、龙虾低语者
• Mario Zechner — Pi 创建者、安全测试
• Clawd — 负责催促改名的太空龙虾

核心贡献者

• Maxim Vovshin — Blogwatcher 技能
• Nacho Iacovino — 定位解析（Telegram + WhatsApp）

许可证

MIT — 像海里的龙虾一样自由。