OpenClaw Runtime 源码级解析：从 CLI 到 Agent Execution Engine

OpenClaw 的 Agent Runtime 由 Control Plane、Model System、Execution Engine、Runtime Surfaces、Streaming Event System 五个子系统构成，共同完成从 CLI 请求到 Agent 推理再到结果流式输出的完整执行路径。

┌──────────────────────┐ │ CLI ENTRY │ │ │ │ openclaw.mjs │ │ src/entry.ts │ │ run-main.ts │ └─────────┬───────────┘ │ ▼ ┌─────────────────────────────────┐ │ CLI COMMAND LAYER │ │ │ │ src/cli/program/* │ │ register.agent.ts │ │ command-registry.ts │ │ register.subclis.ts │ └──────────────┬──────────────────┘ │ ▼ ┌──────────────────────────────────────┐ │ GATEWAY CLIENT │ │ │ │ src/commands/agent-via-gateway.ts │ │ callGateway("agent") │ │ local fallback → agentCommand │ └──────────────┬───────────────────────┘ │ ▼ ┌────────────────────────────────────────┐ │ GATEWAY SERVER │ │ │ │ src/gateway/server.impl.ts │ │ src/gateway/server-methods.ts │ │ src/gateway/server-methods/agent.ts │ │ │ │ RPC dispatch │ └──────────────┬─────────────────────────┘ │ ▼ ┌──────────────────────────────────────────┐ │ AGENT CONTROL PLANE │ │ │ │ src/commands/agent.ts │ │ │ │ responsibilities: │ │ - config resolution │ │ - secret resolution │ │ - session loading │ │ - agent workspace │ │ - model selection │ │ - lifecycle events │ │ - delivery │ └──────────────┬───────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ EMBEDDED RUNNER │ │ │ │ src/agents/pi-embedded-runner/run.ts │ │ │ │ responsibilities: │ │ - resolveModel() │ │ - auth profile rotation │ │ - retry / fallback │ │ - invoke runEmbeddedAttempt │ └──────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ MODEL SYSTEM │ │ │ │ Model Binding │ │ src/agents/pi-embedded-runner/model.ts │ │ │ │ Model Policy │ │ src/agents/model-selection.ts │ │ │ │ Model Catalog │ │ src/agents/model-catalog.ts │ │ │ │ Config Projection │ │ src/agents/models-config.ts │ │ │ │ API Adapter Layer │ │ openai-completions / anthropic / ollama / etc │ └──────────────┬──────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ EXECUTION ENGINE │ │ │ │ src/agents/pi-embedded-runner/run/attempt.ts │ │ │ │ responsibilities: │ │ - workspace setup │ │ - session manager │ │ - prompt execution │ │ - streaming orchestration │ └──────────────┬───────────────────────────────────────────────┘ │ ▼ ┌───────────────────────────────────────────────────────────────┐ │ TOOL SYSTEM │ │ │ │ src/agents/pi-tools.ts │ │ │ │ Tool assembly pipeline: │ │ - filesystem tools │ │ - command execution tools │ │ - patch tools │ │ - channel tools │ │ - OpenClaw internal tools │ │ │ │ Policy filtering │ │ - config policies │ │ - sandbox │ │ - owner-only tools │ └──────────────┬────────────────────────────────────────────────┘ │ ▼ ┌───────────────────────────────────────────────────────────────┐ │ PROMPT SYSTEM │ │ │ │ src/agents/pi-embedded-runner/system-prompt.ts │ │ │ │ Adapter layer │ │ │ │ delegates to: │ │ src/agents/system-prompt.ts │ │ │ │ prompt contents: │ │ - tool summaries │ │ - skills │ │ - runtime context │ │ - workspace metadata │ │ - user/time/context files │ └──────────────┬────────────────────────────────────────────────┘ │ ▼ ┌───────────────────────────────────────────────────────────────┐ │ MODEL EXECUTION │ │ │ │ activeSession.prompt() │ │ │ │ streaming LLM interaction │ │ │ │ tool calls │ │ reasoning stream │ └──────────────┬────────────────────────────────────────────────┘ │ ▼ ┌───────────────────────────────────────────────────────────────┐ │ STREAM EVENT SYSTEM │ │ │ │ src/agents/pi-embedded-subscribe.ts │ │ │ │ responsibilities: │ │ - partial replies │ │ - reasoning stream │ │ - tool results │ │ - usage accumulation │ │ - compaction retry │ │ │ │ session.subscribe(...) │ └──────────────┬────────────────────────────────────────────────┘ │ ▼ ┌───────────────────────────────────────────────────────────────┐ │ RESULT DELIVERY │ │ │ │ src/commands/agent/delivery.ts │ │ src/infra/outbound/deliver.ts │ │ │ │ payload formatting │ │ outbound channel dispatch │ └──────────────┬────────────────────────────────────────────────┘ │ ▼ ┌───────────────────────────────────┐ │ CLIENT OUTPUT │ │ │ │ CLI output │ │ Gateway WS clients │ │ Channels │ └──────────────────────────────────

这张图最重要的四个 Runtime 子系统总结为：

1️⃣ Control Plane

负责 Agent 调度与状态管理

核心代码：

src/commands/agent.ts

2️⃣ Model System

负责 模型选择与绑定

核心代码：

model-selection.ts model-catalog.ts model.ts

3️⃣ Execution Engine

负责 真正执行 agent run

核心代码：

run.ts run/attempt.ts

4️⃣ Runtime Surfaces

模型看到的能力：

Tools

src/agents/pi-tools.ts

Prompt

system-prompt.ts

5️⃣ Streaming/Event System

负责：

partial replies tool results reasoning stream usage

核心：

pi-embedded-subscribe.ts