夜雨聆风
OpenClaw源代码解析 | 本地网关时代 | TypeScript | Pi SDK | Agent Loop执行循环 | 消息路由 | 提示词构建 | 自动化任务分发 | 会话持久
但是，你是否想过——当我们给OpenClaw发了一句最简单的“你好”，从按下发送键的那一刻起，到我们在屏幕上看到它的回复，这背后究竟发生了什么？
今天我们就来梳理一下OpenClaw的源代码，看看它到底是如何工作的。
这不是一次肤浅的功能介绍，而是一场深入核心代码的“解剖之旅”。
一切的起点：网关启动
很多人以为OpenClaw的核心就是那个聊天框，但本质上，它首先是一个本地优先的网关平台。
整个流程的起点，和大模型没有任何关系，而是从网关的启动开始的。只有先把网关跑起来，建立起统一的会话管理、渠道管理、工具管理和事件分发能力，来自不同渠道（比如WhatsApp、Telegram等）的消息才能被汇总到这里，进入后续的处理流程。
在源码文件 auto-reply/monitor.ts 里，核心执行的是 monitorWebChannel 这个函数。整个启动过程大致如下：
- 检查网络连接
确保“管道”通畅。 - 加载配置文件
openclaw.json
这里面包含了智能体、渠道、环境变量、鉴权信息、模型配置等所有核心字段，好比是整个系统的“大脑说明书”。 - 解析当前要使用的账号
比如你的WhatsApp账号。 - 进入一个持续的循环
-
创建消息处理器 -
启动渠道监听器 -
设置心跳机制和看门狗定时器（用于监控连接状态） -
处理连接的断开和重连 -
持续更新系统运行状态
只有当这整套流程全部完成，网关成功启动，OpenClaw才算正式进入“备战”状态，随时准备接收用户发来的消息。
可以说，没有这一层网关的支撑，后面所有的智能能力都无从谈起。
消息如何被系统“看见”——接入与标准化
当网关成功启动，一条来自WhatsApp或者其他平台的消息进入OpenClaw时，它的第一站并不是直接被转发给大模型，而是先进入了一套专门的消息监听与接入层（源码在 inbound/monitor.ts）。
具体来看，系统会先和即时通讯平台建立实时连接，通过事件监听器持续监听新消息。一旦有新消息到达，就会立刻启动一整套流程：
1. 消息去重和高频合并真实环境中，平台经常会重复推送消息，用户也可能短时间内连续发送多条。如果系统直接处理原始消息，很容易导致机器人重复回复。这一步就是为了过滤掉这些噪声，保证后续流程拿到的是干净、完整的用户需求。
2. 权限和合法性检查系统会判断这条消息是否来自允许的用户或群组，是否满足预设的触发规则。如果不符合，消息会被直接过滤掉，根本不会进入后面的智能体处理流程。
3. 媒体文件下载如果消息里包含了图片、文件等附件，系统会自动下载并保存到本地工作目录，这样后续智能体就能直接访问这些文件，完成图片分析、文档读取等操作。
4. 标记已读避免客户端重复推送同一条消息。
5. 消息标准化OpenClaw会把来自不同平台、格式千差万别的原始消息，统一封装成一个标准化的 WebInboundMessage 对象——这就好比把各种语言的信件都翻译成同一种“内部通用语言”。
6. 进入防抖队列防止用户短时间内连续发送大量消息导致系统重复处理。之后触发回调，把整理好的消息交给网关，进入下一个环节。
这一步的本质，就是把来自外部世界的、混乱的、非标准化的用户消息，转化成了系统内部可以识别、调度和处理的标准化事件。
消息该交给谁？——智能体路由决策
当消息完成标准化后，就进入了路由模块（源码 auto-reply/monitor/on-message.ts）。
很多人误以为所有用户消息都会被送到同一个AI模型里，然后由这个模型自己决定怎么处理。但OpenClaw的设计是：不同类型的任务，会被分配给不同的智能体来处理。
具体流程如下：
-
系统首先创建一个消息处理入口，接收标准化消息对象，并重新读取最新配置（因为OpenClaw支持动态调整配置，比如智能体绑定关系、权限规则等，每次处理都会重新读取，确保规则最新）。 -
接着，解析消息的发送方向：是私聊还是群聊？同时确定发送者的唯一ID。
- 群聊场景
机器人需要判断自己有没有被@，是否满足触发规则。 - 私聊场景
通常默认直接处理。
-
然后，读取配置文件里的 bindings绑定规则，通过resolveAgentRoute函数判断应该由哪个智能体处理当前消息——实现精准的任务分流。 -
路由确定后，系统会生成一个唯一的历史记录键值，把当前聊天和对应的历史对话记录关联起来。这就是AI能记得“你之前说过什么”的原理：每次推理前，系统都会把对应的历史加载到上下文里。 -
之后，系统会做一系列安全检查，比如防止机器人自己发送的消息又触发自己（避免循环回复）。 -
最后，区分群聊/私聊，进行相应的权限校验、上下文构建，最终进入核心处理函数 processMessage，交给下一个环节。
为AI推理做足准备——环境装配
很多人以为到了这一步，系统已经开始调用大模型了。但事实是，它只是完成了所有的幕后准备工作，为接下来的推理搭建好一个完整、干净、信息完备的运行环境。这一步的核心逻辑在 get-reply.ts 里。
具体来看，包括：
resolveSessionAgentId 再次确认当前会话对应的智能体，并敲定要使用的AI模型。ensureAgentWorkspace 为当前智能体创建一个专属工作区，用来存放运行时的文件（如下载的附件、临时结果、工具命令执行产生的文件等）。applyMediaUnderstanding 和 applyLinkUnderstanding 进行深度解析，把图片里的信息、链接里的网页内容转化成文本，让智能体在正式推理前就对所有内容有完整理解。initSessionState 会把对应的历史对话记录完整加载进来，为推理准备好上下文。resolveReplyDirectives 会识别用户消息里包含的特殊控制指令，比如 reset（重置会话）、model（指定模型）、verbose（开启详细输出）等，这些指令会调整当前会话的运行方式，有些甚至会直接跳过AI推理，执行内置的系统管理指令。handleInlineActions 处理那些不需要AI推理就能直接完成的操作，比如简单的状态查询。当所有这些准备工作全部完成后，系统才会进入 runPreparedReply 函数，把所有准备好的参数（会话上下文、模型选择、工具环境、用户消息、运行配置等）打包整理好，交给后面的流程。
直到这里，系统依然没有发起任何一次大模型调用——所有工作都是在为接下来的AI推理做最充分的准备。
调度与容错——确保稳定运行
接下来进入 get-reply-run.ts，关键函数是 runPreparedReply。
它的作用是把用户消息和所有配置参数，转换成完整的、大模型可以直接执行的运行配置。
-
系统首先判断这条消息是否真的需要进入AI推理流程（比如内置命令可能在这里直接结束）。 -
然后，把所有信息整理成大模型能理解的提示词结构，并根据用户指令调整模型运行参数（如推理强度、是否开启新会话等）。 -
同时校验当前推理的“思考等级”和运行策略，不同任务需要不同的推理深度。 -
处理消息队列，确保顺序正确，避免上下文混乱。
完成这些后，runPreparedReply 会把所有信息打包，传递给 agent-runner.ts——这是管理智能体运行生命周期的核心调度中枢。
在 agent-runner.ts 中：
-
系统调用 runReplyAgent把消息放进处理队列，并标记为“正在处理”，避免重复。 -
执行 runMemoryFlushIfNeeded：在必要时自动保存会话记忆状态。这是为了防止对话过长撑爆大模型的上下文窗口——当会话信息接近上限时，系统会对历史内容进行压缩，然后持久化到记忆文件中。这就是OpenClaw长会话记忆机制的核心实现。 -
然后进入 runAgentTurnWithFallback，这一层不仅负责调用模型，还内置了完整的失败重试和降级机制。如果模型调用失败（网络问题、服务异常、接口限流等），系统会按预设策略尝试重新执行，或切换备用模型后端——这在生产环境至关重要。 -
模型生成回复后，系统通过 buildReplyPayloads整理成适合当前渠道发送的格式，并记录本次运行的资源使用情况（token消耗、模型类型、成本估算等）。 -
同时触发诊断事件，上报运行信息到监控系统，方便运维人员掌握健康状况。 -
最后关闭“正在输入”提示，检查队列里是否还有后续消息需要处理，如果有，继续调用 runFollowupTurn处理下一条，形成稳定的循环运行机制。
需要再次说明，到了这一步，系统依然没有真正开始调用大模型进行推理，而是在做最终的执行准备和容错机制的布置。
真正的AI推理时刻——智能体执行
终于，我们来到了最核心的部分。这一步的源码主要在 auto-reply/reply/agent-runner-execution.ts 和 agents/pi-embedded-runner/run.ts 中。
agent-runner-execution.ts：最终确认与路径选择
进入 runAgentTurnWithFallback 后：
-
系统先生成一个全局唯一标识（UUID），并注册本次AI调用的完整上下文，方便后续追溯问题。 -
然后进入一个循环执行框架：如果模型调用失败，会根据策略决定重试、降级或切换后端。 -
执行 normalizeStreamingText，清理无意义的心跳标识、空文本等，确保环境干净。 -
接着进入 runWithModelFallback，判断本次任务是否要走CLI命令行模式（比如调用外部的Claude Code、Gemini CLI等）。如果是，就走runCliAgent；否则走默认的嵌入式智能体模式runEmbeddedPiAgent。 -
在这个过程中，系统持续检查异常信号（如会话损坏、上下文溢出），提前处理或终止任务。 -
最后封装出一个标准化的结果对象，传递给下一环节。
run.ts：嵌入式智能体的正式启动
runEmbeddedPiAgent 执行的第一件事是确认排队规则（会话级顺序执行还是全局级统一调度）。接着：
-
根据消息来源渠道，确定最终输出内容的格式（不同平台支持的消息能力不同）。 -
通过 resolveModel补齐模型的完整细节：名称、上下文窗口大小、API地址、调用方式、默认参数等。 -
处理身份认证：系统会遍历一组API密钥候选项，优先尝试第一个，如果失败则自动切换下一个，直到成功或全部失败。这种多密钥轮询机制能有效避免单密钥限流或失效导致的服务不可用。 -
认证通过后，进入内部循环，通过 runEmbeddedAttempt进行单次AI调用尝试——这一步才真正向大模型发起请求。
attempt.ts：向大模型发起请求
在 runEmbeddedAttempt 中：
-
系统先准备完整的运行环境：确定工作目录、沙箱边界，确保所有操作都在受控范围内，这是安全核心。 -
加载当前智能体可用的所有技能和工具（如读文件、写文件、执行命令等）。这些工具一部分是OpenClaw自己实现的，另一部分来自Pi的 pi-coding-agent包。 -
接下来是构建系统提示词。系统会把大量运行时信息——所有技能文档、项目说明文档、灵魂设定文档，甚至每日生成的记忆文件——全部拼接成一个非常长的结构化提示词。这是一把双刃剑：虽然模型获得了更完整的环境信息，但也会消耗巨量token，甚至稀释注意力，导致幻觉或上下文溢出。这也是很多用户反馈OpenClaw token消耗过快、偶尔出现幻觉的核心原因之一。 -
提示词构建完成后，系统导入Pi SDK的 createAgentSession创建一个智能体会话，把所有工具、上下文、规则绑定进去，并把系统提示词固定到会话里。 -
终于，系统通过 activeSession.prompt(effectivePrompt)真正向大模型发送请求！此时Pi SDK开始管理整个智能体的执行循环（Agent Loop）：模型生成文本、触发工具调用、接收工具结果、写回会话历史、继续下一轮推理，直到任务完成。 -
因为是流式生成，模型会逐段输出内容。系统通过订阅会话事件，在流式输出过程中触发回调，把刚生成的一段内容立刻推送给前端——我们看到的“打字机效果”就是这么来的。
回复如何回到你手中——分发与呈现
模型输出的内容是流式的，会逐段返回文本片段或工具调用结果。系统需要把这些碎片化的内容整理成完整的、符合平台要求的回复，才能发送给用户。这一步的源码在 auto-reply/monitor/process-message.ts 中。
核心逻辑是 dispatchReplyWithBufferedBlockDispatcher，它接收AI生成的所有结果（文本、工具调用信息、内容块ID等），转换成最终可以发送的回复结构。然后，系统调用 deliverWebReply，根据当前使用的渠道（WhatsApp、Telegram等），调用对应平台的接口，把整理好的回复推送给用户。
在流式回复场景下，这个过程可能是分批完成的：系统每接收到模型生成的一段完整内容，就立刻通过消息通道发送出去。所以我们在聊天窗口里看到的回复，往往是一段一段逐渐出现的，而不是一次性显示完整的答案。
当所有内容发送完成，这一轮消息处理流程正式结束。整个系统回到最初的监听状态，等待下一条用户消息的到来。
总结：OpenClaw的本质与价值
至此，一条用户消息从进入OpenClaw网关，到最终看到回复的完整闭环，我们已经全部拆解完毕。最后做个总结：
- OpenClaw最核心的价值，在于构建了一套完整的运行时装配体系
它能把用户的一条消息，精准嵌入到一个全维度的运行环境里——包括鉴权、文件读写、工具管理、上下文装配、会话调度、渠道适配、异常处理等等。 - OpenClaw本身并不生产智能
它把核心的智能生成任务完整交给了外部的Pi SDK，自己则默默完成了所有“脏活累活”，最后把整理好的数据喂给大模型的SDK。 - OpenClaw把提示词工程做到了极致
它把所有的运行时信息，都显式地、结构化地翻译进了系统提示词里，让模型获得最丰富的上下文。 - OpenClaw本质上是一套本地优先的消息系统
从架构上看，前端对接大量消息渠道，中间是统一的控制平面，底层挂载了智能体运行时、工具集、命令行交互界面、记忆系统等。正如它的Readme文件所说：网关才是整个系统的控制平面。本质上，它还是一个网关系统。
希望通过今天对OpenClaw源码的解读，能帮助你更好地理解它的应用场景和运行原理。下次再给“龙虾”发消息时，你或许会想起，背后有这么多精妙的代码在默默为你服务。
你对OpenClaw的哪一部分最感兴趣？欢迎留言讨论！
往期精选：
OpenClaw高危漏洞详解｜我在云端养龙虾的日子｜漏洞解决方案｜漏洞影响版本与危险等级
5分钟读懂AI史上最重要的一篇论文《Attention Is All You Need》| 深度剖析 | AI从业者必看
在线策略蒸馏：让小模型学会像大模型一样思考 | 大模型训练的三个阶段 | 反向 KL 散度 | OPDvs强化学习vs离线蒸馏
纳瓦尔的“一万次迭代”成事哲学 | 从线性成长到复利成长 | 人生是一场持续自我升级的游戏
企业级AI Agent设计指南 | 12项核心原则详解 | 打造高可靠、高价值企业级AI Agent | AI产品设计必看
DeepSeek到底厉害在哪儿？争议背后的“知识蒸馏”详解 | MoE、多头潜在注意、多Token预测、混合精度…
AI浪潮下，PM如何转型？详解“AI PM领域”三条高价值赛道与选择策略 | 平台、Native与AI+ | 一线进阶与闭坑指南
上下文工程Context Engineering | Agent性能提升 | WSCI四维治理体系｜写入 选取 压缩 隔离