OpenClaw 源码架构解析
前置知识：本章节面向具备 TypeScript/Node.js 基础的开发者，建议先阅读 使用手册 了解 OpenClaw 的基本使用。 目标读者：希望从源码层面理解 OpenClaw 架构设计的开发者或贡献者。 维护状态：本文档基于 OpenClaw v2026.4.4 源码分析，描述的是当前实现细节。
1. 整体架构总览
1.1 系统定位
OpenClaw 是一个自托管的 AI 智能体网关，其核心职责是：
1.2 源码目录结构
openclaw/src/
├── gateway/ # 网关核心 - 消息入口/路由/会话管理
├── agents/ # 智能体引擎 - AI 推理/工具调用/上下文管理
│ ├── pi-embedded-runner/ # 核心 Runner
│ ├── skills/ # 技能系统
│ └── tools/ # 内置工具定义
├── sessions/ # 会话管理 - 对话上下文/状态/历史
├── channels/ # 通道接入 - 飞书/微信/Telegram/Discord 等
├── plugins/ # 插件系统 - 扩展机制/钩子
├── memory-host-sdk/ # 记忆系统 - 向量搜索/BM25/混合搜索
├── cron/ # 定时任务 - 调度器/心跳/自动化
├── config/ # 配置管理 - 热重载/环境变量/Schema
├── hooks/ # 钩子系统 - 生命周期事件/拦截点
├── mcp/ # MCP 协议 - Model Context Protocol
├── acp/ # ACP 协议 - Agent Communication Protocol
└── infra/ # 基础设施 - 日志/监控/安全2. Gateway：消息中枢
2.1 Gateway 在架构中的角色
Gateway 是整个系统的中央枢纽，负责：
2.2 消息处理流程
2.3 核心文件说明
| 文件 | 职责 | 关键导出 |
|---|---|---|
server.impl.ts | Gateway 启动入口 | startGatewayServer() |
server-chat.ts | 消息处理核心 | createAgentEventHandler() |
server-cron.ts | 定时任务调度 | buildGatewayCronService() |
server-methods.ts | RPC 方法列表 | coreGatewayHandlers |
server-ws-runtime.ts | WebSocket 处理 | attachGatewayWsHandlers() |
config-reload.ts | 配置热重载 | startGatewayConfigReloader() |
boot.ts | 启动引导 | runGatewayBoot() |
2.4 配置热重载机制
3. Agents：智能体引擎
3.1 Agent 循环完整流程
3.2 源码文件对应
| 阶段 | 源码文件 | 关键函数 |
|---|---|---|
| 入口 | pi-embedded-runner/run.ts | runEmbeddedPiAgent() |
| 模型推理 | pi-embedded-runner/model.ts | resolveModelAsync() |
| 工具调用 | pi-embedded-runner/run/attempt.ts | runEmbeddedAttempt() |
| 上下文压缩 | pi-embedded-runner/compact.ts | runPostCompactionSideEffects() |
| 工具定义 | agents/ | bash-tools.exec.ts, bash-tools.ts |
3.3 模型选择与降级
4. Sessions：会话管理
4.1 会话范围体系
4.2 会话键格式
直接消息: agent:<agentId>:main
群组消息: agent:<agentId>:<channel>:group:<id>
定时任务: cron:<jobId>4.3 上下文压缩机制
5. Channels：通道接入
5.1 通道插件架构
5.2 飞书接入原理
6. Plugins：插件系统
6.1 插件架构
6.2 插件类型
| 类型 | 说明 |
|---|---|
| Channel Plugin | 通道接入（飞书/微信/Telegram） |
| Tool Plugin | 工具扩展 |
| Memory Plugin | 记忆提供者 |
| Provider Plugin | AI 模型提供商 |
7. Hooks：钩子系统
7.1 生命周期钩子
7.2 钩子类型
| 钩子 | 触发时机 | 作用 |
|---|---|---|
before_model_resolve | 模型解析前 | 选择和初始化 AI 模型 |
before_prompt_build | 提示构建前 | 组装上下文到最终提示 |
agent_end | 运行结束后 | 智能体完成一次运行 |
before_tool_call | 工具调用前 | 拦截和验证工具参数 |
after_tool_call | 工具调用后 | 处理工具返回结果 |
8. MCP：Model Context Protocol
8.1 MCP 架构
8.2 MCP 用途
- 允许外部 MCP 客户端（如 Claude Desktop）连接到 OpenClaw
- 提供标准化的工具调用协议
- 支持动态发现和调用工具
9. ACP：Agent Communication Protocol
9.1 ACP 架构
9.2 ACP 用途
- 多智能体间的通信协议
- 持久化绑定管理
- 会话状态同步
- 访问策略控制
10. Skills：技能系统
10.1 技能加载优先级
10.2 技能结构
skills/
└── <skill-name>/
├── SKILL.md # 技能定义
├── tools/ # 工具实现
└── references/ # 参考资料11. Memory：记忆系统
11.1 两层记忆架构
11.2 记忆写入流程
12. Cron：定时任务
12.1 定时任务架构
12.2 任务执行模式
13. 配置系统
13.1 配置加载顺序
13.2 关键配置项
14. 安全机制
14.1 沙盒隔离
14.2 访问控制
15. 源码学习路径
15.1 推荐阅读顺序
1. 入门：理解整体架构
└─ src/gateway/server.impl.ts (Gateway 入口)
└─ src/gateway/boot.ts (启动引导)
2. 消息流：理解请求处理
└─ src/gateway/server-chat.ts
└─ src/channels/plugins/ (通道接入)
3. 智能体：理解 AI 推理
└─ src/agents/pi-embedded-runner/run.ts
└─ src/agents/model.ts
4. 会话：理解上下文管理
└─ src/sessions/session-id.ts
└─ src/sessions/session-key-utils.ts
5. 工具：理解执行机制
└─ src/agents/bash-tools.exec.ts (exec 工具)
└─ src/agents/tools/web-tools.ts (browser 工具)
6. 扩展：理解插件系统
└─ src/plugins/registry.ts
└─ src/hooks/hooks.ts15.2 调试技巧
bash
# 查看 Gateway 日志
openclaw gateway --verbose
# 诊断配置问题
openclaw doctor
# 查看会话历史
openclaw sessions list
# 测试工具调用
openclaw tools test <tool-name>16. 关键类/函数索引
| 类/函数 | 文件 | 作用 |
|---|---|---|
startGatewayServer | gateway/server.impl.ts | 启动 Gateway |
runGatewayBoot | gateway/boot.ts | 执行启动引导 |
createAgentEventHandler | gateway/server-chat.ts | 创建消息处理器 |
runEmbeddedPiAgent | agents/pi-embedded-runner/run.ts | 执行智能体 |
resolveModelAsync | agents/pi-embedded-runner/model.ts | 异步获取模型 |
buildEmbeddedRunPayloads | agents/pi-embedded-runner/run/payloads.ts | 构建请求载荷 |
runEmbeddedAttempt | agents/pi-embedded-runner/run/attempt.ts | 执行单次尝试 |
sessionLikelyHasOversizedToolResults | agents/tool-result-truncation.ts | 检测工具结果大小 |