Clawdbot 是一个开源的本地优先个人 AI 助手项目，设计目标是让用户在自有设备上运行一个完全可控的智能助手。项目在 GitHub 上热度颇高，拥有超过 15.4k 的星标，采用宽松的 MIT 开源协议。
它的核心理念是 “Local-first”，所有控制逻辑与数据都运行在用户自己的设备上，不依赖云端服务。它支持连接 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams 等数十个主流消息平台，并通过一个统一的控制平面进行管理。
本文将深入代码层面，拆解 Clawdbot 的技术实现原理，重点关注其模块化架构设计与核心模块的实现细节。
整体架构
Clawdbot 的代码仓库位于 https://github.com/clawdbot/clawdbot。项目主要使用 TypeScript 编写，运行时要求 Node.js 版本 ≥22，并采用 pnpm 作为包管理器，代码结构清晰，模块化程度很高。
从 src/ 目录的组织来看，系统主要由以下核心模块构成：
| 模块目录 |
功能职责 |
src/gateway/ |
WebSocket 控制平面，管理连接、会话、配置和事件 |
src/agents/ |
AI 代理运行时，处理消息并调用 LLM 和工具 |
src/channels/ |
多渠道消息适配器，对接不同的通信平台 |
src/browser/ |
浏览器控制模块，通过 CDP 协议控制 Chrome |
src/canvas-host/ |
Canvas 渲染服务，托管 A2UI 可视化界面 |
src/nodes/ |
设备节点管理，与 iOS/Android/macOS 应用通信 |
src/cli/ |
命令行界面，提供用户交互入口 |
src/config/ |
配置管理系统 |
src/sessions/ |
会话管理，维护对话上下文 |
这些模块通过 Gateway 这个中心枢纽进行协调。所有客户端（CLI、macOS 应用、移动应用）都通过 WebSocket 连接到 Gateway，再由 Gateway 负责将请求路由到对应的处理模块。
Gateway 控制平面实现
启动机制
Gateway 的启动逻辑在 src/gateway/boot.ts 文件中。这里有一个巧妙的设计：系统启动时会检查工作目录下是否存在 BOOT.md 文件。如果文件存在且内容不为空，则会将其内容作为指令交给 Agent 执行。
src/gateway/boot.ts 中的核心函数 runBootOnce 实现了以下逻辑：
export async function runBootOnce(params: {
cfg: ClawdbotConfig;
deps: CliDeps;
workspaceDir: string;
}): Promise<BootRunResult>
该函数首先调用 loadBootFile 函数读取 BOOT.md 文件：
async function loadBootFile(
workspaceDir: string,
): Promise<{ content?: string; status: "ok" | "missing" | "empty" }>
如果文件存在且非空，则会构建一个特殊提示词，并通过 agentCommand 函数（位于 src/commands/agent.js）将任务提交给 Agent 执行。这意味着用户可以通过编辑一个 Markdown 文件来定义启动时需要自动执行的任务。
函数返回值类型定义如下：
export type BootRunResult =
| { status: "skipped"; reason: "missing" | "empty" }
| { status: "ran" }
| { status: "failed"; reason: string };
WebSocket 服务
Gateway 的 WebSocket 服务器实现位于 src/gateway/server/ 目录。从结构看，包含几个关键部分：
src/gateway/server-methods/ - 定义了各种 RPC 方法的处理逻辑src/gateway/protocol/ - 定义了通信协议的数据结构src/gateway/auth.ts - 实现了连接认证逻辑
Gateway 通过 WebSocket 提供实时双向通信能力。客户端连接后，可以发送如 agent:run、config:get、session:send 等类型的消息，Gateway 会根据消息类型将请求分发到对应的处理函数。
认证与安全
src/gateway/auth.ts 文件实现了连接认证机制。客户端尝试建立 WebSocket 连接时必须提供有效的认证凭证，只有通过验证的连接才会被接受。
此外，src/gateway/device-auth.ts 文件处理设备级别的认证，确保只有授权的设备可以连接到 Gateway。
Agent 运行时实现
Pi Agent 架构
Agent 的核心实现位于 src/agents/ 目录，这里包含了完整的 AI 代理运行时，被称为 Pi Agent。
关键子目录包括：
src/agents/pi-embedded-runner/ - Pi Agent 的嵌入式运行器src/agents/pi-embedded-helpers/ - 运行时辅助函数src/agents/pi-extensions/ - Agent 扩展机制src/agents/tools/ - 工具集合src/agents/skills/ - 技能系统src/agents/sandbox/ - 沙箱隔离环境
Agent 的标准工作流程是：接收用户消息 → 构建包含工具列表的提示词 → 调用 LLM → 解析 LLM 响应 → 执行工具调用 → 将结果反馈给 LLM → 循环直到任务完成。
认证配置管理
src/agents/auth-profiles/ 目录实现了多认证配置管理。Clawdbot 支持同时配置多个 LLM 提供商（如 Anthropic、OpenAI）的认证信息，并在运行时根据配置动态选择。
相关文件包括：
src/agents/auth-health.ts - 检查认证配置的健康状态src/agents/auth-profiles.*.test.ts - 认证配置的测试用例
沙箱机制
src/agents/sandbox/ 目录实现了代码执行的沙箱隔离。当 Agent 需要执行可能存在风险的操作时，这些操作会在隔离的 Docker 容器中进行。
项目根目录下的 Dockerfile.sandbox 和 Dockerfile.sandbox-browser 定义了两类沙箱容器：
Dockerfile.sandbox - 通用的代码执行沙箱Dockerfile.sandbox-browser - 带有浏览器环境的沙箱，用于需要操作网页的任务
多渠道通信系统
插件化架构
Clawdbot 对多平台消息的支持通过插件化架构实现，核心代码在 src/channels/plugins/ 目录下。每个消息平台都有对应的插件实现。
插件目录结构清晰：
src/channels/plugins/actions/ - 渠道操作定义src/channels/plugins/agent-tools/ - 渠道相关的 Agent 工具src/channels/plugins/normalize/ - 消息标准化处理src/channels/plugins/onboarding/ - 渠道引导流程src/channels/plugins/outbound/ - 出站消息处理src/channels/plugins/status-issues/ - 状态问题处理
关键文件包括：
src/channels/plugins/catalog.ts - 插件注册表src/channels/plugins/config-schema.ts - 插件配置模式定义src/channels/plugins/channel-config.ts - 渠道配置管理
消息标准化
src/channels/plugins/normalize/ 目录负责将不同平台的原生消息格式转换为统一的内部表示。这样，后端的 Agent 和 Gateway 只需要处理标准化的消息对象，无需关心消息具体来自哪个平台。
安全控制
src/channels/allowlists/ 目录实现了白名单机制。相关文件包括：
src/channels/allowlist-match.ts - 白名单匹配逻辑src/channels/mention-gating.ts - 提及门控（在群组中需要 @ 机器人它才响应）src/channels/command-gating.ts - 命令门控
src/pairing/ 目录则实现了私信配对机制。当陌生用户首次发送私信时，系统会生成一个配对码，只有管理员批准后，该用户才能正常使用机器人功能。
浏览器控制实现
CDP 协议封装
浏览器控制功能位于 src/browser/ 目录，其核心实现基于 Chrome DevTools Protocol (CDP)。
关键文件包括：
src/browser/cdp.ts - CDP 协议的核心封装src/browser/cdp.helpers.ts - CDP 辅助函数src/browser/chrome.ts - Chrome 浏览器启动和管理src/browser/chrome.executables.ts - Chrome 可执行文件路径查找
src/browser/cdp.ts 负责通过 WebSocket 连接到浏览器的调试端口，并发送 CDP 命令来控制浏览器行为。
浏览器操作
src/browser/client-actions.ts 及相关文件定义了丰富的浏览器操作：
src/browser/client-actions-core.ts - 核心操作（导航、点击、输入等）src/browser/client-actions-observe.ts - 页面观察和数据提取src/browser/client-actions-state.ts - 浏览器状态管理src/browser/client-actions-types.ts - 操作类型定义
配置文件管理
src/browser/profiles.ts 和 src/browser/profiles-service.ts 实现了浏览器配置文件的管理。每个会话可以使用独立的浏览器配置文件，从而保持 Cookie 和登录状态的隔离。
Canvas 可视化系统
Canvas 功能位于 src/canvas-host/ 目录。这个模块实现了 A2UI（Agent-to-UI） 协议的渲染服务。
A2UI 是一个将 Agent 内部状态和工作流程可视化的协议。Agent 可以通过发送 A2UI 指令来动态更新 Canvas 上的内容，实现实时的可视化交互。
项目还在 vendor/a2ui/ 目录下包含了 A2UI 渲染器的供应商代码，用于在 macOS、iOS 等客户端应用中渲染 Canvas 内容。
节点系统实现
节点管理
src/nodes/ 目录实现了设备节点的管理。这里的“节点”指的是运行在 macOS、iOS、Android 上的伴侣应用，它们通过 WebSocket 连接到中心 Gateway，从而为 Agent 提供访问设备原生能力（如通知、地理位置等）的通道。
src/node-host/ 目录则包含了节点主机服务，负责管理与各个节点的连接和通信。
跨平台应用
项目包含了多平台的原生应用实现：
apps/ 目录 - 包含了各平台应用的项目文件Swabble/ 目录 - 移动应用的核心代码（Swift 实现）
从项目根目录的 .swiftformat 和 .swiftlint.yml 配置文件可以确认，移动端采用 Swift 语言开发。
工具系统实现
工具目录结构
src/agents/tools/ 目录包含了 Agent 可用的所有工具实现，文件数量超过 50 个，涵盖了从底层系统操作到高层业务处理的完整工具链。
工具按功能可大致分为以下几类：
浏览器控制工具：browser-tool.ts 是核心实现，配合 browser-tool.schema.ts 定义了工具的输入输出规范。它封装了 src/browser/ 目录下的 CDP 协议实现，为 Agent 提供页面导航、元素操作、截图等能力。
可视化工具：canvas-tool.ts 实现了 A2UI 协议的 Canvas 操作接口。
定时任务工具：cron-tool.ts 提供了定时任务的创建和管理能力。
会话管理工具：包含 sessions-list-tool.ts（列出会话）、sessions-send-tool.ts（发送消息）、sessions-history-tool.ts（查询历史）、sessions-spawn-tool.ts（创建新会话）、session-status-tool.ts（查询状态）等，提供了完整的会话操作能力。
网络工具：web-fetch.ts 实现网页内容抓取，web-search.ts 提供网页搜索能力。相关测试文件如 web-fetch.ssrf.test.ts 针对 SSRF 攻击进行了安全测试。
节点控制工具：nodes-tool.ts 是与设备节点通信的接口，Agent 可通过它调用运行在 iOS/Android/macOS 上的原生功能。
平台特定操作：例如 discord-actions.ts 及其子模块提供了 Discord 平台的服务器管理、消息操作和审核功能。类似的还有 slack-actions.ts、telegram-actions.ts、whatsapp-actions.ts。
多媒体工具：image-tool.ts 提供图像处理能力，tts-tool.ts 实现文本转语音功能。
系统工具：gateway-tool.ts 允许 Agent 查询和修改 Gateway 配置，memory-tool.ts 提供会话记忆功能，agents-list-tool.ts 可以列出所有可用 Agent。
浏览器工具深入分析
src/agents/tools/browser-tool.ts 的实现很好地展示了工具系统的设计模式。该文件定义了关键类型：
type BrowserProxyFile = {
path: string;
base64: string;
mimeType?: string;
};
type BrowserNodeTarget = {
nodeId: string;
label?: string;
};
核心函数 resolveBrowserNodeTarget 实现了浏览器目标解析逻辑，支持多种目标类型：
sandbox：在沙箱容器中的浏览器host：在主机上运行的浏览器custom：自定义浏览器实例node：在远程设备节点上的浏览器
当 Agent 调用浏览器工具时，系统会根据配置和节点状态决定使用哪个浏览器实例。如果指定了 requestedNode 参数，工具会检查该节点是否连接且支持浏览器功能，然后将操作代理到该节点执行。这意味着 Agent 可以直接控制运行在用户手机上的浏览器，实现真正的跨设备自动化操作。
技能系统实现
技能系统架构
src/agents/skills/ 目录实现了一个完整的技能管理系统。技能是对基础工具的高级封装，它将多个工具调用和特定的提示词模板组合成面向具体任务的、可复用的能力单元。
核心文件包括：
- 配置和类型定义：
config.ts 管理技能配置，types.ts 定义类型结构，frontmatter.ts 解析技能文件中的 Markdown frontmatter 元数据。
- 技能加载机制：
bundled-dir.ts 管理内置技能，plugin-skills.ts 处理插件技能加载，workspace.ts 管理用户自定义技能。
- 动态刷新：
refresh.ts 实现了技能的动态刷新，允许在运行时重新加载技能而无需重启系统。
- 序列化：
serialize.ts 负责将技能定义序列化为 Agent 可理解的格式。
- 环境配置：
env-overrides.ts 允许技能通过环境变量覆盖默认配置。
三层技能体系
从测试文件的命名可以推断，Clawdbot 实现了三层技能体系：
- Bundled Skills（内置技能）：随项目一起发布，存储在特定目录中。
- Plugin Skills（插件技能）：通过
plugin-skills.ts 加载的外部技能包，可通过包管理器安装以扩展系统能力。
- Workspace Skills（工作空间技能）：用户在自己工作空间中创建的自定义技能，具有最高优先级，会覆盖同名的插件技能和内置技能。
技能的构建和执行
测试文件揭示了技能系统的工作流程：
skills.buildworkspaceskillcommands.test.ts：测试将技能转换为 Agent 可调用命令的过程。skills.buildworkspaceskillsnapshot.test.ts：测试技能快照功能，用于保存和恢复技能状态。skills.resolveskillspromptforrun.test.ts：测试技能提示词解析。当执行技能时，系统会根据技能定义和当前上下文，构建一个包含详细指令和可用工具列表的完整提示词。skills.build-workspace-skills-prompt.syncs-merged-skills-into-target-workspace.test.ts：显示系统支持将多个来源的技能合并同步到目标工作空间。
对这类复杂的技能系统与插件架构感兴趣？你可以在 开源实战 板块找到更多关于热门项目架构分析与最佳实践的深度内容。
沙箱系统实现
沙箱架构
src/agents/sandbox/ 目录实现了基于 Docker 的沙箱隔离系统，确保 Agent 执行的代码和工具调用不会威胁主机安全。
核心文件分层清晰：
- Docker 集成层：
docker.ts 封装 Docker API 调用，types.docker.ts 定义相关类型。
- 配置管理层：
config.ts 定义配置选项，config-hash.ts 通过计算配置哈希值来确保环境一致性。
- 运行时管理层：
manage.ts 管理生命周期，runtime-status.ts 查询状态，context.ts 维护执行上下文，registry.ts 管理沙箱实例注册表。
- 浏览器支持层：
browser.ts 集成沙箱内浏览器，browser-bridges.ts 提供桥接机制。
- 安全策略：
tool-policy.ts 定义工具使用策略，规定哪些工具可在沙箱内执行。
沙箱工作流程
当 Agent 需要执行需隔离的操作时（如运行用户提供的代码），系统会：
- 计算当前配置哈希值。
- 查找是否已有匹配的沙箱实例。
- 若不存在，则创建新的 Docker 容器。
- 挂载必要的文件和目录。
- 在容器内执行操作。
- 监控执行状态。
- 操作完成后，根据策略决定是否销毁容器。
安全机制
沙箱系统的安全性体现在多方面：进程隔离、网络隔离、文件系统隔离、资源使用限制以及通过 tool-policy.ts 实施的工具执行策略。
开发工具链
包管理
项目使用 pnpm 作为包管理器，pnpm-workspace.yaml 文件定义了工作空间配置，支持 Monorepo 结构。
package.json 中定义了完整的构建和开发脚本：
{
"scripts": {
"dev": "node scripts/run-node.mjs",
"build": "tsc -p tsconfig.json && ...",
"ui:build": "node scripts/ui.js build",
"gateway:watch": "tsx watch src/cli/entry.ts gateway",
"test": "vitest"
}
}
代码质量工具
项目使用一系列现代化工具保证代码质量：
- Oxlint (
.oxlintrc.json) - 基于 Rust 的高性能代码检查工具。
- Oxfmt (
.oxfmtrc.jsonc) - 代码格式化工具。
- detect-secrets (
.detect-secrets.cfg) - 密钥泄露检测。
- shellcheck (
.shellcheckrc) - Shell 脚本检查。
- swiftlint (
.swiftlint.yml) - Swift 代码检查。
测试体系
项目建立了完善的测试体系，包含多个 Vitest 配置文件：vitest.unit.config.ts（单元测试）、vitest.e2e.config.ts（端到端测试）、vitest.gateway.config.ts（Gateway 专项测试）等。从 src/ 目录下大量的 .test.ts 文件可以看出，测试覆盖率很高。
部署方案
Docker 部署
项目提供了完整的 Docker 部署方案，包括 Dockerfile（主应用镜像）、docker-compose.yml 和 docker-setup.sh 设置脚本。
云平台部署
fly.toml 文件提供了 Fly.io 平台的部署配置，用户可以将 Gateway 部署到云端以实现远程访问。
总结
Clawdbot 是一个架构清晰、模块化程度极高的个人 AI 助手项目。通过代码分析，可以总结出其技术特点：
- 架构设计：采用中心化 Gateway 控制平面，各模块通过 WebSocket 与其通信，实现松耦合。
- 插件化：渠道、工具、技能均采用插件化设计，扩展性强。
- 安全机制：通过沙箱隔离、白名单、配对机制等实现多层防护。
- 跨平台能力：通过节点系统和原生应用，实现跨 macOS、iOS、Android 的设备控制。
- 工程实践：使用 pnpm、Oxlint、Vitest 等现代化工具链，建立了完善的测试和自动化流程。
从工程角度看，Clawdbot 是一个质量很高的开源项目，其设计思路与实现方式，尤其是在 Node.js 技术栈上的应用，值得开发者深入研究和借鉴。如果你想了解更多关于系统架构设计的知识，可以关注 后端 & 架构 相关内容。
对于希望深入研究或自行部署的开发者，详细查阅项目的 技术文档 和官方指南是必不可少的一步。此外，欢迎在 云栈社区 与其他开发者交流关于 AI 助手实现的心得与挑战。
附：项目核心依赖包简介
生产依赖 (dependencies) 选摘
| 依赖包 |
用途 |
@aws-sdk/client-bedrock |
AWS Bedrock AI 模型服务客户端 |
@grammyjs/runner |
Telegram 机器人框架运行器 |
@slack/bolt |
Slack 机器人框架 |
@whiskeysockets/baileys |
WhatsApp Web 客户端库 |
chromium-bidi |
Chromium BiDi 协议实现（浏览器自动化） |
express / hono |
Web 应用框架 |
playwright-core |
浏览器自动化核心库 |
ws |
WebSocket 客户端/服务器库 |
zod |
TypeScript 模式验证库 |
开发依赖 (devDependencies) 选摘
| 依赖包 |
用途 |
oxlint / oxfmt |
Rust 编写的 JS/TS 代码检查与格式化工具 |
tsx |
TypeScript 执行器 |
vitest |
单元测试框架 |
wireit |
构建任务编排工具 |
发表于 昨天 04:03
|
查看: 1|
回复: 0
