OpenClaw 消息全链路解析从用户输入到智能回复的完整旅程1. 引言一条消息的“奇幻漂流”2. 阶段一消息接收与预检——把好第一道关2.1 渠道适配把“方言”翻译成“普通话”2.2 预检过滤Preflight安全与路由决策引擎2.3 去重与防抖防止“重复触发”和“消息轰炸”3. 阶段二网关调度与排队——系统的“交通警察”3.1 会话解析Session Resolution3.2 排队与并发控制4. 阶段三上下文组装——把“背景知识”喂给 AI4.1 历史上下文注入4.2 引导文件Bootstrap Files加载4.3 Skills 动态注入4.4 安全防护输入净化5. 阶段四Agent 循环Agent Loop——真正“干活”的地方5.1 循环入口5.2 ReAct 循环的具体流程5.3 并发控制与会话锁5.4 超时机制5.5 钩子点你可以拦截的位置6. 阶段五回复投递与持久化——把结果送回来6.1 流式传输与分块6.2 静默回复Silent Reply6.3 持久化与会话转录7. 一张图看懂完整链路8. 结语一条消息背后的工程匠心The Begin点点关注收藏不迷路⬇ ⬇ 底部 ⬇ ⬇1. 引言一条消息的“奇幻漂流”当你向 OpenClaw 发送一条消息比如“帮我整理桌面文件”背后发生了什么它不像普通聊天应用那样直接把消息丢给模型就完事。OpenClaw 的这条消息会经历一条精心设计的流水线去重、防抖、排队、权限校验、上下文组装、ReAct 推理循环、工具执行、流式回复、持久化记忆……每一站都有明确的职责。一句话概括OpenClaw 通过一套由“渠道适配 → 网关调度 → 上下文组装 → Agent 循环 → 回复投递”组成的五阶段流水线把用户的自然语言指令转化为可执行的系统操作和最终回复。本文将从消息进入系统的那一刻开始一步步拆解它完整生命周期的每个环节。2. 阶段一消息接收与预检——把好第一道关2.1 渠道适配把“方言”翻译成“普通话”用户可能从 Telegram、WhatsApp、飞书、Discord、CLI 等不同入口发送消息。OpenClaw 的渠道适配器负责把各平台的私有协议统一转换成系统内部的标准消息结构。每个渠道插件Channel Adapter完成四件事协议解析把平台特有的消息格式解析为标准化结构附件处理识别图片、文档、音频等媒体类型认证与连接完成平台登录和会话建立安全过滤拦截敏感信息需配合第三方安全服务2.2 预检过滤Preflight安全与路由决策引擎消息进入系统后首先经过preflightXxxMessage函数Xxx 代表对应渠道。这不是一次简单的“有没有消息”判断而是一套完整的安全与路由决策引擎。以 Discord 渠道为例预检包括以下关键检查// 源码位置: message-handler-DbRk4Lwu.jsasyncfunctionpreflightDiscordMessage(params){// 1. 去重检查——防止 WebSocket 重连后重复投递if(dedupeKeyrecentInboundMessages.check(dedupeKey))returnnull;// 2. 机器人过滤——忽略其他 bot 的消息if(author.botallowBotsModeoff)returnnull;// 3. 消息类型过滤——忽略系统事件、斜杠命令等if(message.typeMessageType.ChatInputCommand)returnnull;// 4. DM/频道权限策略——检查是否有权在这个对话中响应// 5. 提及检测——机器人是否被 了// 6. 成员白名单——检查发送者是否在允许列表中// 7. 系统事件注入——如果是系统事件转交给系统处理器}2.3 去重与防抖防止“重复触发”和“消息轰炸”入站去重频道可能在重新连接后重新投递同一条消息。OpenClaw 维护一个短生命周期缓存以“频道/账户/对端/会话/消息 ID”为键避免重复投递触发另一次 Agent 运行。入站防抖来自同一发送者的快速连续消息可以通过messages.inbound配置合并为单个 Agent 轮次。防抖按“每个频道 对话”划定范围使用最新消息进行回复关联。注意控制命令如/new会绕过防抖媒体/附件会立即刷新不会等待防抖窗口。3. 阶段二网关调度与排队——系统的“交通警察”3.1 会话解析Session Resolution预检通过后消息被送到 Gateway 网关。Gateway 要做的一件核心事情是这条消息归哪个会话私聊消息全部归一化到主会话mainAI 拥有完整的多轮上下文群组/频道消息按频道隔离每个群组/频道拥有自己的会话键会话键的派生逻辑// 私聊 → main 会话// 群组 → discord:group:123456 或 telegram:channel:-1002381931352// WhatsApp 群组 → whatsapp:group:123456789g.us这种设计的精妙之处在于私聊中 AI 拥有跨轮次的完整记忆群组中按频道隔离互不干扰。3.2 排队与并发控制如果已有 Agent 运行处于活跃状态入站消息可以排队、引导Steer到当前运行中或收集为后续轮次。通过messages.queue配置支持以下模式模式行为steer默认引导到当前运行若回退则排队500ms 防抖followup排队作为后续投递collect收集多条消息后一并处理interrupt中断当前运行立即处理新消息关键设计决策OpenClaw 采用“串行优先”的队列模型——每个会话独立排队默认串行执行。这直接回应了 AI Agent 系统的经典问题并发越多状态越容易失控。多个执行过程同时读写同一会话很容易出现竞态和权限边界模糊。会话转录写入还受会话文件锁保护最多等待60,000ms之后报告会话忙。4. 阶段三上下文组装——把“背景知识”喂给 AIAgent 真正开始“想”之前必须先拿到足够的信息。这就是上下文组装阶段的任务。通过finalizeInboundContext函数构建最终传递给模型的上下文结构constctxPayloadfinalizeInboundContext({Body:combinedBody,// 格式化后的消息内容BodyForAgent:baseText,// 供 Agent 使用的原始文本InboundHistory:inboundHistory,// 频道历史已格式化RawBody:baseText,// 未处理的原始文本CommandBody:baseText,// 命令体用于 /command 解析SessionKey:boundSessionKey,// 会话标识From:effectiveFrom,// 消息来源SenderName:senderName,// ... 更多元数据});4.1 历史上下文注入对于群组/频道OpenClaw 会构建历史上下文标记[Chat messages since your last reply - for context] 历史消息列表 [Current message - respond to this] 当前消息历史缓冲区是仅待处理的——它们包含未触发运行的群组消息例如受提及门控的消息并排除已经在会话转录记录中的消息。每个频道的历史深度可通过historyLimit配置默认50条。4.2 引导文件Bootstrap Files加载OpenClaw 在启动时会加载工作区中的引导文件组成初始系统上下文// 典型文件加载顺序: SOUL.md → AGENTS.md → USER.md → HEARTBEAT.md// 以及 memory/ 目录下的当日文件和 MEMORY.mdasyncfunctionloadWorkspaceBootstrapFiles(sessionKey,workspaceDir){// 读取 workspaceDir 下的 .md 文件// 按文件名排序拼接// 作为 system prompt 前缀注入}这就是 AI 拥有“人格”和“长期记忆”的来源——SOUL.md定义身份MEMORY.md提供跨会话经验。4.3 Skills 动态注入Skills 是可扩展工具集通过SKILL.md文件描述。OpenClaw 在上下文组装阶段只注入技能的名称和描述摘要压缩路径以节省 Token详细的指令文本只有被选中时才加载// Skill 解析流程functionloadSkillsFromDir(skillDir){constfileslistMarkdownFilesRecursive(skillDir);for(constfilePathoffiles){constfrontmatterparseFrontmatterBlock(raw);// frontmatter.name → 技能名称// frontmatter.description → 技能描述供 Agent 判断何时调用constpromptTemplatestripFrontmatter(raw);// 完整指令}}4.4 安全防护输入净化这是 OpenClaw 安全意识最直接的体现。用户可能尝试在消息中注入[System Message]或System:前缀来冒充系统指令。sanitizeInboundSystemTags会将这些标记替换为不可执行的格式防止 Prompt Injection 攻击constBRACKETED_SYSTEM_TAG_RE/\[\s*(System\s*Message|System|Assistant|Internal)\s*\]/gi;constLINE_SYSTEM_PREFIX_RE/^(\s*)System:(?\s|$)/gim;functionsanitizeInboundSystemTags(input){returninput.replace(BRACKETED_SYSTEM_TAG_RE,(_match,tag)(${tag})).replace(LINE_SYSTEM_PREFIX_RE,$1System (untrusted):);}5. 阶段四Agent 循环Agent Loop——真正“干活”的地方上下文组装完成后OpenClaw 进入最核心的Agent Loop智能体循环。官方文档对这一循环的定义是智能体循环是智能体完整的“真实”运行接收 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化。它是把消息转化为操作和最终回复的权威路径同时保持会话状态一致。5.1 循环入口Agent 循环通过两种方式触发Gateway RPCagent和agent.waitCLI 命令openclaw agent --message ...agentRPC 会校验参数、解析会话、持久化会话元数据并立即返回{ runId, acceptedAt }。agentCommand随后执行真正的循环。5.2 ReAct 循环的具体流程是否接收用户消息上下文组装系统提示 记忆 技能列表 历史调用大模型推理需要调用工具执行工具文件读写/浏览器/命令/搜索工具结果返回作为 Observation 反馈给模型生成最终回复持久化: 更新会话 记忆通过 Gateway 投递回复根据京东云开发者社区的源码分析OpenClaw 在处理消息时经历了从“意图识别”到“技能匹配”再到“执行与反馈”的完整 ReAct 循环。5.3 并发控制与会话锁Agent 循环按会话键Session Key串行化运行并可选择经过全局通道。这防止了工具/会话竞争保持会话历史一致性。会话转录写入受文件锁保护。如果某个进程持有锁另一个进程尝试写入时会等待session.writeLock.acquireTimeoutMs默认 60,000ms之后报告会话忙。5.4 超时机制为防止 Agent“死循环”或卡住OpenClaw 设置了多层超时超时类型默认值说明Agent 运行时172,800 秒48 小时agents.defaults.timeoutSeconds模型空闲看门狗120 秒无响应块到达时中止模型请求等待 Agent 完成30 秒agent.wait默认等待时间5.5 钩子点你可以拦截的位置OpenClaw 提供了丰富的钩子Hooks方便开发者在关键节点插入自定义逻辑钩子触发时机before_model_resolve模型解析前可覆盖提供商/模型before_prompt_buildPrompt 构建前可注入额外上下文before_agent_replyLLM 调用前可接管并返回合成回复before_tool_call/after_tool_call工具调用前后可拦截参数/结果agent_end循环完成后检查最终消息和元数据message_received/message_sending/message_sent消息生命周期钩子6. 阶段五回复投递与持久化——把结果送回来6.1 流式传输与分块OpenClaw 支持分块流式传输在模型生成文本块时发送部分回复。关键设置包括blockStreamingDefault是否默认开启分块流式on/offblockStreamingBreak在text_end或message_end处分块blockStreamingChunk分块的大小约束minChars/maxCharshumanDelay分块回复之间类似真人的暂停6.2 静默回复Silent Reply精确的静默 tokenNO_REPLY/no_reply表示“不要投递用户可见的回复”。当某轮还有待处理的工具媒体时OpenClaw 会剥离静默文本但仍会投递媒体附件。不同对话类型对静默的处理不同直接对话默认不允许静默会将裸静默回复重写为简短的可见回退群组/频道默认允许静默6.3 持久化与会话转录循环完成后整个会话和工具结果被持久化。会话转录写入受文件锁保护确保并发安全。最终回复通过原始渠道返回给用户用户偏好和关键信息则进入记忆系统供后续会话使用——这正是 OpenClaw 能“越用越懂你”的原因。7. 一张图看懂完整链路记忆系统工具系统大模型Agent 执行引擎Gateway 网关渠道适配器用户记忆系统工具系统大模型Agent 执行引擎Gateway 网关渠道适配器用户阶段一预检阶段二调度阶段三上下文组装阶段四Agent 循环alt[需要调用工具][直接回复]loop[ReAct 循环]发送消息渠道适配协议→标准化去重检查 防抖标准化消息权限校验会话解析私聊→main / 群组→隔离入队串行队列 会话锁分发消息读取记忆 (MEMORY.md 当日日志)返回记忆片段加载引导文件 (SOUL.md/AGENTS.md/USER.md)加载 Skills 摘要名称描述输入净化防止 Prompt Injection发送上下文 用户消息推理结果执行工具文件/浏览器/命令返回工具结果生成最终回复持久化会话 记忆发送最终回复投递回复显示回复8. 结语一条消息背后的工程匠心一条看似简单的“帮我整理桌面文件”在 OpenClaw 中经历了渠道适配、预检过滤、去重防抖、会话解析、排队控制、上下文组装、安全净化、Agent 循环、工具执行、流式回复、持久化记忆等十多个环节。这套链路的精妙之处不在于某个单一环节而在于每个环节各司其职共同构成了一个可运行、可扩展、可治理的 AI Agent 系统。Gateway 负责“接客”Agent 负责“想和做”Skill 提供“专业能力”Memory 确保“越用越懂你”——它们协同工作让 AI 从“能说会道”进化到了“真刀真枪干活”。The End点点关注收藏不迷路⬆ ⬆ 顶部 ⬆ ⬆