OpenClaw 源码全链路拆解笔记

从一条 “你好” 消息出发，追踪 OpenClaw 处理消息的完整路径。

目录

架构总览

Reply

Agent Runtime

Pipeline

Gateway

WebSocket

HTTP

Channels Mgr

Telegram / Discord
WhatsApp / TUI / WebChat

dispatch

get-reply

get-reply-run

agent-runner

embedded-runner

Model Auth

Tools

attempt

prompt()

dispatcher

delivery

Channel Plugin

User

第 1 站：入口与网关启动

核心问题：OpenClaw 是如何启动的？

进程入口

Gateway Server 启动

配置系统

💡 你会学到

Gateway 不是一个简单的 HTTP server——它是整个系统的控制平面。所有消息渠道、工具、Agent 都挂载在 Gateway 上。

第 2 站：消息接入与标准化

核心问题：不同平台的消息如何统一处理？

Channel Plugin 架构

每个消息渠道（Telegram/Discord/WhatsApp/Slack）都是一个 Channel Plugin：

Plugin SDK — 消息标准化

Channel Plugin 使用统一的 SDK 将平台消息转化为内部格式：

标准化消息结构 — MsgContext

// 标准化后的消息包含这些关键字段：
type MsgContext = {
  Body: string;                  // 原始消息文本
  BodyForAgent: string;          // 带时间戳的消息（给 Agent 看）
  SessionKey: string;            // 会话标识
  Provider: string;              // 来源渠道（telegram/discord/...）
  ChatType: string;              // direct / group
  SenderId: string;              // 发送者 ID
  CommandAuthorized: boolean;    // 是否有命令执行权限
  // ... 更多字段
};

消息去重与防抖

WebChat / Gateway 内部渠道

对于 TUI / Control UI / ACP 等内部渠道，消息通过 Gateway RPC 进入：

💡 你会学到

Plugin 模式：每个渠道都是可插拔的。新增一个消息渠道只需要实现 Plugin 接口，不需要修改核心逻辑。

第 3 站：路由决策 — 谁来处理这条消息？

核心问题：消息到达后，如何决定由哪个 Agent 处理？

消息分发入口

Agent 路由解析

Session Key 体系

Session Key 格式：agent:{agentId}:{channel}:{chatType}:{chatId}

例如：agent:main:telegram:direct:8572674464

权限与访问控制

💡 你会学到

Strategy 模式：不同渠道、不同用户、不同群组可以绑定到不同的 Agent，实现精准的任务分流。路由规则是配置驱动的，不需要改代码。

第 4 站：会话初始化与上下文装配

核心问题：Agent 开始处理前，需要准备哪些上下文？

核心入口

这个函数做了大量幕后工作，但不会调用大模型：

Step 1：确定 Agent 和工作区

determine Agent

prepare workspace

resolveSessionAgentId()

ensureAgentWorkspace()

Agent ready

Step 2：媒体与链接理解

如果消息包含图片、文件或链接，先进行深度解析：

Step 3：会话状态初始化

  • src/auto-reply/reply/session.ts#L169 — initSessionState()
    • 加载历史对话记录
    • 恢复会话上下文
    • 这就是 AI "记住"你之前说过的话的原理 — 不是真正的记忆，而是每次推理前重新加载历史

Step 4：解析控制指令

Step 5：Typing 状态

💡 你会学到

到这一步为止，系统还没有调用任何大模型。所有的工作都是在准备上下文——这正是 OpenClaw 区别于简单 API wrapper 的关键。

第 5 站：执行配置与任务排队

核心问题：准备好的上下文如何打包成执行任务？

执行配置构建

这个函数将所有准备好的参数打包：

  1. Thinking Level 解析 — /think high 等用户指令会调整推理深度

  2. 队列策略

  3. 群聊上下文构建

  4. 入站元数据注入

  5. 路由回复

最终调用 → runReplyAgent()

💡 你会学到

Pipeline 模式：消息经过一系列 transform 阶段（标准化 → 路由 → 上下文装配 → 执行配置），每个阶段只关注自己的职责。

第 6 站：Agent Runner — 生命周期管理

核心问题：Agent 的执行生命周期是怎么管理的？

核心入口

这个函数管理 Agent 的完整生命周期：

Step 1：记忆刷新

Step 2：Block Streaming 管线

Step 3：执行并构建回复

调用 → runAgentTurnWithFallback()

Step 4：构建回复 Payload

Step 5：成本计算与诊断

Step 6：Followup 处理

💡 你会学到

Observer 模式：Agent 生命周期中的每个阶段都通过事件（emitAgentEvent、emitDiagnosticEvent）通知订阅者，实现松耦合的监控和扩展。

第 7 站：执行层 — Fallback 与容错

核心问题：模型调用失败怎么办？

核心入口

Step 1：注册运行上下文

const runId = crypto.randomUUID();     // 全局唯一运行标识
registerAgentRunContext(runId, ...);    // 注册上下文，用于追溯

Step 2：CLI vs 嵌入式模式选择

Yes

No

isCliProvider()?

runCliAgent()
Claude Code / Codex CLI / Gemini CLI

runEmbeddedPiAgent()
Default embedded mode

Step 3：Model Fallback 机制

  • src/agents/model-fallback.ts#L511 — runWithModelFallback()
    • 如果主模型调用失败（网络错误、限流、计费问题…）
    • 自动按配置的 fallback 链切换到备用模型
    • 支持重试策略和冷却期管理

Step 4：Failover 错误分类

  • src/agents/failover-error.ts — FailoverError / resolveFailoverStatus()
  • src/agents/pi-embedded-helpers.ts — 错误分类函数：
    • isCompactionFailureError() — 上下文压缩失败
    • isContextOverflowError() — 上下文窗口溢出
    • isBillingErrorMessage() — 计费错误
    • isTransientHttpError() — 临时网络错误（可重试）

💡 你会学到

容错设计：OpenClaw 在生产环境中需要处理各种不可预期的失败。Fallback 机制确保单个模型失败不会导致用户得不到回复。

第 8 站：嵌入式运行时 — 模型解析与认证

核心问题：系统如何确定用哪个模型、用哪个 API Key？

核心入口

Step 1：Lane 排队

Step 2：模型解析

Step 3：API 密钥认证

多密钥轮询机制：

Step 4：上下文窗口保护

  • src/agents/context-window-guard.ts — evaluateContextWindowGuard() / resolveContextWindowInfo()
    • 检查上下文是否即将溢出
    • 必要时触发自动压缩（compaction）

Step 5：Compaction（上下文压缩）

💡 你会学到

多层保护：模型解析 → API 认证 → 上下文窗口检查 → 自动压缩。每一层都有失败处理，确保推理请求在最佳状态下发出。

第 9 站：核心推理 — 真正调用大模型

核心问题：最终是怎么调用大模型的？

核心入口

Step 1：工作环境准备

// Line 1384
const resolvedWorkspace = resolveUserPath(params.workspaceDir);

// Line 1399
const sandbox = await resolveSandboxContext({ ... });

Step 2：工具创建

Agent Tools

OpenClaw Native

exec

process

apply_patch

browser

cron

message

web_search

web_fetch

memory_search

sessions_spawn

nodes

tts

Pi SDK

read

write

edit

grep

...

Step 3：Skill 加载

Step 4：系统提示词构建

⚠️ 双刃剑：系统提示词包含的信息越多，模型的环境理解越完整，但 token 消耗也越大。这是 OpenClaw token 消耗较快的核心原因之一。

Step 5：创建 Agent Session（Pi SDK）

// Line 1854
({ session } = await createAgentSession({
  model,
  tools,
  systemPrompt,
  // ...
}));
  • 使用 @mariozechner/pi-coding-agent 的 createAgentSession()
  • 绑定所有工具、上下文、规则到这个会话

Step 6：Stream Function 创建

不同模型 Provider 使用不同的流式调用函数：

Step 7：发起推理请求！🚀

// Line 2539-2541
await activeSession.prompt(effectivePrompt, { images: imageResult.images });
// 或
await activeSession.prompt(effectivePrompt);

这是整个链路中，真正调用大模型的唯一一行代码。

Step 8：Agent Loop（由 Pi SDK 管理）

prompt() 内部运行 Agent Loop：

  1. 模型生成文本 / 工具调用
  2. 如果触发工具调用 → 执行工具 → 结果写回历史 → 继续推理
  3. 循环直到模型认为任务完成

Step 9：事件订阅与流式输出

💡 你会学到

核心洞察：OpenClaw 本身不生产智能——它把推理任务完全交给 Pi SDK + 大模型。OpenClaw 的价值在于构建了一套完整的运行时装配体系，让每次推理都在最佳上下文中执行。

第 10 站：回复分发 — 消息送达用户

核心问题：模型的回复如何送回用户的聊天窗口？

回复分发管线

流式分发流程

Model streaming output

subscribeEmbeddedPiSession

block-reply-pipeline

reply-dispatcher

reply-delivery

Channel Plugin

User sees reply

回复格式适配

平台特定处理

不同平台有不同的消息能力和限制：

会话状态持久化

回复发送后，系统更新会话状态：

💡 你会学到

回复分发不是简单的"把文字发回去"。系统需要处理流式输出、格式适配、长消息分块、平台限制等大量边缘情况。

核心子系统

🧠 记忆系统

⏰ Cron 定时任务

🌐 浏览器控制

🔌 Plugin 系统

🔐 安全系统

🪝 Hook 系统

🤖 ACP（Agent Communication Protocol）

🗣️ TTS 语音合成

🔑 Secrets 管理

设计模式总结

模式 在哪里 关键文件
Plugin/Provider 渠道接入、模型 Provider、TTS Provider src/channels/plugins/ / src/providers/
Pipeline/Middleware 消息处理链 src/auto-reply/dispatch.ts → get-reply → agent-runner
Observer/Event 生命周期事件、Hook 系统 src/infra/agent-events.ts / src/hooks/
Strategy 模型选择、认证策略、Fallback src/agents/model-fallback.ts / src/agents/model-auth.ts
Factory Session/Agent/Tool 创建 src/agents/pi-tools.ts / src/auto-reply/reply/session.ts
Queue/Lane 任务排队与并发控制 src/process/command-queue.ts / src/agents/pi-embedded-runner/lanes.ts
Chain of Responsibility Fallback 降级链 src/agents/model-fallback.ts / src/agents/auth-profiles/order.ts

关键洞察

1. OpenClaw 是一个运行时装配引擎

它的核心价值不是 AI 推理本身，而是：

  • 将用户消息精准嵌入到全维度运行环境中
  • 管理认证、工具、上下文、会话状态的完整生命周期

2. 智能生成完全委托给 Pi SDK

OpenClaw 做了所有的"脏活累活"——鉴权、路由、工具管理、上下文装配、异常处理——然后把整理好的数据交给 @mariozechner/pi-coding-agent 的 createAgentSession().prompt() 完成推理。

3. 提示词工程做到了极致

所有运行时信息都会结构化地注入系统提示词——这既是优势（模型获得完整环境理解），也是代价（token 消耗高、注意力稀释）。

4. 本质是一个本地优先的网关系统

Runtime

Agent Runtime

Tool Set

Memory

Plugins

Control Plane

Gateway

Channels

Telegram

Discord

WhatsApp

Slack

...

5. 从代码量看优先级

模块 文件数 核心关注
agents/ 200+ 模型管理、工具、认证、嵌入式运行时
auto-reply/ 170+ 消息处理管线、命令系统、回复分发
gateway/ 180+ Gateway 服务器、RPC、认证、Control UI
channels/ 50+ 渠道 Plugin、平台适配
memory/ 60+ 向量搜索、嵌入、索引
security/ 20+ 安全审计、命令审批

推荐阅读顺序

  1. 先读 src/auto-reply/dispatch.ts — 消息分发入口，理解全局流程
  2. 然后 src/auto-reply/reply/get-reply.ts — 上下文装配
  3. 然后 src/auto-reply/reply/agent-runner.ts — Agent 生命周期
  4. 然后 src/agents/pi-embedded-runner/run.ts — 嵌入式运行时
  5. 最后 src/agents/pi-embedded-runner/run/attempt.ts — 核心推理（最复杂）
  6. 按兴趣 深入各子系统（memory/、cron/、browser/、acp/）

Generated from OpenClaw source at /Users/GitRepos/openclaw — 2026-03-17

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

Agent 沙箱逃逸面实战：从镜像供应链到 OpenClaw 权限边界设计

avatar 龙虾开发者社区
cover

密钥轮换审计：如何用 MaxClaw 网关实现多厂商模型路由的熔断与配额管理

avatar 龙虾开发者社区
cover

Agent 网关如何正确处理消息幂等：从 webhook 乱序到企业 VPN 分流实战

avatar 龙虾开发者社区