【技术干货】Clawdbot源码解析：打造完全可控的本地AI助手架构与实现

Clawdbot是一个架构清晰、模块化程度高的开源个人AI助手项目。采用本地优先设计理念，所有控制逻辑和数据运行在用户设备上。文章深入分析了其核心架构，包括Gateway控制平面、Agent运行时、多渠道通信系统、浏览器控制、Canvas可视化等模块实现，并详细介绍了其插件化架构、沙箱安全机制、工具系统和技能系统等技术特点。通过WebSocket实现模块间通信，支持跨平台设备控制，提供了完整的端到端解决方案。

Clawdbot 是一个开源的个人 AI 助手项目，它的设计目标是让用户能够在自己的设备上运行一个完全可控的智能助手。这个项目在 GitHub 上获得了 15.4k 星标和 1.9k 分支，采用 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/目录的组织结构来看，系统由以下核心模块组成：

这些模块通过 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" }>

如果文件存在且非空，函数会调用buildBootPrompt构建一个特殊的提示词，然后通过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 连接时，必须提供有效的认证凭证。Gateway 会验证这些凭证，只有通过验证的连接才会被接受并保持活跃状态。

此外，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实现了与 Chrome 浏览器的通信，通过 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 协议的渲染服务。

A2UI（Agent-to-UI）是一个将 Agent 的内部状态和工作流程可视化的协议。Agent 可以通过发送 A2UI 指令来更新 Canvas 上的内容，实现实时的可视化交互。

项目还在vendor/a2ui/目录下包含了 A2UI 渲染器的供应商代码，用于在客户端（如 macOS 应用、iOS 应用）中渲染 Canvas 内容。

节点系统实现

节点管理

src/nodes/目录实现了设备节点的管理。节点是指运行在 macOS、iOS、Android 上的伴侣应用，它们通过 WebSocket 连接到 Gateway，提供设备原生能力。

src/node-host/目录包含了节点主机服务，负责管理与各个节点的连接和通信。

跨平台应用

项目包含以下平台的应用实现：

• apps/

  目录 - 包含各平台应用的项目文件

• Swabble/

  目录 - 移动应用的核心代码（Swift 实现）

从.swiftformat和.swiftlint.yml配置文件可以确认，移动应用使用 Swift 语言开发。

工具系统实现

工具目录结构

src/agents/tools/目录包含了 Agent 可用的所有工具实现。这个目录有超过 50 个文件，涵盖了从底层浏览器控制到高层业务操作的完整工具链。

https://github.com/clawdbot/clawdbot/tree/main/src/agents/tools

工具按功能分为以下几类：

浏览器控制工具：browser-tool.ts是浏览器控制的核心实现，配合browser-tool.schema.ts定义了工具的输入输出规范。这个工具封装了src/browser/目录下的 CDP 协议实现，为 Agent 提供了页面导航、元素操作、截图等能力。

可视化工具：canvas-tool.ts实现了 A2UI 协议的 Canvas 操作接口，Agent 可以通过这个工具向用户界面推送实时的可视化内容。

定时任务工具：cron-tool.ts提供了定时任务的创建和管理能力，Agent 可以设置定期执行的任务。

会话管理工具：包含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 攻击的安全测试，在web-tools.readability.test.ts中测试了可读性提取功能。

节点控制工具：nodes-tool.ts是与设备节点通信的接口，通过它 Agent 可以调用运行在 iOS/Android/macOS 上的原生功能。

平台特定操作：针对不同消息平台，有专门的操作工具。例如discord-actions.ts及其子模块（discord-actions-guild.ts、discord-actions-messaging.ts、discord-actions-moderation.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参数，工具会检查该节点是否连接（node.connected && isBrowserNode(node)），然后将浏览器操作代理到该节点执行。这意味着 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（内置技能）：这些技能随项目一起发布，存储在特定的内置目录中。测试文件skills.build-workspace-skills-prompt.applies-bundled-allowlist-without-affecting-workspace-skills.test.ts验证了内置技能的白名单机制不会影响工作空间技能。

Plugin Skills（插件技能）：通过plugin-skills.ts加载的外部技能包。这些技能可以通过包管理器安装，扩展系统的能力。

Workspace Skills（工作空间技能）：用户在自己的工作空间中创建的自定义技能。测试文件skills.build-workspace-skills-prompt.prefers-workspace-skills-managed-skills.test.ts表明工作空间技能具有最高优先级，会覆盖同名的插件技能和内置技能。

技能的构建和执行

测试文件揭示了技能系统的工作流程：

skills.buildworkspaceskillcommands.test.ts测试了技能命令的构建过程。每个技能会被转换为 Agent 可以调用的命令。

skills.buildworkspaceskillsnapshot.test.ts测试了技能快照功能，这允许系统保存和恢复技能的状态。

skills.resolveskillspromptforrun.test.ts测试了技能提示词的解析。当 Agent 需要执行一个技能时，系统会根据技能定义和当前上下文，构建一个包含指令和可用工具列表的完整提示词。

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定义了 Docker 相关的类型。这一层负责容器的创建、启动、停止和删除。

配置管理层：config.ts定义了沙箱的配置选项，config-hash.ts通过计算配置的哈希值来确保沙箱环境的一致性。当配置改变时，系统会创建新的沙箱容器。

运行时管理层：manage.ts实现了沙箱的生命周期管理，runtime-status.ts提供运行时状态查询，context.ts维护沙箱的执行上下文，registry.ts管理沙箱实例的注册表。

浏览器支持层：browser.ts实现了沙箱内浏览器的集成，browser-bridges.ts提供了沙箱浏览器与外部系统的桥接机制。这使得 Agent 可以在隔离环境中安全地进行网页操作。

工作空间管理：workspace.ts管理沙箱的工作空间，包括文件的挂载和权限控制。

安全策略：tool-policy.ts定义了工具使用策略，规定了哪些工具可以在沙箱内执行，哪些必须在主机上执行。tool-policy.test.ts包含了策略的测试用例。

维护功能：prune.ts实现了沙箱的清理功能，定期删除不再使用的容器和镜像，防止磁盘空间耗尽。

沙箱工作流程

当 Agent 需要执行一个需要隔离的操作时（例如运行用户提供的代码），系统会：

1. 通过config-hash.ts计算当前配置的哈希值
2. 在registry.ts中查找是否已有匹配的沙箱实例
3. 如果不存在，通过docker.ts创建新的容器
4. 通过workspace.ts挂载必要的文件和目录
5. 在容器内执行操作
6. 通过runtime-status.ts监控执行状态
7. 操作完成后，根据策略决定是保持容器运行还是销毁

项目根目录的Dockerfile.sandbox和Dockerfile.sandbox-browser定义了两种沙箱镜像。前者是通用的代码执行环境，后者额外包含了 Chrome 浏览器，用于需要浏览器的任务。

安全机制

沙箱系统的安全性体现在多个方面：

进程隔离：通过 Docker 容器实现完全的进程隔离，沙箱内的代码无法直接访问主机资源。

网络隔离：可以配置容器的网络策略，限制沙箱的网络访问。

文件系统隔离：沙箱有独立的文件系统，只能访问明确挂载的目录。

资源限制：可以限制容器的 CPU、内存等资源使用，防止资源耗尽攻击。

工具策略：通过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.unit.config.ts

  • 单元测试配置

• vitest.e2e.config.ts

  • 端到端测试配置

• vitest.gateway.config.ts

  • Gateway 专项测试配置

• vitest.extensions.config.ts

  • 扩展功能测试配置

• vitest.live.config.ts

  • 实时环境测试配置

从src/目录下大量的.test.ts文件可以看出，项目的测试覆盖率很高，几乎每个核心模块都有对应的测试用例。

持续集成

.github/目录包含了 GitHub Actions 的工作流配置，实现了自动化的构建、测试和发布流程。

部署方案

Docker 部署

项目提供了完整的 Docker 部署方案：

• Dockerfile

  • 主应用的 Docker 镜像

• docker-compose.yml

  • Docker Compose 配置

• docker-setup.sh

  • Docker 环境设置脚本

云平台部署

fly.toml文件提供了 Fly.io 平台的部署配置，用户可以将 Gateway 部署到云端，实现远程访问。

总结

Clawdbot 是一个架构清晰、模块化程度高的个人 AI 助手项目。通过分析其代码实现，可以总结出以下技术特点：

架构设计：采用中心化的 Gateway 控制平面，所有模块通过 WebSocket 与 Gateway 通信，实现了松耦合的架构。

插件化：渠道、工具、技能都采用插件化设计，具有很强的可扩展性。

安全机制：通过沙箱隔离、白名单控制、配对机制等多层安全措施，保障系统安全。

跨平台能力：通过节点系统和原生应用，实现了跨 macOS、iOS、Android 的设备控制能力。

工程实践：使用现代化的开发工具链（pnpm、Oxlint、vitest），建立了完善的测试体系和自动化流程。

从代码实现来看，Clawdbot 是一个工程质量很高的开源项目，其设计思路和实现方式值得学习和借鉴。

最后我们再整理下package.json中所有依赖的介绍：

生产依赖 (dependencies)

可选依赖 (optionalDependencies)

开发依赖 (devDependencies)

AI时代，未来的就业机会在哪里？

答案就藏在大模型的浪潮里。从ChatGPT、DeepSeek等日常工具，到自然语言处理、计算机视觉、多模态等核心领域，技术普惠化、应用垂直化与生态开源化正催生Prompt工程师、自然语言处理、计算机视觉工程师、大模型算法工程师、AI应用产品经理等AI岗位。

掌握大模型技能，就是把握高薪未来。

那么，普通人如何抓住大模型风口？

AI技术的普及对个人能力提出了新的要求，在AI时代，持续学习和适应新技术变得尤为重要。无论是企业还是个人，都需要不断更新知识体系，提升与AI协作的能力，以适应不断变化的工作环境。

因此，这里给大家整理了一份《2026最新大模型全套学习资源》，包括2026最新大模型学习路线、大模型书籍、视频教程、项目实战、最新行业报告、面试题、AI产品经理入门到精通等，带你从零基础入门到精通，快速掌握大模型技术！

由于篇幅有限，有需要的小伙伴可以扫码获取！

1. 成长路线图&学习规划

要学习一门新的技术，作为新手一定要先学习成长路线图，方向不对，努力白费。这里，我们为新手和想要进一步提升的专业人士准备了一份详细的学习成长路线图和规划。

2. 大模型经典PDF书籍

书籍和学习文档资料是学习大模型过程中必不可少的，我们精选了一系列深入探讨大模型技术的书籍和学习文档，它们由领域内的顶尖专家撰写，内容全面、深入、详尽，为你学习大模型提供坚实的理论基础。（书籍含电子版PDF）

3. 大模型视频教程

对于很多自学或者没有基础的同学来说，书籍这些纯文字类的学习教材会觉得比较晦涩难以理解，因此，我们提供了丰富的大模型视频教程，以动态、形象的方式展示技术概念，帮助你更快、更轻松地掌握核心知识。

4. 大模型项目实战

学以致用，当你的理论知识积累到一定程度，就需要通过项目实战，在实际操作中检验和巩固你所学到的知识，同时为你找工作和职业发展打下坚实的基础。

5. 大模型行业报告

行业分析主要包括对不同行业的现状、趋势、问题、机会等进行系统地调研和评估，以了解哪些行业更适合引入大模型的技术和应用，以及在哪些方面可以发挥大模型的优势。

6. 大模型面试题

面试不仅是技术的较量，更需要充分的准备。

在你已经掌握了大模型技术之后，就需要开始准备面试，我们将提供精心整理的大模型面试题库，涵盖当前面试中可能遇到的各种技术问题，让你在面试中游刃有余。

为什么大家都在学AI大模型？

随着AI技术的发展，企业对人才的需求从“单一技术”转向 “AI+行业”双背景。企业对人才的需求从“单一技术”转向 “AI+行业”双背景。金融+AI、制造+AI、医疗+AI等跨界岗位薪资涨幅达30%-50%。

同时很多人面临优化裁员，近期科技巨头英特尔裁员2万人，传统岗位不断缩减，因此转行AI势在必行！

这些资料有用吗？

这份资料由我们和鲁为民博士(北京清华大学学士和美国加州理工学院博士)共同整理，现任上海殷泊信息科技CEO，其创立的MoPaaS云平台获Forrester全球’强劲表现者’认证，服务航天科工、国家电网等1000+企业，以第一作者在IEEE Transactions发表论文50+篇，获NASA JPL火星探测系统强化学习专利等35项中美专利。本套AI大模型课程由清华大学-加州理工双料博士、吴文俊人工智能奖得主鲁为民教授领衔研发。

资料内容涵盖了从入门到进阶的各类视频教程和实战项目，无论你是小白还是有些技术基础的技术人员，这份资料都绝对能帮助你提升薪资待遇，转行大模型岗位。

大模型全套学习资料已整理打包，有需要的小伙伴可以微信扫描下方CSDN官方认证二维码，免费领取【保证100%免费】