OpenClaw 中有两层 run-loop文件行数职责cli/gateway-cli/run-loop.ts1026外层循环gateway 进程的生命周期管理启动→监听→重启→停止agents/embedded-agent-runner/run-loop.ts669内层循环单个 Agent 执行的 LLM↔Tool 闭循环我们重点讲内层循环的run-loop.ts这是 OpenClaw 嵌入式 Agent运行循环Run Loop的核心实现。它负责驱动 Agent 的一次完整推理会话包括多次尝试、重试、模型切换、错误恢复和资源清理是整个 Agent 执行引擎的“心脏”。文件定位与职责文件路径src/agents/embedded/run-loop.ts核心导出runPreparedEmbeddedLoop(input: PreparedEmbeddedRunInput): PromiseEmbeddedAgentRunResult调用方由run-orchestrator.ts中的executePreparedEmbeddedRun调用。职责管理一次 Agent 运行的完整生命周期从开始到结束。处理模型调用、工具执行、上下文管理、重试逻辑、错误恢复。支持认证轮换、模型回退、超时控制、循环检测。负责清理资源如 MCP 运行时、上下文引擎。整体架构runPreparedEmbeddedLoop(input)│├── 初始化阶段 ──────────────────────────────│ ├── prepareEmbeddedRunRuntime() → 运行时准备模型/认证/harness│ ├── 创建各类状态管理器│ │ ├── contextRecoveryState ← 上下文恢复状态│ │ ├──usageAccumulator ← token 用量累加│ │ ├── terminalRetryState ← 终端重试│ │ ├── idleTimeoutBreakerState ← 空闲超时断路器│ │ ├── postCompactionGuard ← 压缩后循环检测│ │ ├── sessionPromptState ← 会话提示词状态│ │ └── failoverRetryController ← 故障转移重试控制器│ ├── ensureContextEnginesInitialized()│ └── resolveContextEngine() → 初始化上下文引擎管理 prompt 组装 contextEngine通过resolveContextEngine获取│└── 主循环 while(true) ─────────────────────││ ┌───────────────────────────────────│ │ 检查超出最大重试次数→ 返回失败 L277-311│ │ 检查overload 断路器触发→ 返回失败 L312-320│ ││ ├─ ① prepareAndDispatchEmbeddedRunAttempt() L321-344│ │ → 组装 prompt → 调 LLM → 解析 tool_calls → 执行工具 → 组装下一轮 prompt│ │ → 返回 dispatchedAttempt│ ││ ├─ ② normalizeEmbeddedRunAttempt()│ │ → 标准化尝试结果│ │ → 判断 action: complete | retry│ │ → 提取 aborted/timedOut/terminalOutcome 等状态│ ││ ├─ ③ recoverEmbeddedRunAttempt()│ │ → 如果需要恢复rotate profile、fallback model、重试│ │ → 判断 action: complete | retry│ ││ ├─ ④ handleEmbeddedAssistantFailure()│ │ → 处理 LLM 助手故障│ │ │ ├── 超时→ 重试/切换模型│ │ │ ├── rate limit→ 换 profile/退避重试│ │ │ ├── auth error→ 刷新 token/换 profile│ │ │ ├── overload→ 换 profile│ │ │ └── 其他→ 标记失败│ │ → 判断 action: retry | proceed│ ││ ├─ ⑤ prepareEmbeddedRunTerminal()│ │ → 组装最终输出visible text, raw text, tool summary, agentMeta│ ││ ├─ ⑥ resolveEmbeddedRunTerminalTimeout()│ │ → 超时场景的特殊处理│ ││ └─ ⑦ resolveEmbeddedRunTerminal()│ → 最终判断完成 OR 重试│ → complete → 返回 EmbeddedAgentRunResult│ → retry → continue 回到循环顶部│└── finally 清理├── 清理 prompt build cache├── 停 runtime auth refresh timer├── contextEngine.dispose()└── 清理 bundle MCP runtime1. 初始化阶段解析输入参数构建运行时环境prepareEmbeddedRunRuntime。初始化各种状态管理器usageAccumulator累计 token 用量contextRecoveryState上下文恢复状态idleTimeoutBreakerState空闲超时断路器postCompactionGuard压缩后循环检测sessionPromptState会话提示词状态failoverRetryController故障转移重试控制器初始化上下文引擎contextEngine通过resolveContextEngine获取。2. 核心执行流程while 循环L275-621l整个运行循环是一个while (true)结构通过多个状态变量控制循环终止或继续重试。它的职责重试控制失败了怎么办换模型换 profile退避状态管理token 用量累计、上下文恢复、session prompt 持久化故障处理rate limit、auth error、overload、timeout、idle timeout终端判断什么时候算完成什么时候继续while (未终止) {① 构建 promptsystem context tools history② 调用 LLM③ 解析响应text / tool_calls / thinking④ 如果有 tool_calls → 执行工具 → 把结果塞回上下文 → goto ②⑤ 如果没有 tool_calls → 这是最终回复 → 终止}处理compaction上下文超长时压缩、failover模型挂了换一个、重试2. 循环迭代每次尝试每次迭代执行一次 Agent 推理尝试步骤包括a. 准备与调度尝试调用prepareAndDispatchEmbeddedRunAttempt构造本次尝试所需的参数。规范化尝试normalizeEmbeddedRunAttempt处理可能的重试或完成条件。如果尝试成功完成直接返回结果。b. 尝试恢复与错误处理调用recoverEmbeddedRunAttempt处理超时、中断、认证失败等异常。如果恢复后决定重试则更新状态并继续循环。如果恢复后决定完成则返回结果。c. 处理 Assistant 失败调用handleEmbeddedAssistantFailure分析失败原因如空响应、推理循环、认证失败、超时等。根据失败类型决定是否重试、切换模型/认证配置或最终失败。d. 终端处理与结果返回如果无法恢复则调用prepareEmbeddedRunTerminal构建最终结果。通过resolveEmbeddedRunTerminalTimeout和resolveEmbeddedRunTerminal判断是否需要重试或返回最终结果。如果终端决定重试则继续循环否则返回最终结果。关键点1. Token 用量控制const usageAccumulator createUsageAccumulator();let lastRunPromptUsage: ReturnTypetypeof normalizeUsage | undefined;// 每次 LLM 调用后累加 token 使用量 可用于子 Agent 的 token 预算控制2. 上下文引擎Context Engineconst contextEngine await resolveContextEngine(params.config, {...});// 管理 prompt 组装system prompt 历史 tools attachment 压缩时由 compactionRuntime 调用3. Tool 结果观察const observeToolOutcome (observation: ToolOutcomeObservation): void {// 观察每个 tool 调用的结果追踪 tool call ordinal调用序号 检测 tool 循环post-compaction guard 如果检测到死循环 → abort};4. 多 Agent 的 session prompt 状态const sessionPromptState createEmbeddedRunSessionPromptState({runParams: params,sessionAgentId,resolvedSessionKey,lifecycleGeneration,});// 管理 session 的 prompt 持久化子 Agent 执行完成后prompt 状态更新到 session5. 故障转移const failoverRetryController createEmbeddedRunFailoverRetryController({...});// 当当前模型/profile不可用时// → rotate profile换 API key// → fallback model换备选模型// → rate limit backoff退避重试关键组件与状态管理组件作用preparedRuntime封装了模型、认证配置、插件信息等运行时上下文。contextEngine负责管理对话历史、压缩、上下文窗口等。sessionPromptState管理当前会话的提示词、持久化状态。usageAccumulator累计 token 消耗用于计费和限流。failoverRetryController控制模型故障转移、重试次数、认证轮换。postCompactionGuard检测压缩后是否陷入循环工具重复调用。idleTimeoutBreakerState检测长时间空闲防止成本失控。terminalRetryState管理终端重试如空响应、仅推理输出。contextRecoveryState记录上下文恢复尝试用于智能回退。重试与容错机制最大重试次数由MAX_RUN_LOOP_ITERATIONS控制基于可用认证配置数。认证轮换如果认证失败通过advanceAttemptAuthProfile切换到下一个 API Key。模型回退如果当前模型持续失败可触发 fallback 模型通过fallbackConfigured决定。超时处理timedOut整体超时idleTimedOut空闲超时timedOutDuringCompaction压缩阶段超时timedOutDuringToolExecution工具执行超时空响应/仅推理循环针对模型返回空文本或仅推理内容进行有限次重试。断路器idleTimeoutBreakerState防止长时间无响应导致成本失控。postCompactionGuard防止压缩后工具调用循环。上下文引擎与会话管理上下文引擎contextEngine负责维护对话历史、压缩、截断等。每次尝试前会通过buildEmbeddedContextEngineRuntimeSettings构建运行时设置如 token 预算、回退原因。会话状态sessionPromptState管理当前激活的提示词和持久化控制。清理与资源回收在finally块中执行调用maybeEmitFastModeAutoResetBestEffort快速模式自动重置。停止认证刷新计时器。执行runAgentCleanupStep清理上下文引擎资源。如果cleanupBundleMcpOnRunEnd为 true则退出会话的 MCP 运行时。结果输出最终返回EmbeddedAgentRunResult包含回复内容payloads元数据meta包括会话 ID、模型、耗时、用量、最终可见文本等。错误信息如果失败。设计亮点高度模块化每个功能模块认证、上下文、重试、超时都封装为独立单元。弹性设计支持多级重试、认证切换、模型回退确保高可用性。成本控制通过空闲超时断路器、循环检测、用量累计防止失控消耗。可观测性详细日志、阶段标记、进度通知便于调试和监控。资源管理显式清理上下文引擎和 MCP 运行时避免资源泄漏。与其他模块的关系被executePreparedEmbeddedRun调用位于run-execution.ts。依赖prepareEmbeddedRunRuntime位于run/runtime-preparation.ts准备运行时。依赖handleEmbeddedAssistantFailure位于run/assistant-failure.ts处理失败。依赖prepareAndDispatchEmbeddedRunAttempt位于run/attempt-dispatch-preparation.ts调度尝试。总结run-loop.ts是 OpenClaw 嵌入式 Agent 运行循环的核心实现它协调了尝试执行、错误恢复、重试策略、资源清理等复杂逻辑。通过分层、模块化的设计它实现了高可用、可扩展、可监控的 Agent 运行时环境。理解这份源码有助于掌握 OpenClaw 整个 Agent 执行引擎的运作机制和设计哲学。正在规划《OpenClaw源码解读》书籍欢迎出版社编辑交流