OpenClaw Agent 02：Agent Loop——EventStream 驱动的生命周期与核心循环

在探讨智能体系统的底层实现时，绝大多数工程问题都可以追溯到其核心调度循环的设计。在 Pi 的代码库中，这个核心引擎位于 packages/agent/src/agent-loop.ts。

无论外层是终端 CLI、VS Code 插件还是企业级多渠道 Gateway，驱动整个智能体运转的生命线，就是一个基于 EventStream（事件流）的异步双层状态循环。读懂了这个循环的设计，你就能清晰理解生产级 Coding Agent 是如何做到高吞吐、零挂起和断点续传的。

双入口设计：全新会话与断点恢复

在工业级场景中，程序随时可能因为网络波动、用户手动中断或宿主崩溃而退出。因此，生产级 Agent 绝对不能把状态死死保存在不可重放的内存变量中。

Pi 在设计之初就暴露了两个同构的入口函数：

1
2
3
4
5
6
7
// packages/agent/src/agent-loop.ts

// 1. 发起全新的智能体会话
export function agentLoop(config: AgentConfig): EventStream { ... }

// 2. 从历史事件转录清单（Transcript）中精准恢复上下文
export function agentLoopContinue(config: AgentConfig, transcript: Event[]): EventStream { ... }

两者对外暴露的返回值类型完全一致：EventStream。agentLoopContinue 允许智能体在服务重启或网络恢复后，从磁盘上的 JSONL 审计日志中瞬间重建内存上下文，继续执行上一轮未竟的任务。

为什么选择 EventStream（AsyncGenerator）架构？

传统三方框架的 API 往往是一个黑盒函数：const result = await agent.run(prompt)。这种同步等待模式在 Coding Agent 场景是灾难性的——模型读取 5 个大文件、执行几轮 Shell 命令可能长达两三分钟，调用方在这期间对内部进度一无所知。

Pi 将整套生命周期抽象为由 AsyncGenerator 驱动的强类型结构化事件流：

1
2
3
4
5
6
7
8
9
10
11
type AgentEvent =
  | { type: 'agent_start' }
  | { type: 'turn_start' }
  | { type: 'message_start'; role: 'assistant' }
  | { type: 'message_update'; delta: string }           // 大模型流式输出片段
  | { type: 'message_end'; content: Message }
  | { type: 'tool_execution_start'; toolCall: ToolCall } // 工具开始执行通知
  | { type: 'tool_execution_update'; delta: string }    // 工具实时输出日志 (如 build 输出)
  | { type: 'tool_execution_end'; result: ToolResult }   // 工具完成返回
  | { type: 'turn_end' }
  | { type: 'agent_end' };

采用 AsyncGenerator 的核心工程优势在于原生背压（Backpressure）机制：如果客户端的终端渲染或网络发送变慢了，通过 for await (const ev of stream) 会自然阻塞等待，避免无限制的事件堆积在 Node.js 内存堆中导致 OOM。

双层循环控制拓扑与数据流转

Pi 的核心循环由一个处理长对话的**外层循环（Outer Loop）与一个处理多步工具推演的内层循环（Inner Loop）**紧密交织而成：

工具派发：为什么默认必须是并行（Promise.all）？

在代码审查或跨文件排查时，模型经常在一轮思考中一次性申请调用多个工具（例如并发读取 auth.ts、db.ts 和执行 git status）。

Pi 在工具调度中将并行执行作为默认路径：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// 简化自 agent-loop.ts 内部实现
async function executeToolCalls(toolCalls: ToolCall[], config: AgentConfig): Promise<ToolResult[]> {
  // 如果配置了严格顺序约束（有数据依赖）
  if (config.sequentialTools) {
    const results: ToolResult[] = [];
    for (const call of toolCalls) {
      results.push(await executeSingleTool(call, config));
    }
    return results;
  }

  // 默认并发派发：IO 密集操作延迟急剧降低
  return Promise.all(
    toolCalls.map(async (call) => {
      return executeSingleTool(call, config);
    })
  );
}

在 3 个独立文件读取耗时各为 2 秒的场景下：

  • 传统串行框架：总等待时间为 $2 + 2 + 2 = 6$ 秒；
  • Pi 并行架构：总等待时间为 $\max(2, 2, 2) \approx 2$ 秒，端到端延迟降低了 66%。

Hooks 拦截系统：解耦安全与上下文变换

为了在不侵入破坏核心循环逻辑的前提下实现合规校验，Pi 暴露了一组关键的拦截点（Hook）：

1
2
3
4
5
6
7
8
9
10
11
12
13
interface AgentHooks {
  // 1. 在工具调用执行前拦截：可用于命令正则黑名单拦截、用户授权审批
  beforeToolCall?: (toolCall: ToolCall) => ToolCall | null;

  // 2. 工具执行完毕后后处理：可对超大日志进行智能截断，只保留头尾
  afterToolCall?: (result: ToolResult) => ToolResult;

  // 3. 上下文发往模型前变换：动态注入临时 System 指令或执行局部修剪
  transformContext?: (messages: Message[]) => Message[];

  // 4. Provider 协议转换适配器
  convertToLlm?: (message: Message) => LlmMessage;
}

OpenClaw 网关的五阶段流水线与并发安全防护

OpenClaw 在内化该循环的同时，将其置于一个更加严密的企业级网关管道中：

1. 基于文件锁的 per-session 串行化隔离

在 Web 或即时聊天软件中，用户可能会在数秒内连续发送两条消息。如果允许多个 Agent Loop 同时并发读写同一个会话，会导致严重的上下文竞态、消息顺序错乱以及工具文件写入冲突。

OpenClaw 采用严密的会话级写锁保护：

1
2
3
4
5
6
7
8
9
// 基于文件锁的排它会话锁
const lockPath = `/tmp/openclaw-session-${sessionId}.lock`;
const sessionLock = await acquireFileLock(lockPath);
try {
  // 同一会话内部的消息严格排队串行推进
  await runEmbeddedAgentLoop(session, incomingMessage);
} finally {
  await sessionLock.release();
}

2. 生产级多层超时熔断配置

1
2
3
4
5
timeouts:
  waitForInput: 30000      # 30 秒等待人类输入
  maxRuntime: 172800000    # 48 小时单任务最大运行时
  idleWatchdog: 300000     # 5 分钟无响应判定为挂死 watchdog 自动休眠
  toolExecution: 120000    # 单个工具执行硬超时 (2 分钟)

机制横评：Claude Code vs OpenClaw 执行循环

核心维度 Claude Code（Anthropic 商业闭源） OpenClaw（开源独立网关） 胜出与工程评注
上下文压缩 大模型直接摘要（无验证环节） 标识符保留机制 + 质量检查点重试 OpenClaw：杜绝压缩后丢失函数名与行号
工具安全机制 简单的 Shell 命令黑名单 四层防护：正则 + Ed25519 签名 + 沙箱 + 权限降级 OpenClaw：企业级防御更严密
缓存优化 官方 Prompt Caching 深度集成 依赖各 Provider 原生行为 Claude Code：原厂首字延迟更优
任务隔离 同进程子智能体（SubAgent） 独立 Worktree 目录 + 独立 Session 锁 OpenClaw：支持多分支无踩踏修改

关联导航