OpenClaw源码学习
概述官网主要使用TypeScript开发、开源GitHub387K Star81.3K Fork个人AI助理7x24小时在线、可部署在本地、能自己写代码进化、通过WhatsApp等就能指挥的赛博管家官方文档。核心逻辑去中心化与反向控制。核心特性能直接执行浏览网页、文件操作、系统控制、应用集成自我进化去中心化交互支持Telegram、WhatsApp、Discord、Slack、iMessage等这些模块通过Gateway中心枢纽控制平面进行协调。所有客户端都通过WebSocket连接到GatewayGateway负责将请求路由到相应的处理模块。模块目录功能职责src/gateway/WebSocket控制平面管理连接、会话、配置和事件src/agents/AI代理运行时处理消息并调用LLM和工具src/channels/多渠道消息适配器对接不同的通信平台src/browser/浏览器控制模块通过CDP协议控制Chromesrc/canvas/Canvas渲染服务托管A2UI可视化界面src/node-host/设备节点管理与iOS/Android/macOS应用通信src/cli/命令行界面提供用户交互入口src/config/配置管理系统src/sessions/会话管理维护对话上下文注该代码库关注度极高大概率是GitHub第一代码提交非常频繁下面列出的部分源码在最新版很有可能因为重构被删除或调整路径。Gateway启动逻辑在src/gateway/boot.ts文件中实现定义特殊的启动机制系统会在启动时检查工作目录下是否存在BOOT.md文件如果存在且内容不为空会将其内容作为指令交给Agent执行。核心函数runBootOnce实现如下逻辑exportasyncfunctionrunBootOnce(params:{cfg:ClawdbotConfig;deps:CliDeps;workspaceDir:string;agentId?:string;}):PromiseBootRunResult首先调用loadBootFile函数读取BOOT.md文件asyncfunctionloadBootFile(workspaceDir:string,):Promise{content?:string;status:ok|missing|empty}如果文件存在且非空函数会调用buildBootPrompt构建一个特殊的提示词然后通过agentCommand函数位于src/commands/agent.js将任务提交给Agent执行允许用户通过编辑Markdown文件来定义启动时的自动化任务。返回值类型定义为exporttypeBootRunResult|{status:skipped;reason:missing|empty}|{status:ran}|{status:failed;reason:string};WebSocket服务器实现位于src/gateway/server/目录包含以下关键文件src/gateway/server-methods/定义各种RPC方法的处理逻辑src/gateway/protocol/定义通信协议的数据结构src/gateway/auth.ts实现连接认证逻辑通过WebSocket提供实时双向通信能力。客户端连接后可发送不同类型的消息如agent:run、config:get、session:send等Gateway根据消息类型将请求分发到对应的处理函数。src/gateway/auth.ts文件实现连接认证机制。当客户端尝试建立WebSocket连接时必须提供有效的认证凭证。Gateway会验证这些凭证只有通过验证的连接才会被接受并保持活跃状态。src/gateway/device-auth.ts文件处理设备级别的认证确保只有授权的设备可连接到Gateway。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/目录实现多认证配置管理。OpenClaw支持同时配置多个LLM提供商Anthropic等的认证信息并在运行时根据配置选择使用哪个提供商。相关文件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带有浏览器的沙箱用于需要浏览器环境的任务多渠道通信系统多渠道支持通过插件化架构实现核心代码位于src/channels/plugins/目录每个消息平台都有对应的插件实现。插件目录结构src/channels/plugins/actions/渠道操作定义src/channels/plugins/contracts/消息标准化处理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.tsCDP协议的核心封装src/browser/cdp.helpers.tsCDP辅助函数src/browser/chrome.tsChrome浏览器启动和管理src/browser/chrome.executables.tsChrome可执行文件路径查找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协议的渲染服务。A2UIAgent-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可用的所有工具实现258个文件涵盖从底层浏览器控制到高层业务操作的完整工具链。按功能分为以下几类浏览器控制工具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的实现展示工具系统的设计模式定义关键类型typeBrowserProxyFile{path:string;base64:string;mimeType?:string;};typeBrowserNodeTarget{nodeId:string;label?:string;};核心函数resolveBrowserNodeTarget实现浏览器目标解析逻辑支持多种目标类型sandbox在沙箱容器中的浏览器host在主机上运行的浏览器custom自定义浏览器实例node在远程设备节点上的浏览器当Agent调用浏览器工具时系统会根据配置和节点状态决定使用哪个浏览器实例。如果指定requestedNode参数工具会检查该节点是否连接node.connected isBrowserNode(node)然后将浏览器操作代理到该节点执行。这意味着Agent可控制运行在用户手机上的浏览器实现真正的跨设备操作。技能系统src/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允许技能通过环境变量覆盖默认配置三层技能体系从测试文件的命名可看出OpenClaw实现三层技能体系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需要执行一个需要隔离的操作时系统会通过config-hash.ts计算当前配置的哈希值在registry.ts中查找是否已有匹配的沙箱实例如果不存在通过docker.ts创建新的容器通过workspace.ts挂载必要的文件和目录在容器内执行操作通过runtime-status.ts监控执行状态操作完成后根据策略决定是保持容器运行还是销毁项目根目录的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.tsGateway专项测试配置vitest.extensions.config.ts扩展功能测试配置vitest.live.config.ts实时环境测试配置从src/目录下大量.test.ts文件几乎每个核心模块都有对应的测试用例。持续集成.github/目录包含GitHub Actions的工作流配置实现自动化的构建、测试和发布流程。package.json生产依赖 (dependencies)依赖包用途agentclientprotocol/sdkAgent客户端协议SDKaws-sdk/client-bedrockAWS Bedrock服务客户端AI模型服务buape/carbonDiscord机器人框架clack/prompts终端交互式提示库grammyjs/runnerGrammy Telegram机器人运行器grammyjs/transformer-throttlerGrammy机器人请求节流转换器homebridge/ciaomDNS/Bonjour服务发现库line/bot-sdkLINE聊天机器人SDKlydell/node-pty伪终端PTY实现用于终端模拟mariozechner/pi-agent-corePi Agent核心库mariozechner/pi-aiPi AI功能库mariozechner/pi-coding-agentPi编码助手代理mariozechner/pi-tuiPi终端用户界面库mozilla/readability网页内容提取和可读性优化sinclair/typeboxTypeScript类型验证和JSON Schemaslack/boltSlack机器人框架slack/web-apiSlack Web API客户端whiskeysockets/baileysWhatsApp Web客户端库ajvJSON Schema验证器body-parserHTTP请求体解析中间件chalk终端文本样式和颜色chokidar文件系统监听库chromium-bidiChromium BiDi协议实现cli-highlight命令行代码高亮commander命令行界面框架croner定时任务调度器crondetect-libc检测系统libc版本discord-api-typesDiscord API类型定义dotenv环境变量加载器expressWeb应用框架file-type文件类型检测grammyTelegram机器人框架hono轻量级Web框架jitiTypeScript/ESM运行时加载器json5JSON5解析器支持注释的JSONjszipZIP文件处理库linkedom轻量级DOM实现long长整数处理库markdown-itMarkdown解析和渲染node-edge-ttsEdge文本转语音服务osc-progress终端进度条OSC序列pdfjs-distPDF文件解析库playwright-core浏览器自动化核心库proper-lockfile文件锁实现qrcode-terminal终端二维码生成器sharp高性能图像处理库sqlite-vecSQLite向量扩展tarTAR归档文件处理tslogTypeScript日志库undici高性能HTTP客户端wsWebSocket客户端和服务器yamlYAML解析和序列化zodTypeScript模式验证库可选依赖 (optional Dependencies)依赖包用途napi-rs/canvas高性能Canvas实现基于Rustnode-llama-cppLLaMA大语言模型的Node.js绑定开发依赖 (devDependencies)依赖包用途grammyjs/typesGrammy框架类型定义lit-labs/signalsLit响应式信号实验性功能lit/contextLit上下文管理mariozechner/mini-lit轻量级Lit框架types/body-parserbody-parser类型定义types/expressExpress类型定义types/markdown-itmarkdown-it类型定义types/nodeNode.js类型定义types/proper-lockfileproper-lockfile类型定义types/qrcode-terminalqrcode-terminal类型定义types/wsWebSocket类型定义typescript/native-previewTypeScript原生预览版vitest/coverage-v8Vitest代码覆盖率工具docx-previewWord文档预览库litWeb Components库lucide图标库ollamaOllama本地AI模型客户端oxfmtRust编写的代码格式化工具oxlintRust编写的JavaScript/TypeScript Linteroxlint-tsgolintTypeScript Golint规则集quicktype-coreJSON Schema到类型定义转换器rolldownRust编写的打包工具signal-utils信号处理工具集tsxTypeScript执行器typescriptTypeScript编译器vitest单元测试框架wireit构建任务编排工具技术特点架构设计采用中心化Gateway控制平面所有模块通过WebSocket与Gateway通信实现松耦合的架构插件化渠道、工具、技能都采用插件化设计具有很强的可扩展性安全机制通过沙箱隔离、白名单控制、配对机制等多层安全措施保障系统安全跨平台能力通过节点系统和原生应用实现跨macOS、iOS、Android的设备控制能力工程实践使用现代化的开发工具链pnpm、Oxlint、vitest建立完善的测试体系和自动化流程