OpenClaw 项目架构（开发者视角）

本文面向阅读源码的开发者，按“仓库分层 → 核心运行时 → 插件边界 → 关键数据流”的顺序，整理 OpenClaw 的整体架构与主要模块。

本文由AI辅助生成

1. OpenClaw源码架构

OpenClaw 是一个“多渠道 AI 网关 + 可扩展插件系统 + 多端节点（macOS/iOS/Android）”的组合：

• CLI：负责安装、配置、诊断（doctor）、启动守护进程、启动网关、发送消息、运行 agent 等。
• Gateway（网关控制平面）：常驻进程，提供 WebSocket/HTTP 控制接口、Control UI、配置热加载、通道管理、插件装载、cron/hook 等。
• Agent Runtime（推理/工具执行）：处理会话、模型选择/回退、工具调用、技能加载、消息投递与会话存档等。
• Plugins（插件）：把“通道（channels）”“模型/Provider”“技能/工具”“安装/Doctor/配置 UI hints”等扩展点外置为插件。
• Control UI：浏览器端控制面板（单独的 ui/ workspace 包）。
• 移动/桌面端 App：apps/ 里包含 iOS/Android/macOS 工程，用于节点能力（语音/相机/Canvas 等）与产品形态。

从代码组织上看：src/ 是核心平台；extensions/ 是仓库内自带的“打包插件”；src/plugin-sdk/ 是插件对外契约；ui/ 是 Web UI；apps/ 是端侧应用。

2. 仓库结构总览

只列出与架构理解最相关的目录/文件。

• openclaw.mjs：发布到 npm 的 openclaw 可执行入口。做 Node 版本校验、compile cache、以及导入 dist/entry.(m)js 的引导。
• src/：核心 TypeScript 源码。
  • src/entry.ts：构建后对应 dist/entry.js，负责 CLI 启动前的环境准备、fast-path help/version、以及进入 src/cli/run-main.ts。
  • src/cli/：CLI 命令注册、参数解析、子命令路由、交互式提示、容器/开发 profile 等。
  • src/commands/：CLI 子命令的实现层（例如 agent, gateway, doctor, status 等）。
  • src/gateway/：网关服务器（WS/HTTP）、通道管理、插件 bootstrap、runtime services、热重载与健康检查等。
  • src/gateway/protocol/：网关控制平面的协议与 schema（Zod/类型定义等），并通过脚本生成 JSON/Swift 等产物。
  • src/agents/：agent 执行链路（会话、模型选择、技能/工具、投递、转录持久化等）。
  • src/plugins/：插件发现、manifest、加载器、registry、插件 runtime 以及与网关/通道/工具的编排。
  • src/plugin-sdk/：插件 SDK 的公开契约（构建后通过 openclaw/plugin-sdk/* 子路径导出）。
  • src/config/：配置文件、schema、默认值、paths、legacy 兼容、session store 等。
  • src/daemon/：把网关/相关能力安装为后台服务的跨平台适配（launchd/systemd/schtasks 等）。
  • src/cron/：cron 调度与投递（与网关的 cron service 集成）。
  • src/hooks/：hook 配置、安装/更新、加载器与策略（例如 Gmail 相关 hook 也在该目录）。
  • src/secrets/：SecretRef 解析、审计、运行时快照与应用。
  • src/channels/：通道层的核心类型与插件桥接（核心实现细节与对外 contract 有严格边界）。
  • src/infra/：跨平台基础设施（网络、重试、二进制依赖、端口、WS、WAS/WSL、SSRF 防护等）。
  • src/media/：媒体处理（音频/图片/视频/QR、存储、TTL 清理等）。
  • src/tui/：终端 UI（表格、主题、交互命令）。
  • src/logging/：日志采集/格式化/脱敏/级别与状态管理。
  • src/terminal/：TTY/ANSI 友好的输出能力（表格、主题、链接等），被 CLI/TUI/网关日志复用。
• extensions/：仓库内的“bundled plugins”（每个子目录是一个 workspace package）。
  • 例如 extensions/irc/：包含 openclaw.plugin.json（manifest）、index.ts（插件入口）、src/（插件内部实现）等。
  • extensions/AGENTS.md：说明“extensions 与第三方插件等价”的边界规则。
• ui/：Control UI（Lit + Vite）。构建产物由网关静态托管（由 src/gateway/ 的 Control UI 逻辑提供服务）。
• apps/：iOS/Android/macOS 工程（与网关/节点能力相关）。
• docs/：产品/开发文档（Mintlify）。大量“概念/命令/通道/插件”说明可作为源码阅读的配套背景。

3. 运行时分层与核心组件

3.0 顶层组件关系图（简化）

                    ┌──────────────────────────┐
                    │          CLI             │
                    │ openclaw.mjs + src/cli/* │
                    └────────────┬─────────────┘
                                 │ commands
                                 v
┌───────────────────────────────────────────────────────────────┐
│                           Gateway                               │
│            src/gateway/* + src/plugins/* + src/config/*         │
│  WS/HTTP + Control UI + Channels + Cron/Hooks + Secrets + State │
└───────────────┬───────────────────────────────┬───────────────┘
                │                               │
                │ serve UI / API                │ node/device sessions
                v                               v
     ┌────────────────────┐           ┌─────────────────────────┐
     │     Control UI      │           │   macOS/iOS/Android     │
     │        ui/*         │           │         apps/*          │
     └────────────────────┘           └─────────────────────────┘
                │
                │ inbound events / outbound delivery
                v
     ┌──────────────────────────────────────────────────────────┐
     │                Channels / Channel Plugins                 │
     │        core types (src/channels/*) + extensions/*         │
     └──────────────────────────┬───────────────────────────────┘
                                │ route → session → agent
                                v
                     ┌──────────────────────────┐
                     │       Agent Runtime      │
                     │  src/agents/* + tools    │
                     └──────────────────────────┘

3.1 CLI 启动链路（从可执行文件到命令实现）

入口链路可概括为：

1. openclaw.mjs（npm bin）：
   • 校验 Node 版本、启用 compile cache
   • fast-path 输出根 --help
   • 否则导入构建产物 dist/entry.js / dist/entry.mjs
2. src/entry.ts：
   • 环境归一化（Windows argv、NO_COLOR、compile cache、warning filter、一些 runtime marker）
   • fast-path 处理根 --version
   • 进入 src/cli/run-main.ts 的 runCli(argv)
3. src/cli/run-main.ts：
   • dotenv 装载策略、运行时守卫（最低 runtime）
   • Commander program 构建与命令注册
   • 支持“按需注册”：先注册 primary command，再按策略加载/注册插件命令（避免整库启动成本）
   • program.parseAsync(...) 后进入具体命令 handler（多落在 src/commands/）

关键文件：

• openclaw.mjs
• src/entry.ts
• src/cli/run-main.ts
• src/cli/program.ts（Commander program 构建入口）
• src/commands/*（命令实现，通常进一步调用 gateway/agent/plugins/config 等模块）

3.2 Gateway（控制平面常驻进程）

网关是常驻服务，职责集中在“控制 + 编排”，而不是把所有业务都硬编码在 core：

• 提供 WebSocket/HTTP 服务：Control UI、状态/健康、配置写入、hook、cron、节点/设备会话、以及部分 API endpoints（例如 OpenAI/OpenResponses 风格端点开关）。
• 启动与管理 Channel 插件：在网关启动时加载通道插件并保持稳定的通道 registry（避免后续非主加载覆盖通道插件快照）。
• 启动与管理 Plugin Runtime：加载、缓存、热重载、deferred bootstrap，并将插件暴露到各 runtime surface（channel/httpRoute/tools 等）。
• 维护 运行时状态：presence/health cache、任务队列、诊断心跳、TLS/tailscale 等。

关键文件：

• src/gateway/server.ts / src/gateway/server.impl.ts：网关启动主逻辑（startGatewayServer）。
• src/gateway/server-startup-*.ts：启动前准备（配置快照、插件 bootstrap、早期 runtime）。
• src/gateway/server-channels.ts：通道管理（结合 src/channels/plugins/*）。
• src/gateway/server-control-ui-root.ts：Control UI 静态资源服务与 root state。
• src/gateway/server-reload-handlers.ts：配置/插件热重载相关。

3.3 Agent Runtime（会话、模型、技能/工具、投递）

agent 相关逻辑集中在 src/agents/，并通过 CLI 命令 openclaw agent ...、网关 inbound、以及内部子 agent 调用等方式触发。

典型职责：

• 会话解析与持久化：通过 session key / session store 把“一个对话的上下文”绑定到 agentId 与 workspace。
• 模型选择与回退：支持 provider/model override、thinking level、fallback 策略等。
• 技能/工具加载：从 workspace/插件 registry 构建当前 agent 可用的 skills/tool snapshot，并带版本刷新策略。
• 投递与回复：把输出投递到指定 channel target（可选），或仅在本地记录 transcript。
• 与 ACP（control-plane）集成：在某些模式下通过 ACP session manager 管理运行与事件。

关键文件：

• src/agents/agent-command.ts：agentCommand(...) 作为统一入口（CLI 与内部调用共用）。
• src/agents/skills.ts、src/agents/skills/*：技能快照与过滤/刷新逻辑。
• src/auto-reply/*：回复分发、thinking 配置、模板等（agent 产出的消息如何被调度/分块/投递）。

3.4 Plugins（插件系统）

插件系统是 OpenClaw 可扩展能力的核心：通道、provider、工具、hook、UI hints、doctor 修复等都尽可能通过插件表达，而不是写死在 core。

插件系统的几个关键概念：

• Plugin Manifest：openclaw.plugin.json 是不执行代码即可读取的元数据（用于 discovery、setup、配置 UI hints 等）。
• Plugin Registry：加载后的插件集合及其 runtime surface（commands、channel plugins、http routes、tools 等）。
• Plugin Loader：负责 discovery、激活策略、模块加载（Jiti/alias）、schema 校验、缓存与并发保护。
• Plugin SDK：对外 contract 固化在 src/plugin-sdk/*，构建后通过 openclaw/plugin-sdk/* 子路径导出，插件禁止 deep-import core internals。

关键文件：

• src/plugins/loader.ts：插件发现 + 加载主流程（cache、alias、schema 校验、激活策略等）。
• src/plugins/runtime.ts：进程级 registry 状态（active registry + 针对 httpRoute/channel 的 pin 机制）。
• src/plugins/registry.ts：registry 结构与记录类型。
• src/plugin-sdk/：插件 SDK（公开子路径导出见根 package.json 的 exports）。
• extensions/*：仓库内 bundled plugins（与第三方插件同边界，见 extensions/AGENTS.md）。

3.5 Gateway Protocol（控制平面协议）

网关的 WS/HTTP 控制平面并不是“随便发 JSON”，而是有明确的协议与 schema：

• src/gateway/protocol/schema.ts 与 src/gateway/protocol/schema/*：协议的类型/校验定义（包含 agents/models/skills、channels、cron、devices/nodes、secrets 等多个子域）。
• src/gateway/protocol/index.ts：对外聚合导出。
• 根 package.json 的脚本：
  • pnpm protocol:gen：生成协议相关产物（例如 dist/protocol.schema.json）。
  • pnpm protocol:gen:swift：生成 Swift 模型（用于 macOS/iOS 侧）。
  • pnpm protocol:check：校验生成产物未漂移。

3.6 Daemon（后台服务安装与管理）

OpenClaw 需要把网关作为常驻进程运行，因此 core 内置跨平台“服务安装/管理”能力：

• src/daemon/launchd.ts：macOS（launchd user service）
• src/daemon/systemd.ts：Linux（systemd user service）
• src/daemon/schtasks.ts：Windows（计划任务）
• src/daemon/service.ts：抽象层与统一入口（CLI 命令通常调用这里）

4. 关键数据流（端到端）

4.1 启动网关（gateway run）

高层流程（省略大量细节）：

1. CLI 进入 openclaw gateway ... 对应命令 handler（位于 src/commands/，最终调用 startGatewayServer）。
2. src/gateway/server.impl.ts：
   • 读取启动配置快照、应用 override
   • 激活运行时 secrets（可能触发状态事件）
   • 进行网关 auth/tailscale/TLS 等准备
   • bootstrap 插件（包含通道插件、http handlers、工具等）
   • 启动 WS/HTTP 服务与各类 runtime service（cron、hooks、diagnostic、readiness 等）
3. 网关开始对外提供 Control UI/WS API，并持续监听配置变化进行热重载。

4.2 入站消息到 agent 再到投递

典型“某个 channel 收到消息 → 触发 agent → 回发”的链路可以理解为：

1. 通道插件在网关内建立连接/轮询/订阅，并把入站事件转换为统一 envelope（通道 contract 负责抽象）。
2. 路由与会话选择：根据配置（agents、channels、allowlist、pairing、groups 等）确定目标 agentId/sessionKey。
3. Agent 执行：调用 agentCommand(...) 或等价的运行入口。
   • 装载 config + secrets、解析会话、准备 workspace、装载技能/工具快照
   • 选择模型并执行推理（含工具调用/媒体处理等）
4. 回复分发：
   • 生成 reply payload（可能分块、可能有引用/附件）
   • 由 channel 插件完成“投递回原通道/目标通道”
5. 持久化：会话 store/transcript、事件日志、媒体临时文件等按各自模块落盘。

4.3 “插件命令”如何进入 CLI

CLI 具备“按需加载插件命令”的策略（避免每次运行都全量装载插件）：

• 在 src/cli/run-main.ts 中会先判断 primary command 是否需要只注册主命令；
• 若需要插件命令，则调用 src/plugins/cli.ts 触发“从已验证 config 中注册插件命令”；
• 如果命令实际上是 runtime slash command（只在聊天/运行时可用），会给出明确提示（见 resolveMissingPluginCommandMessage）。

5. 配置、状态与持久化

5.1 配置（Config）

• src/config/ 聚合了 config IO、schema、defaults、legacy、paths 等。
• src/config/config.ts 是“对外 re-export”入口，真正实现主要在 src/config/io.ts、src/config/schema.ts、src/config/validation.ts 等。
• 网关启动时会读取“启动快照”，并支持运行时写回/热重载（见 src/gateway/server.impl.ts 的 loadGatewayStartupConfigSnapshot、registerConfigWriteListener 等调用链）。

5.2 会话（Sessions）

• sessionKey 把对话绑定到 agentId + 会话形态（main/group 等）。
• session store 的路径与格式在 src/config/sessions/* 里定义，并被 agent/gateway/CLI 共用。
• agent 执行完成后会更新 session store、写 transcript（见 src/agents/agent-command.ts 中的 session 相关调用链）。

5.3 Secrets

• secrets 的解析/审计/应用位于 src/secrets/。
• 网关启动时会激活运行时 secrets，并维护 snapshot，供各 runtime surface 使用（见 src/gateway/server.impl.ts 中的 secrets activator 与 snapshot 管理）。

5.4 媒体与临时文件

• src/media/ 负责媒体解析、fetch、存储、mime、二维码图片等。
• 网关维护媒体 TTL（在 src/gateway/server.impl.ts 中可见 TTL 上限与清理策略参数）。

6. 插件边界（非常重要）

OpenClaw 把 extensions/ 当作“第三方插件同等级边界”来约束 core 与插件的耦合方式（这能显著降低 core 的硬编码特殊情况）。

核心规则（摘要，详见 extensions/AGENTS.md 与各模块的 AGENTS.md）：

• 插件生产代码只允许通过 openclaw/plugin-sdk/* 与自身 api.ts / runtime-api.ts 等 barrel 与 core 交互。
• 禁止插件 deep-import src/** 或其他插件的 src/**。
• 如果 core 需要复用某个 bundled plugin 的能力，应先通过该插件的 api.ts 暴露，再视情况加入 src/plugin-sdk/<id>.ts 外部契约。

对应的 core 侧组织：

• src/plugin-sdk/：公开 contract（构建后通过根 package.json#exports 导出）。
• src/plugins/：loader + registry + runtime surfaces（负责把插件能力编排进网关/agent/CLI）。
• src/channels/：通道核心类型与桥接（实现细节与插件 contract 分离）。

7. 多端与 UI（与 core 的关系）

7.1 Control UI（ui/）

• ui/ 是单独的 workspace 包（见 ui/package.json），基于 Vite + Lit。
• 网关在运行时托管 UI 静态资源，并通过 WS/HTTP 与网关交互（Control UI 相关服务在 src/gateway/server-control-ui-root.ts 等文件）。

7.2 Apps（apps/）

• apps/macos/：macOS 菜单栏 App 与 Canvas/节点能力相关。
• apps/ios/、apps/android/：移动端节点能力与配套体验。
• 端侧与网关的通信协议与模型主要在 src/gateway/protocol/ 定义，并通过 pnpm protocol:gen:swift 生成 Swift 模型供端侧工程使用。

8. 构建、输出与工作区

8.1 构建产物

• pnpm build 生成 dist/（Node 运行与发布包使用）。
• openclaw.mjs 在运行时导入 dist/entry.(m)js，因此源码树直接运行通常走 pnpm dev / pnpm openclaw ... 这类脚本。

8.2 Workspace（pnpm）

pnpm-workspace.yaml 定义的 workspace 主要包括：

• 根包（.）：核心 CLI/Gateway/SDK 导出。
• ui/：Control UI。
• extensions/*：bundled plugins。

9. “从哪里开始读源码”建议路线

如果目标是快速建立 mental model，可以按下列顺序阅读（每一步都能把“谁调用谁”串起来）：

1. CLI 引导：openclaw.mjs → src/entry.ts → src/cli/run-main.ts
2. 网关主入口：src/gateway/server.impl.ts（关注启动阶段做了哪些准备与 bootstrap）
3. Agent 主入口：src/agents/agent-command.ts（关注会话解析、workspace、技能快照、模型选择与投递）
4. 插件加载：src/plugins/loader.ts + src/plugins/runtime.ts（理解 registry/cache/pin/alias）
5. 插件对外契约：src/plugin-sdk/* 与任意一个 extensions/<plugin>/openclaw.plugin.json + index.ts