OpenClaw 代码深度剖析 第一篇：20万 Star 背后的架构
OpenClaw 拥有 20 万+ GitHub star、一个维基百科词条，创始人刚刚加入了 OpenAI。但抛开叙事，一个根本问题浮现：代码到底做了什么？
我们克隆了仓库并阅读了源码。这个三篇系列将带你深入 209,000 行 TypeScript 代码。
- 第一篇（本文）： 架构 — monorepo 布局、agent 运行时、gateway、路由
- 第二篇：Skills、Memory 与 Tools
- 第三篇：安全、质量与最终评价
仓库概览
OpenClaw 是一个基于 pnpm 的 monorepo，目标运行环境为 Node.js 22+（纯 ESM，TypeScript 5.9 严格模式）。
| 目录 | 用途 | 规模 |
|---|---|---|
src/ |
核心运行时 | ~50 个子目录，~800 个文件 |
extensions/ |
Channel 适配器、memory 后端、auth 提供者 | 37 个 plugin |
skills/ |
内置技能定义（Markdown 文件） | 52 个技能 |
apps/ |
macOS、iOS、Android 伴侣应用 | 3 个应用 |
packages/ |
旧名称兼容层（Clawdbot、Moltbot） | 2 个包 |
ui/ |
基于 React 的 Web 界面（A2UI） | 1 个包 |
核心依赖：Express 5.2、Zod 4.3、Vitest 4.0、oxlint、sharp、grammy（Telegram）、@slack/bolt、discord.js、@whiskeysockets/baileys（WhatsApp）、playwright-core。
75+ 个直接依赖，通过 pnpm workspaces 组织管理。
最重要的发现：OpenClaw 没有实现自己的 Agent 循环
这是最关键的架构洞察。
核心的 LLM 交互循环 — prompt 构建、流式输出、工具执行、错误恢复 — 完全委托给了 @mariozechner/pi-agent-core，这是一个来自独立仓库（github.com/badlogic/pi-mono，作者 Mario Zechner）的 pre-1.0 包。
OpenClaw 使用了 pi-mono 的四个包：
| 包名 | 版本 | 用途 |
|---|---|---|
pi-agent-core |
0.53.0 | 有状态 agent 循环、工具执行、事件流 |
pi-ai |
0.53.0 | 统一 LLM API，支持 17+ 供应商 |
pi-coding-agent |
0.53.0 | 文件操作、shell 工具、grep/find |
pi-tui |
0.53.0 | 终端 UI |
Agent 生命周期通过 pi-agent-core 流转：
agent_start → turn_start → message_start → message_update* → message_end
→ [tool_execution_start → tool_execution_update* → tool_execution_end]*
→ turn_end → agent_endsteer()（运行中中断）、followUp()（排队任务）、abort()、思考预算、工具错误自修复 — 全部来自 pi-agent-core。
那 OpenClaw 到底构建了什么？ 围绕这个循环的一切基础设施：路由、channels、skills、memory、沙箱和 gateway。
Gateway：161 个文件构成的控制平面
一切流量都经过 WebSocket + HTTP 服务器。默认绑定：ws://127.0.0.1:18789（仅本地回环）。
认证（4 种模式）
src/gateway/auth.ts → authorizeGatewayConnect()| 模式 | 使用场景 |
|---|---|
none |
仅开发环境 |
token |
Bearer token 匹配 |
password |
密码认证 |
trusted-proxy |
代理头验证 |
所有密钥匹配使用常量时间比较（safeEqualSecret()）。速率限制按 IP 配置。Tailscale 集成提供安全的局域网访问。
Chat 会话管理
三个注册表驱动聊天系统：
- ChatRunRegistry — 将 session ID 映射到活跃的聊天运行（队列式）。
- ChatRunState — 聚合缓冲区、delta 时序和中止追踪。
- ToolEventRecipientRegistry — 追踪接收工具事件的 WebSocket 客户端（TTL 制，默认 10 分钟）。
文本 delta 以最小 150ms 间隔节流。心跳抑制防止后台操作中的频繁 UI 更新。dropIfSlow 背压机制保护慢消费者。
启动序列
Gateway 启动时读取工作区中的 BOOT.md 文件，将其作为 agent prompt 执行 — 用于自动化启动任务（发送通知、检查状态等）。启动过程创建临时会话（boot-{timestamp}-{uuid}），运行 agent，然后恢复原始会话映射。
路由：8 级优先级
来自 channels 的消息命中 src/routing/resolve-route.ts 中的分层路由系统：
| 优先级 | 匹配类型 | 示例 |
|---|---|---|
| 1 | 直接对等绑定 | Thread/DM → 特定 agent |
| 2 | 父级对等继承 | 回复到父线程的 agent |
| 3 | Guild + 角色 | Discord guild + 成员角色 |
| 4 | 仅 Guild | Discord guild，任意角色 |
| 5 | 团队绑定 | Slack workspace |
| 6 | 账户模式 | 账户级路由 |
| 7 | Channel 默认 | 每个 channel 的通配符 |
| 8 | 全局默认 | 配置的兜底方案 |
每条路由产生两个 session key：
sessionKey— 完整上下文（peer、account、channel）mainSessionKey— 简化版 key，用于直接聊天合并
Session 追踪模型覆盖、推理深度、发送策略和完整对话历史。持久化使用基于文件的存储，配合原子写入。
这意味着什么
OpenClaw 的架构是一个 hub-and-spoke gateway 模式：
- Channel 通过 extension 接入（37 个适配器）。
- Gateway 进行认证、限流和路由。
- 路由引擎决定哪个 agent 处理消息。
- Agent 运行时（pi-agent-core）完成 LLM 工作。
- 响应通过 gateway 回流到原始 channel。
这更接近 AI agent 的 Nginx 而非独立的 AI 框架。Gateway 的工程质量很高 — 认证、会话管理、事件广播和背压处理都是生产级的模式。
但最关键的部分 — agent 循环本身 — 依赖于一个 pre-1.0 的外部依赖。
下一篇：第二篇 — Skills、Memory 与 Tools 涵盖 SKILL.md 系统、混合 memory 搜索、70 个 agent 工具以及 plugin hook 架构。
分析基于 OpenClaw v2026.2.18。源码：github.com/openclaw/openclaw。