2026-01-27 16:31:20 +08:00

80 KiB

Raw Blame History

🦞 Clawdbot — 个人AI助手

蜕变！蜕变！

Clawdbot 是一款运行于自有设备的个人AI助手。它能在你日常使用的通讯渠道上与你互动（WhatsApp、Telegram、Slack、Discord、Signal、iMessage、Microsoft Teams、WebChat），还支持BlueBubbles、Matrix、Zalo及Zalo Personal等扩展渠道。在macOS/iOS/Android上可实现语音对话，并能渲染实时可控的Canvas界面。Gateway只是控制平面——产品核心在于助手本身。

如果你需要一款专属、单用户的助手，追求本地化、高速响应且常驻后台的体验，这就是为你打造的。

官网 · 文档 · 快速入门 · 更新指南 · 展示案例 · 常见问题 · 向导 · Nix · Docker · Discord社区

推荐配置方式：运行引导向导（clawdbot onboard）。它将引导你完成gateway、workspace、channels及skills的配置。CLI向导是推荐路径，支持macOS、Linux及Windows（通过WSL2；强烈推荐）。兼容npm、pnpm或bun。首次安装？从这里开始：快速入门

订阅服务（OAuth）：

Anthropic（Claude Pro/Max）
OpenAI（ChatGPT/Codex）

模型建议：虽然支持任意模型，但强烈推荐Anthropic Pro/Max（100/200）+ Opus 4.5，凭借其长上下文处理能力与更强的prompt-injection防护。详见入门指南。

模型（选择与认证）

模型配置与CLI：Models
认证配置轮换（OAuth vs API keys）与故障转移：Model failover

安装（推荐）

运行环境：Node ≥22。

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

clawdbot onboard --install-daemon

向导将安装Gateway守护进程（launchd/systemd用户服务），确保服务常驻运行。

快速启动（极简指南）

运行环境：Node ≥22。

完整新手教程（认证、配对、渠道）：快速入门

clawdbot onboard --install-daemon

clawdbot gateway --port 18789 --verbose

# 发送消息
clawdbot message send --to +1234567890 --message "Hello from Clawdbot"

# 与助手对话（可选：通过任意已连接渠道回传：WhatsApp/Telegram/Slack/Discord/Signal/iMessage/BlueBubbles/Microsoft Teams/Matrix/Zalo/Zalo Personal/WebChat）
clawdbot agent --message "Ship checklist" --thinking high

需要升级？更新指南（并运行 clawdbot doctor）。

开发渠道

stable：正式版本（vYYYY.M.D 或 vYYYY.M.D-<patch>），npm dist-tag latest。
beta：预发布版本（vYYYY.M.D-beta.N），npm dist-tag beta（macOS应用可能缺失）。
dev：main分支最新提交，npm dist-tag dev（发布时）。

切换渠道（git + npm）：clawdbot update --channel stable|beta|dev。详情：开发渠道。

源码安装（开发）

源码构建推荐使用pnpm。Bun可选，用于直接运行TypeScript。

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

pnpm install
pnpm ui:build # 首次运行自动安装UI依赖
pnpm build

pnpm clawdbot onboard --install-daemon

# 开发循环（TS变更自动重载）
pnpm gateway:watch

注意：pnpm clawdbot ... 直接运行TypeScript（通过tsx）。pnpm build 生成dist/目录，用于通过Node/打包的clawdbot二进制文件运行。

安全默认（DM访问）

Clawdbot连接真实的消息通讯界面。将入站DM视为不可信输入。

完整安全指南：Security

Telegram/WhatsApp/Signal/iMessage/Microsoft Teams/Discord/Slack的默认行为：

DM配对（dmPolicy="pairing" / channels.discord.dm.policy="pairing" / channels.slack.dm.policy="pairing"）：未知发送者收到配对码，助手不处理其消息。
批准方式：clawdbot pairing approve <channel> <code>（随后发送者被加入本地白名单）。
公开入站DM需显式选择启用：设置 dmPolicy="open" 并在渠道白名单中包含 "*"（allowFrom / channels.discord.dm.allowFrom / channels.slack.dm.allowFrom）。

运行 clawdbot doctor 可发现风险/配置错误的DM策略。

核心亮点

本地优先Gateway —— 会话、渠道、工具与事件的单一控制平面。
多渠道收件箱 —— WhatsApp、Telegram、Slack、Discord、Signal、iMessage、BlueBubbles、Microsoft Teams、Matrix、Zalo、Zalo Personal、WebChat、macOS、iOS/Android。
多代理路由 —— 将入站渠道/账户/会话路由至隔离的代理（workspaces + 每代理会话）。
语音唤醒 + 对话模式 —— macOS/iOS/Android的常驻语音，集成ElevenLabs。
实时Canvas —— 代理驱动的可视化工作区，支持A2UI。
一流工具 —— 浏览器、canvas、nodes、cron、会话及Discord/Slack操作。
配套应用 —— macOS菜单栏应用 + iOS/Android nodes。
引导安装 + Skills —— 向导式安装，支持捆绑/管理/workspaceSkills。

Star历史

已构建功能全景

核心平台

Gateway WS控制平面，含会话、状态、配置、cron、webhooks、Control UI及Canvas host。
CLI界面：gateway、agent、send、wizard及doctor。
Pi agent运行时（RPC模式），支持工具流与块流。
会话模型：main用于直接聊天，群组隔离，激活模式，队列模式，回复回传。群组规则：Groups。
媒体管道：图片/音频/视频，转录钩子，大小限制，临时文件生命周期。音频详情：Audio。

渠道

Channels：WhatsApp（Baileys）、Telegram（grammY）、Slack（Bolt）、Discord（discord.js）、Signal（signal-cli）、iMessage（imsg）、BlueBubbles（扩展）、Microsoft Teams（扩展）、Matrix（扩展）、Zalo（扩展）、Zalo Personal（扩展）、WebChat。
群组路由：提及门控、回复标签、每渠道分块与路由。渠道规则：Channels。

应用 + Nodes

macOS应用：菜单栏控制平面、Voice Wake/PTT、Talk Mode悬浮窗、WebChat、调试工具、remote gateway控制。
iOS node：Canvas、Voice Wake、Talk Mode、相机、屏幕录制、Bonjour配对。
Android node：Canvas、Talk Mode、相机、屏幕录制、可选SMS。
macOS node mode：system.run/notify + canvas/camera暴露。

工具 + 自动化

浏览器控制：专用clawd Chrome/Chromium，快照、操作、上传、配置文件。
Canvas：A2UI push/reset、eval、快照。
Nodes：相机快照/剪辑、屏幕录制、location.get、通知。
Cron + 唤醒；webhooks；Gmail Pub/Sub。
Skills平台：捆绑、管理及workspaceSkills，含安装门控与UI。

运行时 + 安全

运维 + 打包

Control UI + WebChat由Gateway直接提供。
Tailscale Serve/Funnel或SSH隧道，支持token/密码认证。
Nix模式用于声明式配置；Docker安装。
Doctor迁移、日志。

工作原理（简述）

WhatsApp / Telegram / Slack / Discord / Signal / iMessage / BlueBubbles / Microsoft Teams / Matrix / Zalo / Zalo Personal / WebChat
               │
               ▼
┌───────────────────────────────┐
│            Gateway            │
│       （控制平面）             │
│     ws://127.0.0.1:18789      │
└──────────────┬────────────────┘
               │
               ├─ Pi agent（RPC）
               ├─ CLI（clawdbot …）
               ├─ WebChat UI
               ├─ macOS应用
               └─ iOS / Android nodes

关键子系统

Gateway WebSocket网络 —— 面向客户端、工具及事件的单一WS控制平面（运维详见：Gateway runbook）。
Tailscale暴露 —— 通过Serve/Funnel暴露Gateway仪表板与WS（远程访问：Remote）。
浏览器控制 —— clawd托管的Chrome/Chromium，支持CDP控制。
Canvas + A2UI —— 代理驱动的可视化工作区（A2UI宿主：Canvas/A2UI）。
Voice Wake + Talk Mode —— 常驻语音与连续对话。
Nodes —— Canvas、相机快照/剪辑、屏幕录制、location.get、通知，以及macOS专属的system.run/system.notify。

Tailscale访问（Gateway仪表板）

Clawdbot可自动配置Tailscale Serve（仅tailnet）或 Funnel（公开），同时Gateway保持绑定到loopback。配置gateway.tailscale.mode：

off：不启用Tailscale自动化（默认）。
serve：通过tailscale serve实现仅tailnet的HTTPS（默认使用Tailscale身份header）。
funnel：通过tailscale funnel实现公开HTTPS（需要共享密码认证）。

注意：

启用Serve/Funnel时，gateway.bind必须保持为loopback（Clawdbot会强制此设置）。
通过设置gateway.auth.mode: "password"或gateway.auth.allowTailscale: false，可强制Serve要求密码。
除非设置了gateway.auth.mode: "password"，否则Funnel拒绝启动。
可选：gateway.tailscale.resetOnExit可在关闭时撤销Serve/Funnel。

详情：Tailscale指南 · Web界面

Remote Gateway（Linux表现优异）

在小型Linux实例上运行Gateway完全可行。客户端（macOS应用、CLI、WebChat）可通过Tailscale Serve/Funnel或SSH隧道连接，你仍可配对设备nodes（macOS/iOS/Android）以在需要时执行设备本地操作。

Gateway主机默认运行exec工具与渠道连接。
设备Nodes通过node.invoke运行设备本地操作（system.run、相机、屏幕录制、通知）。简而言之：exec在Gateway所在位置运行；设备操作在设备所在位置运行。

详情：远程访问 · Nodes · Security

通过Gateway协议的macOS权限

macOS应用可在node mode下运行，通过Gateway WebSocket（node.list / node.describe）广播其能力+权限映射。客户端随后可通过node.invoke执行本地操作：

system.run运行本地命令并返回stdout/stderr/退出码；设置needsScreenRecording: true以要求屏幕录制权限（否则返回PERMISSION_MISSING）。
system.notify发布用户通知，如通知被拒则失败。
canvas.*、camera.*、screen.record及location.get也通过node.invoke路由，遵循TCC权限状态。

提升bash（主机权限）与macOS TCC权限是分开的：

使用/elevated on|off在启用+白名单后切换每会话的提权访问。
Gateway通过sessions.patch（WS方法）持久化每会话开关，与thinkingLevel、verboseLevel、model、sendPolicy及groupActivation一并存储。

详情：Nodes · macOS应用 · Gateway协议

Agent to Agent（sessions_* 工具）

用于跨会话协调工作，无需在聊天界面间切换。
sessions_list —— 发现活跃会话（agents）及其元数据。
sessions_history —— 获取会话的转录日志。
sessions_send —— 向另一会话发送消息；可选回复回传ping-pong + 公告步骤（REPLY_SKIP、ANNOUNCE_SKIP）。

详情：Session工具

Skills注册表（ClawdHub）

ClawdHub是最小化的Skills注册表。启用ClawdHub后，代理可自动搜索Skills并按需拉取新Skills。

ClawdHub

聊天命令

在WhatsApp/Telegram/Slack/Microsoft Teams/WebChat中发送（群组命令仅限所有者）：

/status —— 紧凑会话状态（模型 + tokens，成本如可用）
/new 或 /reset —— 重置会话
/compact —— 压缩会话上下文（摘要）
/think <level> —— off|minimal|low|medium|high|xhigh（仅限GPT-5.2 + Codex模型）
/verbose on|off
/usage off|tokens|full —— 每响应用量页脚
/restart —— 重启gateway（群组中仅限所有者）
/activation mention|always —— 群组激活切换（仅群组）

应用（可选）

仅Gateway即可提供出色体验。所有应用均为可选，用于添加额外功能。

如计划构建/运行配套应用，请遵循以下平台运行手册。

macOS（Clawdbot.app）（可选）

菜单栏控制Gateway与健康状态。
Voice Wake + 一键通悬浮窗。
WebChat + 调试工具。
通过SSH远程控制gateway。

注意：macOS权限需在签名构建后才能跨重建保持（见docs/mac/permissions.md）。

iOS node（可选）

通过Bridge作为node配对。
语音触发转发 + Canvas界面。
通过clawdbot nodes …控制。

运行手册：iOS连接。

Android node（可选）

通过相同Bridge + 配对流程与iOS配对。
暴露Canvas、Camera及Screen capture命令。
运行手册：Android连接。

Agent workspace + Skills

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

配置

最小化配置 ~/.clawdbot/clawdbot.json（模型 + 默认值）：

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

完整配置参考（所有键 + 示例）。

安全模型（重要）

默认：工具在main会话的主机上运行，因此仅你本人使用时代理拥有完全访问权限。
群组/渠道安全：设置agents.defaults.sandbox.mode: "non-main"以在非main会话（群组/渠道）内运行每会话Docker沙箱；这些会话的bash将在Docker中运行。
**沙箱默认值：**白名单bash、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn；黑名单browser、canvas、nodes、cron、discord、gateway。

详情：安全指南 · Docker + 沙箱 · 沙箱配置

链接设备：pnpm clawdbot channels login（凭证存储于~/.clawdbot/credentials）。
通过channels.whatsapp.allowFrom白名单可访问助手的人员。
如设置channels.whatsapp.groups，则变为群组白名单；包含"*"以允许所有群组。

设置TELEGRAM_BOT_TOKEN或channels.telegram.botToken（环境变量优先）。
可选：设置channels.telegram.groups（含channels.telegram.groups."*".requireMention）；设置后即为群组白名单（包含"*"以允许所有群组）。另可设置channels.telegram.allowFrom或channels.telegram.webhookUrl。

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

Slack

设置SLACK_BOT_TOKEN + SLACK_APP_TOKEN（或channels.slack.botToken + channels.slack.appToken）。

Discord

设置DISCORD_BOT_TOKEN或channels.discord.token（环境变量优先）。
可选：设置commands.native、commands.text或commands.useAccessGroups，以及channels.discord.dm.allowFrom、channels.discord.guilds或channels.discord.mediaMaxMb。

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

Signal

需要signal-cli及channels.signal配置段。

iMessage

仅限macOS；Messages必须已登录。
如设置channels.imessage.groups，则变为群组白名单；包含"*"以允许所有群组。

Microsoft Teams

配置Teams应用 + Bot Framework，然后添加msteams配置段。
通过msteams.allowFrom白名单可访问人员；群组访问通过msteams.groupAllowFrom或msteams.groupPolicy: "open"。

WebChat

使用Gateway WebSocket；无独立WebChat端口/配置。

浏览器控制（可选）：

{
  browser: {
    enabled: true,
    controlUrl: "http://127.0.0.1:18791",
    color: "#FF4500"
  }
}

文档

完成引导流程后，使用以下深度参考文档。

高级文档（发现 + 控制）

运维与故障排查

深度解析

Workspace与Skills

平台内部机制

邮件钩子（Gmail）

docs.clawd.bot/gmail-pubsub

Clawd

Clawdbot专为Clawd——一个懂你的AI助手而打造。🦞
作者：Peter Steinberger及社区贡献者。

社区

贡献指南、维护者及PR提交方式详见CONTRIBUTING.md。
欢迎AI/vibe-coded PR！🤖

特别感谢Mario Zechner的支持及pi-mono。

感谢所有贡献者：

80 KiB Raw Blame History Unescape Escape