1. 项目概述1.1 项目基本信息项目名称: ClawdbotGitHub 仓库: https://github.com/openclaw/openclaw开源协议: MIT核心语言: TypeScript运行时要求: Node.js ≥22包管理器: pnpm1.2 核心设计理念本地优先Local-first: 所有控制逻辑和数据运行在用户自己的设备上完全可控: 不依赖云端服务用户拥有完全控制权多渠道支持: 统一控制平面管理多个消息平台1.3 支持的消息平台WhatsApp、Telegram、Slack、DiscordGoogle Chat、Signal、iMessageMicrosoft Teams 等2. 整体架构设计2.1 架构模式Clawdbot 采用中心化的 Gateway 控制平面架构所有模块通过 WebSocket 与 Gateway 通信实现松耦合的模块化设计。2.2 核心模块组织模块目录功能职责src/gateway/WebSocket 控制平面管理连接、会话、配置和事件src/agents/AI 代理运行时处理消息并调用 LLM 和工具src/channels/多渠道消息适配器对接不同的通信平台src/browser/浏览器控制模块通过 CDP 协议控制 Chromesrc/canvas-host/Canvas 渲染服务托管 A2UI 可视化界面src/nodes/设备节点管理与 iOS/Android/macOS 应用通信src/cli/命令行界面提供用户交互入口src/config/配置管理系统src/sessions/会话管理维护对话上下文2.3 通信架构客户端CLI/macOS App/移动App ↓ WebSocket Gateway中心枢纽 ↓ 路由分发 各功能模块Agents/Channels/Browser等3. Gateway 控制平面实现3.1 启动机制核心文件:src/gateway/boot.ts关键特性:BOOT.md 机制: 系统启动时检查工作目录下的BOOT.md文件自动化任务: 如果文件存在且非空将其内容作为指令交给 Agent 执行启动流程:loadBootFile()- 读取 BOOT.md 文件buildBootPrompt()- 构建提示词agentCommand()- 提交任务给 Agent返回值类型:type BootRunResult | { status: skipped; reason: missing | empty } | { status: ran } | { status: failed; reason: string };3.2 WebSocket 服务目录结构:src/gateway/server-methods/- RPC 方法处理逻辑src/gateway/protocol/- 通信协议数据结构src/gateway/auth.ts- 连接认证逻辑功能特性:实时双向通信支持多种消息类型agent:run、config:get、session:send等根据消息类型路由到对应处理函数3.3 认证与安全连接认证:src/gateway/auth.ts- 验证 WebSocket 连接凭证设备认证:src/gateway/device-auth.ts- 设备级别认证确保只有授权设备可连接4. Agent 运行时实现4.1 Pi Agent 架构核心目录:src/agents/关键子目录:src/agents/pi-embedded-runner/- Pi Agent 嵌入式运行器src/agents/pi-embedded-helpers/- 运行时辅助函数src/agents/pi-extensions/- Agent 扩展机制src/agents/tools/- 工具集合50 个工具src/agents/skills/- 技能系统src/agents/sandbox/- 沙箱隔离环境4.2 Agent 工作流程接收用户消息 → 构建包含工具列表的提示词 → 调用 LLM → 解析 LLM 响应 → 执行工具调用 → 将结果反馈给 LLM → 循环直到任务完成4.3 认证配置管理目录:src/agents/auth-profiles/功能:支持多认证配置管理可同时配置多个 LLM 提供商Anthropic、OpenAI 等运行时根据配置选择使用哪个提供商src/agents/auth-health.ts- 检查认证配置健康状态5. 多渠道通信系统5.1 插件化架构核心目录: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- 渠道配置管理5.2 消息标准化目录:src/channels/plugins/normalize/功能: 将不同平台的消息格式转换为统一的内部表示Agent 和 Gateway 只需处理标准化消息对象。5.3 安全控制机制5.3.1 白名单机制目录:src/channels/allowlists/src/channels/allowlist-match.ts- 白名单匹配逻辑src/channels/mention-gating.ts- 提及门控群组中需要 才响应src/channels/command-gating.ts- 命令门控5.3.2 配对机制目录:src/pairing/陌生用户首次私信时生成配对码只有管理员批准后用户才能正常使用机器人6. 浏览器控制实现6.1 CDP 协议封装核心目录:src/browser/关键文件:src/browser/cdp.ts- CDP 协议核心封装src/browser/cdp.helpers.ts- CDP 辅助函数src/browser/chrome.ts- Chrome 浏览器启动和管理src/browser/chrome.executables.ts- Chrome 可执行文件路径查找实现方式: 通过 WebSocket 连接到浏览器的调试端口发送 CDP 命令控制浏览器行为。6.2 浏览器操作操作分类:src/browser/client-actions-core.ts- 核心操作导航、点击、输入等src/browser/client-actions-observe.ts- 页面观察和数据提取src/browser/client-actions-state.ts- 浏览器状态管理src/browser/client-actions-types.ts- 操作类型定义6.3 配置文件管理src/browser/profiles.ts- 浏览器配置文件管理src/browser/profiles-service.ts- 配置文件服务特性: 每个会话使用独立的浏览器配置文件保持 Cookie 和登录状态隔离6.4 跨设备浏览器控制浏览器工具:src/agents/tools/browser-tool.ts目标类型:sandbox- 在沙箱容器中的浏览器host- 在主机上运行的浏览器custom- 自定义浏览器实例node- 在远程设备节点上的浏览器关键能力: Agent 可以控制运行在用户手机上的浏览器实现真正的跨设备操作。7. Canvas 可视化系统7.1 A2UI 协议目录:src/canvas-host/核心概念:A2UI (Agent-to-UI): 将 Agent 的内部状态和工作流程可视化的协议Agent 通过发送 A2UI 指令更新 Canvas 上的内容实现实时的可视化交互7.2 渲染器实现供应商代码:vendor/a2ui/用于在客户端macOS 应用、iOS 应用中渲染 Canvas 内容8. 节点系统实现8.1 节点管理目录:src/nodes/功能:管理运行在 macOS、iOS、Android 上的伴侣应用通过 WebSocket 连接到 Gateway提供设备原生能力节点主机服务:src/node-host/- 管理与各个节点的连接和通信8.2 跨平台应用目录结构:apps/- 各平台应用的项目文件Swabble/- 移动应用核心代码Swift 实现开发语言: Swift从.swiftformat和.swiftlint.yml配置确认9. 工具系统实现9.1 工具目录结构目录:src/agents/tools/50 个文件9.2 工具分类9.2.1 浏览器控制工具browser-tool.ts- 浏览器控制核心实现browser-tool.schema.ts- 工具输入输出规范功能: 页面导航、元素操作、截图等9.2.2 可视化工具canvas-tool.ts- A2UI 协议的 Canvas 操作接口9.2.3 定时任务工具cron-tool.ts- 定时任务创建和管理9.2.4 会话管理工具sessions-list-tool.ts- 列出会话sessions-send-tool.ts- 发送消息到会话sessions-history-tool.ts- 查询会话历史sessions-spawn-tool.ts- 创建新会话session-status-tool.ts- 查询会话状态9.2.5 网络工具web-fetch.ts- 网页内容抓取web-search.ts- 网页搜索能力安全测试:web-fetch.ssrf.test.ts- SSRF 攻击安全测试可读性测试:web-tools.readability.test.ts- 可读性提取功能测试9.2.6 节点控制工具nodes-tool.ts- 与设备节点通信的接口9.2.7 平台特定操作工具discord-actions.ts及其子模块guild、messaging、moderationslack-actions.tstelegram-actions.tswhatsapp-actions.ts9.2.8 多媒体工具image-tool.ts- 图像生成和处理tts-tool.ts- 文本转语音9.2.9 系统工具gateway-tool.ts- 查询和修改 Gateway 配置memory-tool.ts- 会话记忆功能agents-list-tool.ts- 列出所有可用的 Agent9.3 浏览器工具深入分析文件:src/agents/tools/browser-tool.ts关键类型:type BrowserProxyFile { path: string; base64: string; mimeType?: string; }; type BrowserNodeTarget { nodeId: string; label?: string; };核心函数:resolveBrowserNodeTarget()- 实现浏览器目标解析逻辑10. 技能系统实现10.1 技能系统架构目录:src/agents/skills/核心概念: 技能是对基础工具的高级封装将多个工具调用和特定的提示词组合成面向任务的能力单元。10.2 核心文件config.ts- 技能配置管理types.ts- 技能系统类型结构frontmatter.ts- 解析技能文件中的 Markdown frontmatter 元数据bundled-dir.ts- 内置技能目录管理plugin-skills.ts- 插件技能加载workspace.ts- 用户工作空间中的自定义技能管理refresh.ts- 技能动态刷新机制运行时重新加载serialize.ts- 技能定义序列化env-overrides.ts- 通过环境变量覆盖默认配置10.3 三层技能体系10.3.1 Bundled Skills内置技能随项目一起发布存储在特定的内置目录中测试文件验证了白名单机制不会影响工作空间技能10.3.2 Plugin Skills插件技能通过plugin-skills.ts加载的外部技能包可通过包管理器安装扩展系统能力10.3.3 Workspace Skills工作空间技能用户在自己的工作空间中创建的自定义技能最高优先级: 会覆盖同名的插件技能和内置技能10.4 技能构建和执行流程测试文件揭示的工作流程:skills.buildworkspaceskillcommands.test.ts- 技能命令构建skills.buildworkspaceskillsnapshot.test.ts- 技能快照功能skills.resolveskillspromptforrun.test.ts- 技能提示词解析skills.build-workspace-skills-prompt.syncs-merged-skills-into-target-workspace.test.ts- 技能同步11. 沙箱系统实现11.1 沙箱架构目录:src/agents/sandbox/设计目标: 基于 Docker 的沙箱隔离系统确保 Agent 执行的代码和工具调用不会对主机系统造成安全威胁。11.2 核心文件层次11.2.1 Docker 集成层docker.ts- Docker API 调用封装types.docker.ts- Docker 相关类型定义功能: 容器创建、启动、停止和删除11.2.2 配置管理层config.ts- 沙箱配置选项config-hash.ts- 通过计算配置哈希值确保沙箱环境一致性特性: 配置改变时创建新的沙箱容器11.2.3 运行时管理层manage.ts- 沙箱生命周期管理runtime-status.ts- 运行时状态查询context.ts- 沙箱执行上下文维护registry.ts- 沙箱实例注册表管理11.2.4 浏览器支持层browser.ts- 沙箱内浏览器集成browser-bridges.ts- 沙箱浏览器与外部系统桥接功能: Agent 在隔离环境中安全进行网页操作11.2.5 工作空间管理workspace.ts- 沙箱工作空间管理文件挂载和权限控制11.2.6 安全策略tool-policy.ts- 工具使用策略定义tool-policy.test.ts- 策略测试用例规则: 某些敏感工具如系统配置修改被禁止在沙箱内执行11.2.7 维护功能prune.ts- 沙箱清理功能定期删除不再使用的容器和镜像11.3 沙箱工作流程1. 通过 config-hash.ts 计算当前配置的哈希值 2. 在 registry.ts 中查找是否已有匹配的沙箱实例 3. 如果不存在通过 docker.ts 创建新的容器 4. 通过 workspace.ts 挂载必要的文件和目录 5. 在容器内执行操作 6. 通过 runtime-status.ts 监控执行状态 7. 操作完成后根据策略决定是保持容器运行还是销毁11.4 沙箱镜像类型项目根目录:Dockerfile.sandbox- 通用代码执行环境Dockerfile.sandbox-browser- 额外包含 Chrome 浏览器的沙箱11.5 安全机制11.5.1 进程隔离通过 Docker 容器实现完全的进程隔离沙箱内的代码无法直接访问主机资源11.5.2 网络隔离可配置容器的网络策略限制沙箱的网络访问11.5.3 文件系统隔离沙箱有独立的文件系统只能访问明确挂载的目录11.5.4 资源限制限制容器的 CPU、内存等资源使用防止资源耗尽攻击11.5.5 工具策略通过tool-policy.ts定义策略敏感工具禁止在沙箱内执行12. 开发工具链12.1 包管理包管理器: pnpm工作空间配置:pnpm-workspace.yaml- 支持 Monorepo 结构12.2 构建脚本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 } }12.3 代码质量工具工具配置文件用途Oxlint.oxlintrc.json基于 Rust 的高性能代码检查工具Oxfmt.oxfmtrc.jsonc代码格式化工具detect-secrets.detect-secrets.cfg密钥泄露检测shellcheck.shellcheckrcShell 脚本检查swiftlint.swiftlint.ymlSwift 代码检查12.4 测试体系测试配置文件:vitest.unit.config.ts- 单元测试配置vitest.e2e.config.ts- 端到端测试配置vitest.gateway.config.ts- Gateway 专项测试配置vitest.extensions.config.ts- 扩展功能测试配置vitest.live.config.ts- 实时环境测试配置测试覆盖率:src/目录下大量的.test.ts文件几乎每个核心模块都有对应的测试用例。12.5 持续集成目录:.github/GitHub Actions 工作流配置自动化构建、测试和发布流程13. 部署方案13.1 Docker 部署文件:Dockerfile- 主应用的 Docker 镜像docker-compose.yml- Docker Compose 配置docker-setup.sh- Docker 环境设置脚本13.2 云平台部署文件:fly.tomlFly.io 平台部署配置用户可将 Gateway 部署到云端实现远程访问14. 依赖分析14.1 生产依赖dependencies14.1.1 AI 和 Agent 相关agentclientprotocol/sdk- Agent 客户端协议 SDKaws-sdk/client-bedrock- AWS Bedrock 服务客户端AI 模型服务mariozechner/pi-agent-core- Pi Agent 核心库mariozechner/pi-ai- Pi AI 功能库mariozechner/pi-coding-agent- Pi 编码助手代理mariozechner/pi-tui- Pi 终端用户界面库14.1.2 消息平台 SDKbuape/carbon- Discord 机器人框架grammyjs/runner- Grammy Telegram 机器人运行器grammyjs/transformer-throttler- Grammy 机器人请求节流转换器line/bot-sdk- LINE 聊天机器人 SDKslack/bolt- Slack 机器人框架slack/web-api- Slack Web API 客户端whiskeysockets/baileys- WhatsApp Web 客户端库grammy- Telegram 机器人框架14.1.3 浏览器和自动化chromium-bidi- Chromium BiDi 协议实现playwright-core- 浏览器自动化核心库14.1.4 Web 框架和服务器express- Web 应用框架hono- 轻量级 Web 框架ws- WebSocket 客户端和服务器body-parser- HTTP 请求体解析中间件14.1.5 工具和实用库clack/prompts- 终端交互式提示库mozilla/readability- 网页内容提取和可读性优化sinclair/typebox- TypeScript 类型验证和 JSON Schemaajv- JSON Schema 验证器chalk- 终端文本样式和颜色chokidar- 文件系统监听库cli-highlight- 命令行代码高亮commander- 命令行界面框架croner- 定时任务调度器crondotenv- 环境变量加载器file-type- 文件类型检测jiti- TypeScript/ESM 运行时加载器json5- JSON5 解析器支持注释的 JSONjszip- ZIP 文件处理库linkedom- 轻量级 DOM 实现long- 长整数处理库markdown-it- Markdown 解析和渲染node-edge-tts- Edge 文本转语音服务osc-progress- 终端进度条OSC 序列pdfjs-dist- PDF 文件解析库proper-lockfile- 文件锁实现qrcode-terminal- 终端二维码生成器sharp- 高性能图像处理库sqlite-vec- SQLite 向量扩展tar- TAR 归档文件处理tslog- TypeScript 日志库undici- 高性能 HTTP 客户端yaml- YAML 解析和序列化zod- TypeScript 模式验证库14.1.6 系统集成homebridge/ciao- mDNS/Bonjour 服务发现库lydell/node-pty- 伪终端PTY实现用于终端模拟detect-libc- 检测系统 libc 版本discord-api-types- Discord API 类型定义14.2 可选依赖optionalDependenciesnapi-rs/canvas- 高性能 Canvas 实现基于 Rustnode-llama-cpp- LLaMA 大语言模型的 Node.js 绑定14.3 开发依赖devDependencies14.3.1 类型定义grammyjs/types- Grammy 框架类型定义types/body-parser- body-parser 类型定义types/express- Express 类型定义types/markdown-it- markdown-it 类型定义types/node- Node.js 类型定义types/proper-lockfile- proper-lockfile 类型定义types/qrcode-terminal- qrcode-terminal 类型定义types/ws- WebSocket 类型定义14.3.2 前端框架lit-labs/signals- Lit 响应式信号实验性功能lit/context- Lit 上下文管理mariozechner/mini-lit- 轻量级 Lit 框架lit- Web Components 库lucide- 图标库14.3.3 开发工具typescript/native-preview- TypeScript 原生预览版vitest/coverage-v8- Vitest 代码覆盖率工具oxfmt- Rust 编写的代码格式化工具oxlint- Rust 编写的 JavaScript/TypeScript Linteroxlint-tsgolint- TypeScript Golint 规则集rolldown- Rust 编写的打包工具tsx- TypeScript 执行器typescript- TypeScript 编译器vitest- 单元测试框架wireit- 构建任务编排工具14.3.4 其他工具docx-preview- Word 文档预览库ollama- Ollama 本地 AI 模型客户端quicktype-core- JSON Schema 到类型定义转换器signal-utils- 信号处理工具集15. 技术特点总结15.1 架构设计优势中心化 Gateway: 统一控制平面松耦合架构WebSocket 通信: 实时双向通信能力模块化设计: 清晰的模块职责划分15.2 插件化设计渠道插件化: 易于扩展新的消息平台工具插件化: 50 工具功能丰富技能插件化: 三层技能体系灵活扩展15.3 安全机制沙箱隔离: Docker 容器隔离进程、网络、文件系统隔离白名单控制: 允许列表、提及门控、命令门控配对机制: 陌生用户需要管理员批准资源限制: CPU、内存限制防止资源耗尽攻击15.4 跨平台能力设备节点系统: macOS、iOS、Android 原生应用跨设备浏览器控制: 可控制运行在手机上的浏览器统一控制平面: 通过 Gateway 统一管理15.5 工程实践现代化工具链: pnpm、Oxlint、vitest完善测试体系: 单元测试、E2E 测试、实时环境测试自动化流程: GitHub Actions CI/CD代码质量保障: 多种代码检查工具16. 技术亮点分析16.1 BOOT.md 启动机制创新点: 通过编辑 Markdown 文件定义启动时的自动化任务实现了配置即代码的理念。16.2 三层技能体系设计优势:Bundled Skills: 保证核心功能稳定性Plugin Skills: 社区扩展能力Workspace Skills: 用户自定义最高优先级16.3 跨设备浏览器控制技术突破: Agent 可以控制运行在用户手机上的浏览器实现了真正的跨设备操作能力。16.4 A2UI 可视化协议创新设计: Agent-to-UI 协议实现了 Agent 内部状态和工作流程的可视化提升了用户体验。16.5 沙箱系统设计安全特性:配置哈希确保环境一致性多层次的隔离机制工具策略控制敏感操作17. 代码实现建议17.1 架构设计借鉴中心化 Gateway 模式: 适用于需要统一管理多个服务的场景WebSocket 实时通信: 适合需要双向实时通信的应用插件化架构: 提高系统可扩展性17.2 安全实践沙箱隔离: 对于需要执行用户代码的场景必须使用沙箱隔离多层安全控制: 白名单、配对、资源限制等多层防护工具策略: 定义清晰的工具使用策略17.3 工程实践Monorepo 管理: 使用 pnpm workspace 管理多包项目测试驱动: 建立完善的测试体系代码质量工具: 使用现代化工具链保证代码质量18. 对比分析18.1 与其他 AI 助手对比特性Clawdbot其他云端 AI 助手数据控制本地优先完全可控云端处理用户控制有限隐私性数据不离开用户设备数据上传到云端扩展性插件化架构易于扩展功能固定扩展受限跨平台支持多平台统一控制通常单一平台成本本地运行无服务费用需要订阅费用18.2 技术栈对比技术选择Clawdbot常见选择语言TypeScriptPython/JavaScript包管理pnpmnpm/yarn测试框架VitestJest/MochaLinterOxlintESLint格式化OxfmtPrettier19. 实验复现指导19.1 环境准备Node.js: 安装 Node.js ≥22pnpm: 安装 pnpm 包管理器Docker: 安装 Docker用于沙箱功能19.2 项目克隆和安装git clone https://github.com/clawdbot/clawdbot.git cd clawdbot pnpm install19.3 配置设置配置 LLM 提供商认证信息配置消息平台连接设置 Gateway 参数19.4 运行测试# 单元测试 pnpm test # E2E 测试 pnpm test:e2e # Gateway 测试 pnpm test:gateway19.5 启动 Gatewaypnpm gateway:watch20. 总结Clawdbot 是一个架构清晰、模块化程度高、工程质量优秀的个人 AI 助手项目。其设计思路和实现方式值得学习和借鉴架构设计: 中心化 Gateway 模块化设计实现了松耦合、高内聚的系统架构安全机制: 多层安全防护沙箱隔离、白名单、配对机制等扩展性: 插件化设计支持渠道、工具、技能的灵活扩展跨平台: 通过节点系统实现跨设备控制能力工程实践: 现代化工具链、完善测试体系、自动化流程该项目展示了如何构建一个高质量、可扩展、安全可靠的 AI 助手系统为类似项目的开发提供了宝贵的参考。