openclaw关键文件与执行链路

1. CLI 启动链路

1.1 openclaw.mjs

作用：

• 这是全局安装后二进制 openclaw 的真正入口。
• 检查 Node 版本。
• 尝试加载 dist/entry.js / dist/entry.mjs。
• 对 --help 做快速输出优化。
• 当源码树未构建时给出清晰错误。

意义：

• 这是"发布态用户体验"的第一层保护。
• 也是 openclaw 作为 npm CLI 能否顺利启动的第一道门。

1.2 src/entry.ts

作用：

• 归一化环境变量与 CLI 参数。
• 处理版本快路径、帮助快路径。
• 处理 CLI respawn 计划。
• 负责最终把执行转给 src/cli/run-main.ts。

意义：

• 它相当于源码态的真正 CLI 启动总线。
• 负责把运行环境调整到 OpenClaw 期望的形态。

1.3 src/cli/run-main.ts

作用：

• 处理 --profile、--container、.env 加载、PATH 确保等启动细节。
• 路由到特殊命令路径。
• 创建 commander program。
• 在 parse 前按需注册 core CLI 和 plugin CLI。

意义：

• 它是 CLI 框架装配的中心。
• 说明 OpenClaw 把"命令行框架"和"命令业务逻辑"刻意拆开了。

1.4 src/cli/program/build-program.ts

作用：

• 真正创建 Commander Command 实例。
• 安装 help / preaction / context。
• 注册所有命令。

意义：

• 这是 CLI 命令树被构建出来的那个点。

2. Gateway 启动链路

2.1 src/cli/gateway-cli/run.ts

作用：

• 解析 gateway run 的参数。
• 合并命令行参数与配置。
• 做控制台、端口、密码、tailscale、UI 构建等启动前处理。
• 最终进入 gateway run loop。

2.2 src/gateway/server.impl.ts

作用：

• Gateway 的大装配文件。
• 负责：
  • 配置载入与刷新
  • control UI 资产
  • plugin runtime
  • channel manager
  • node registry
  • secrets runtime snapshot
  • task registry maintenance
  • heartbeat / diagnostics
  • Gateway methods / events / WS handlers

意义：

• 这是"控制平面总装厂"。
• 如果想知道 Gateway 到底把哪些子系统串了起来，看这个文件最直接。

2.3 src/gateway/protocol/schema.ts

作用：

• 汇总 Gateway 协议 schema 导出。
• 把 agent、channels、frames、nodes、sessions、secrets、wizard 等协议片段聚合成统一入口。

意义：

• 它是 operator clients / nodes / UI 与 Gateway 之间的类型合同核心。

3. Plugin 启动链路

3.1 src/plugins/manifest-registry.ts

作用：

• 从 bundled / workspace / global / config roots 发现插件候选。
• 读取 openclaw.plugin.json 等 manifest。
• 形成 manifest-first 的插件注册表。

意义：

• 它保证了"先看元数据，再决定是否加载运行时代码"的架构原则。

3.2 src/plugins/loader.ts

作用：

• 真正把插件模块加载进来。
• 使用 jiti 与 SDK alias map 解决运行时模块加载。
• 管理 registry cache、reentry 防护、activation state、runtime 构建。

意义：

• 这是 OpenClaw 插件系统最关键的内部文件之一。
• 也是典型的维护热点。

3.3 src/plugins/runtime/index.ts

作用：

• 构建 plugin runtime facade。
• 把 agent、subagent、config、channel、events、logging、tts、mediaUnderstanding 等能力以懒加载方式暴露给插件。

意义：

• 它让插件看到的是稳定 runtime 合同，而不是 core 内部细节。

3.4 src/plugins/cli.ts

作用：

• 负责 plugin CLI descriptors 与命令组注册。
• 支持 eager/lazy 两种模式。

意义：

• 说明插件不仅能提供 provider/channel/runtime，也能提供自己的 CLI surface。

3.5 src/plugin-sdk/core.ts

作用：

• 对插件公开大量类型、工具函数、channel/provider 合同、配置辅助、日志能力。

意义：

• 这是插件作者真正依赖的公共 SDK 面之一。
• 改动这里就可能影响 bundled plugin 与第三方插件兼容性。

4. Channel 体系链路

4.1 src/channels/plugins/registry.ts

作用：

• 从 active plugin runtime 中拿到 channel plugin registry。
• 排序、去重、按 ID 查找。
• 为 CLI 和 Gateway 提供统一 channel plugin 查询入口。

4.2 src/channels/plugins/index.ts

作用：

• 把 channel plugin 注册表、allowlist、config match、approval adapter 等能力导出为公共入口。

意义：

• 从代码导航角度，它是 src/channels/plugins/* 的门面文件。

5. Agent 执行链路

5.1 src/commands/agent.ts

作用：

• 把 openclaw agent 命令映射到真正的 agent runtime。
• 该文件本身只是薄导出，真实逻辑放在 src/agents/agent-command.ts。

意义：

• 它体现了 commands 和 agents 的职责分离。

5.2 src/agents/agent-command.ts

作用：

• 负责一次 agent 执行的大部分编排：
  • 配置与 secret 解析
  • session 解析
  • model / thinking / verbose 解析
  • auth profile 处理
  • workspace / skills 快照
  • run attempt
  • 结果派发与 session store 更新

意义：

• 这是 OpenClaw agent loop 的高层 orchestrator。

5.3 src/agents/pi-embedded-runner/run/attempt.ts

作用：

• 这是 agent 真正跑一轮的重文件。
• 负责更底层的：
  • prompt / context 形成
  • 模型执行
  • tool 调用
  • 流式事件
  • compaction / retry / timeout
  • transcript 持久化细节

意义：

• 这是最接近"OpenClaw agent engine 内核"的文件之一。

6. UI 执行链路

6.1 ui/src/ui/app.ts

作用：

• Control UI 的主 LitElement。
• 持有大量界面状态：
  • chat
  • config
  • devices
  • approvals
  • dreaming
  • skills
  • tools
  • usage

意义：

• 这是前端主壳。
• 同时也暴露出 UI 状态集中度较高的问题。

7. 代表性扩展入口

7.1 extensions/openai/index.ts

代表一种"provider 聚合型插件"：

• 一个插件注册多个能力：
  • 文本 provider
  • Codex CLI backend
  • 图像生成
  • 语音
  • 实时语音/转录
  • 媒体理解
  • 视频生成

说明 OpenClaw 的插件单位更像"供应商边界"，不是只包一条 API。

7.2 extensions/telegram/index.ts

代表一种"bundled channel entry"：

• 声明 channel plugin runtime
• 声明 secret contract
• 声明 setup/runtime 入口

说明渠道插件采用 metadata + runtime seam 方式接入。

7.3 extensions/browser/index.ts

代表一种"工具型平台插件"：

• 注册浏览器能力
• 声明 security audit collectors
• 提供节点宿主命令

说明插件不只用于模型和消息渠道，也用于平台工具。

7.4 extensions/voice-call/index.ts

代表一种"功能插件"：

• 有自己的 config schema
• 有自己的 Gateway handlers
• 依赖外部实时语音/TTS 能力
• 有自己的 CLI 和运行时

说明 OpenClaw 插件可以扩展成相对独立的子产品。

7.5 extensions/memory-core/index.ts

代表一种"memory capability plugin"：

• 注册 memory capability
• 注册 memory 工具
• 提供 memory CLI
• 提供 dreaming/flush plan/public artifacts

说明 Memory 也是插件边界，而不是硬编码 core feature。

8. 关键文件总表

文件	作用
openclaw.mjs	发布态 CLI wrapper 与 dist 引导。
src/entry.ts	源码态主入口，处理环境与快路径。
src/cli/run-main.ts	CLI 主装配器。
src/cli/program/build-program.ts	Commander program 构建点。
src/cli/deps.ts	懒加载 channel outbound sender。
src/cli/gateway-cli/run.ts	gateway run 命令实现。
src/commands/agent.ts	agent 命令业务入口。
src/agents/agent-command.ts	agent 高层执行编排。
src/agents/pi-embedded-runner/run/attempt.ts	agent 实际执行核心。
src/gateway/server.impl.ts	Gateway 总装配文件。
src/gateway/protocol/schema.ts	Gateway 协议总入口。
src/gateway/server-methods/chat.ts	聊天/会话相关 Gateway methods。
src/plugins/manifest-registry.ts	插件元数据注册表。
src/plugins/loader.ts	插件实际加载器。
src/plugins/runtime/index.ts	plugin runtime facade。
src/plugins/cli.ts	插件 CLI 注册。
src/plugins/contracts/registry.ts	插件契约与能力注册快照。
src/channels/plugins/registry.ts	channel plugin 注册与查找。
src/plugin-sdk/core.ts	对插件公开的核心 SDK 面。
src/config/config.ts	配置公共导出与入口。
ui/src/ui/app.ts	Control UI 主壳。
extensions/openai/index.ts	供应商聚合型插件入口示例。
extensions/telegram/index.ts	渠道插件入口示例。
extensions/browser/index.ts	工具插件入口示例。
extensions/voice-call/index.ts	功能插件入口示例。
extensions/memory-core/index.ts	memory 插件入口示例。

9. 执行链路总图

9.1 CLI 到 Agent

openclaw

-> openclaw.mjs

-> src/entry.ts

-> src/cli/run-main.ts

-> src/cli/program/build-program.ts

-> src/commands/agent.ts

-> src/agents/agent-command.ts

-> src/agents/pi-embedded-runner/run/attempt.ts

9.2 CLI 到 Gateway

openclaw gateway run

-> src/cli/gateway-cli/run.ts

-> Gateway run loop

-> src/gateway/server.impl.ts

9.3 Gateway 到插件

Gateway 启动

-> src/plugins/manifest-registry.ts

-> src/plugins/loader.ts

-> src/plugins/runtime/index.ts

-> channel/provider/tool/service plugin 注册进 registry

9.4 UI 到 Gateway

Browser 打开 Control UI

-> ui/src/ui/app.ts

-> ui/src/ui/app-gateway.ts

-> Gateway WS/HTTP methods

-> 更新状态、聊天、配置、设备与日志视图

10. 总结

如果只看 OpenClaw 的 README，会觉得它功能很多。

如果看这些关键文件，会发现它并不是随意堆功能，而是围绕下面几条主线组织的：

• CLI 主线
• Gateway 主线
• Agent 主线
• Plugin 主线
• Channel 主线
• UI 主线

这也是它能在复杂度很高的情况下，仍然保持整体可理解性的主要原因。