企业官网建设流程全解析

概述

官网，主要使用TypeScript开发、开源（GitHub，387K Star，81.3K Fork）个人AI助理，7x24小时在线、可部署在本地、能自己写代码进化、通过WhatsApp等就能指挥的赛博管家，官方文档。

核心逻辑：去中心化与反向控制。

核心特性：

• 能直接执行：浏览网页、文件操作、系统控制、应用集成；
• 自我进化：
• 去中心化交互：支持Telegram、WhatsApp、Discord、Slack、iMessage等

这些模块通过Gateway中心枢纽（控制平面）进行协调。所有客户端都通过WebSocket连接到Gateway，Gateway负责将请求路由到相应的处理模块。

注：该代码库关注度极高，大概率是GitHub第一，代码提交非常频繁，下面列出的部分源码在最新版很有可能因为重构被删除或调整路径。

Gateway

启动逻辑在src/gateway/boot.ts文件中实现，定义特殊的启动机制：系统会在启动时检查工作目录下是否存在BOOT.md文件，如果存在且内容不为空，会将其内容作为指令交给Agent执行。

核心函数runBootOnce实现如下逻辑：

exportasyncfunctionrunBootOnce(params:{cfg:ClawdbotConfig;deps:CliDeps;workspaceDir:string;agentId?:string;}):Promise<BootRunResult>

首先调用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.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可用的所有工具实现，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需要执行一个需要隔离的操作时，系统会：

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的工作流配置，实现自动化的构建、测试和发布流程。

package.json

生产依赖 (dependencies)

可选依赖 (optional Dependencies)

开发依赖 (devDependencies)

技术特点：

• 架构设计：采用中心化Gateway控制平面，所有模块通过WebSocket与Gateway通信，实现松耦合的架构
• 插件化：渠道、工具、技能都采用插件化设计，具有很强的可扩展性
• 安全机制：通过沙箱隔离、白名单控制、配对机制等多层安全措施，保障系统安全
• 跨平台能力：通过节点系统和原生应用，实现跨macOS、iOS、Android的设备控制能力
• 工程实践：使用现代化的开发工具链（pnpm、Oxlint、vitest），建立完善的测试体系和自动化流程