OpenClaw Agent Runner 深度解析一次 Agent 运行的完整生命周期1. 引言Agent Runner 是什么2. Runner 与 Provider、Model、Channel 的区别3. 一次 Agent 运行的完整阶段3.1 阶段一参数校验与会话解析3.2 阶段二上下文组装3.2.1 工作区引导文件加载3.2.2 Skills 加载3.2.3 模型与认证解析3.3 阶段三执行循环Agent Loop3.3.1 排队与并发控制3.3.2 runEmbeddedAgent 的核心循环3.3.3 超时机制3.4 阶段四流式回复与事件投递3.4.1 事件流3.4.2 分块流式传输3.4.3 静默回复3.5 阶段五持久化与生命周期结束3.5.1 持久化3.5.2 agent.wait 等待完成4. 运行时选择策略Runtime Selection5. 运行时所有权谁拥有循环的哪部分6. 架构速览代码在哪里7. 结语The Begin点点关注收藏不迷路⬇ ⬇ 底部 ⬇ ⬇1. 引言Agent Runner 是什么在 OpenClaw 的架构中Agent Runner或称 Agent Runtime是真正“干活”的核心引擎。如果用一座工厂来比喻 OpenClawGateway是“前台接待”——接消息、做路由、控制权限Agent Runner是“生产车间”——把用户指令变成实际操作再把结果送回来一句话定义Agent Runner 是拥有一个已准备模型循环的组件——它接收提示词驱动模型输出处理原生工具调用并将完成的轮次返回给 OpenClaw。本文将完整拆解 Agent Runner 的工作过程从触发到结束逐一剖析每个阶段的职责、机制和设计考量。2. Runner 与 Provider、Model、Channel 的区别首先需要理清一个常见的混淆点。在 OpenClaw 中Runner执行环境、Provider提供商、Model模型和 Channel渠道是四个不同层级的概念层级示例含义Provideropenai,anthropic,openai-codexOpenClaw 如何认证、发现模型并命名模型引用Modelgpt-5.5,claude-opus-4-6为 Agent 轮次选择的具体模型Agent Runtimeopenclaw,codex,claude-cli执行已准备轮次的底层循环或后端ChannelTelegram, Discord, Slack, WhatsApp消息进入和离开 OpenClaw 的位置简单来说Provider 解决“找谁认证”Model 解决“用哪个大脑”Runtime 解决“怎么跑这个大脑”Channel 解决“从哪里接消息”。Runtime 又有两个家族嵌入式 Harness在 OpenClaw 已准备的 Agent 循环内运行包括内置的openclaw运行时和插件注册的codex等CLI 后端运行本地 CLI 进程保持模型引用为标准形式如anthropic/claude-opus-4-7配合agentRuntime.id: claude-cli3. 一次 Agent 运行的完整阶段一次 Agent 运行经历五个核心阶段。以下将逐一展开。触发入口Gateway RPC / CLI阶段一参数校验与会话解析阶段二上下文组装阶段三执行循环模型推理 ↔ 工具执行阶段四流式回复与事件投递阶段五持久化与生命周期结束3.1 阶段一参数校验与会话解析Agent 运行的触发方式有两种Gateway RPCagent和agent.waitCLI 命令openclaw agent --message ...当用户消息抵达后agentRPC 执行以下步骤参数校验检查消息格式、权限、Token 限额等会话解析根据sessionKey或sessionId定位到具体会话私聊消息 → 映射到主会话main群组/频道消息 → 按频道隔离每个群组拥有独立会话键会话元数据持久化记录会话状态立即返回返回{ runId, acceptedAt }不等待运行完成。这个设计让 Gateway 可以快速响应而 Agent 在后台继续处理。关键设计agentRPC 是异步的——它只负责“接下这个任务”真正的执行由agentCommand和runEmbeddedAgent完成。3.2 阶段二上下文组装agentCommand开始真正执行前需要完成上下文组装。这是 Agent 能够“有记忆、有身份、有工具”的基础。3.2.1 工作区引导文件加载OpenClaw 在agents.defaults.workspace目录下加载一系列引导文件注入到系统提示词中文件内容AGENTS.md操作指示 “记忆”SOUL.md人格、边界、语气TOOLS.md用户维护的工具备注BOOTSTRAP.md一次性首次执行仪式完成后删除IDENTITY.mdAgent 名称/氛围USER.md用户数据 偏好的称呼方式这些文件在新会话的第一轮中会被注入到系统提示词的“项目上下文”中。空白文件会被略过大文件会被修剪截断以保证提示词精炼。3.2.2 Skills 加载Agent 会加载 Skills 快照。Skills 通过SKILL.md文件描述采用渐进式披露机制启动时只加载技能的名称和描述摘要详细的指令文本只有被选中时才加载。这种设计有效控制了上下文窗口的占用。3.2.3 模型与认证解析系统解析模型引用如openai/gpt-5.5认证配置文件如 OAuth 或 API Key运行时策略决定使用哪个 Runtime运行时选择有明确的优先级模型级运行时策略最高优先级Provider 级运行时策略auto 模式注册的插件 Runtime 可以声明支持的 Provider/Model 组合兜底如果没有运行时声明该轮次使用openclaw作为兼容性运行时OpenAI Agent 模型是一个特例未设置运行时和auto模式都会解析到Codex harness。3.3 阶段三执行循环Agent Loop这是 Agent Runner 最核心的部分——ReAct 循环。3.3.1 排队与并发控制运行按会话键串行化并可选择经过全局通道。这个设计防止了工具/会话竞争保持会话历史一致性。会话转录写入受文件锁保护。锁是进程感知且基于文件的能捕获绕过进程内队列或来自其他进程的写入者。会话转录写入者最多等待session.writeLock.acquireTimeoutMs默认 60,000ms之后报告会话忙。核心设计原则OpenClaw 采用“串行优先”的队列模型——每个会话独立排队默认串行执行优先保证状态稳定。并发越多状态越容易失控。3.3.2runEmbeddedAgent的核心循环runEmbeddedAgent是执行循环的实际承载者建立 Pi 会话构建 pi-agent-core 运行时所需的对象订阅 Pi 事件将 pi-agent-core 的事件桥接到 OpenClaw Agent 流工具事件 →stream: toolAssistant 增量 →stream: assistant生命周期事件 →stream: lifecyclephase:start/end/error强制执行超时通过中止计时器控制运行时长对于 Codex app-server 轮次如果已接受的轮次在终端事件前停止产生进度则中止该轮次是否接收用户消息上下文组装模型推理需要调用工具执行工具文件/浏览器/命令工具结果返回作为 Observation生成最终回复3.3.3 超时机制OpenClaw 设置了多层超时防止 Agent“死循环”或卡住超时类型默认值说明Agent 运行时172,800 秒48 小时agents.defaults.timeoutSeconds模型空闲看门狗120 秒无响应块到达时中止模型请求等待 Agent 完成30 秒agent.wait默认等待时间会话写入锁等待60,000 秒session.writeLock.acquireTimeoutMs3.4 阶段四流式回复与事件投递OpenClaw 支持在模型生成过程中流式输出而不是等全部生成完再一次性返回。3.4.1 事件流Agent 运行过程中发出的流事件包括lifecyclestart→end/errorassistant来自模型的流式增量文本tool工具调用的 start/update/end 事件compaction压缩周期事件3.4.2 分块流式传输通过配置blockStreamingDefault可以开启分块流式传输在模型生成文本块时发送部分回复而不是等待完整回复。关键设置包括blockStreamingBreak在text_end或message_end处分块和humanDelay分块回复之间的类人暂停。3.4.3 静默回复精确的静默 TokenNO_REPLY/no_reply表示“不要投递用户可见的回复”。系统会将其从出站负载中剥离但工具媒体附件仍会投递。3.5 阶段五持久化与生命周期结束3.5.1 持久化循环完成后整个会话和工具结果被持久化。会话转录以 JSONL 格式存储在~/.openclaw/agents/agentId/sessions/SessionId.jsonl会话 ID 是稳定的由 OpenClaw 选定。3.5.2agent.wait等待完成agent.wait使用waitForAgentRun等待特定runId的生命周期 end/error返回{ status: ok|error|timeout, startedAt, endedAt, error? }。4. 运行时选择策略Runtime SelectionOpenClaw 在 Provider 和模型解析之后选择嵌入式运行时。选择优先级如下模型级运行时策略最高优先级位于已配置的 Provider 模型条目中或agents.defaults.models[provider/model].agentRuntimeProvider 级运行时策略位于models.providers.provider.agentRuntimeauto 模式已注册的插件 Runtime 可以声明支持的 Provider/Model 组合兜底如果没有运行时声明使用openclaw作为兼容性运行时特别注意整会话和整 Agent 运行时固定项如OPENCLAW_AGENT_RUNTIME会被忽略。运行openclaw doctor --fix可以移除过期的配置并转换旧版模型引用。5. 运行时所有权谁拥有循环的哪部分不同运行时拥有循环中不同范围的内容。以 OpenClaw 内置 Runtime 和 Codex app-server 为例表面OpenClaw 嵌入式Codex app-server模型循环所有者OpenClawCodex app-server规范线程状态OpenClaw 转录Codex 线程 OpenClaw 转录镜像OpenClaw 动态工具原生 OpenClaw 工具循环通过 Codex 适配器桥接原生 Shell 和文件工具OpenClaw 路径Codex 原生工具通过钩子桥接上下文引擎原生 OpenClaw 上下文组装OpenClaw 将上下文投影到 Codex 轮次压缩OpenClaw 或选定上下文引擎Codex 原生压缩 OpenClaw 通知渠道投递OpenClawOpenClaw这个所有权拆分是主要设计规则如果 OpenClaw 拥有该表面 → 提供正常的插件钩子行为如果原生运行时拥有该表面 → OpenClaw 需要运行时事件或原生钩子如果原生运行时拥有规范线程状态 → OpenClaw 应镜像和投影上下文不重写不受支持的内部实现6. 架构速览代码在哪里OpenClaw 的 Agent Runtime 代码分布如下路径职责src/agents/embedded-agent-runner/内置 Agent 循环、Provider 流适配器、压缩、模型选择、会话接线src/agents/sessions/会话持久化、扩展加载、资源发现、Skills、提示词、主题packages/agent-core/可复用 Agent 核心、Harness 类型、消息、压缩助手、提示词模板src/agents/runtime/OpenClaw 对openclaw/agent-core的门面 本地代理工具src/agents/agent-tools*.tsOpenClaw 拥有的工具定义、Schema、策略、钩子适配器src/agents/agent-hooks/内置运行时钩子如压缩保护和上下文修剪src/llm/模型/Provider 注册、传输助手、Provider 特定流实现7. 结语Agent Runner 是 OpenClaw 从“能说会道”到“真刀真枪干活”的关键转化器。一次 Agent 运行的生命周期可以概括为参数校验与会话解析→ 接单上下文组装→ 准备工作执行循环模型推理 ↔ 工具执行→ 核心干活流式回复与事件投递→ 边干边汇报持久化与生命周期结束→ 收工存档理解 Agent Runner 的工作方式是深入掌握 OpenClaw 工程原理的必修课。它融合了队列管理、会话锁、运行时选择、超时控制、事件流分发等多个系统工程的关键设计值得仔细品味。The End点点关注收藏不迷路⬆ ⬆ 顶部 ⬆ ⬆