06. Agent Runtime：一次消息如何变成模型和工具调用

这篇解决什么问题

OpenClaw 的核心不是某个 channel，也不是 openclaw.mjs。

真正决定助手怎么回答、怎么调用工具、怎么保存会话的是 Agent Runtime。

官方架构文档明确说：

OpenClaw owns the built-in agent runtime directly.

runtime code 在：

src/agents/

model/provider helpers 在：

src/llm/

先看哪些目录

src/agents/embedded-agent-runner/
src/agents/sessions/
src/agents/agent-tools*.ts
src/agents/agent-hooks/
src/agents/runtime/
packages/agent-core/
src/llm/

不要一上来扫完整 src/agents/。这个目录里测试很多，直接看会乱。

一次消息的简化链路

可以先这样理解：

Gateway 或 CLI 收到用户消息
→ 找到 agent 和 session
→ Agent Runtime 加载 session 状态
→ 构造系统提示词、项目上下文、skills、tools
→ 选择模型 provider
→ 发起流式模型调用
→ 如果模型请求工具，执行工具
→ 把工具结果追加回上下文
→ 继续模型调用或生成最终回复
→ 保存 session
→ 回复交给 CLI 或 Gateway 投递

这和很多 tool-calling agent 的主循环相似，但 OpenClaw 加了很多平台、权限、sandbox、plugin 和 session 细节。

Runtime Layout 怎么读

官方文档给了几个关键点：

src/agents/embedded-agent-runner/：attempt loop、provider stream adapters、compaction、model selection、session wiring
src/agents/sessions/：session persistence、extension loading、resource discovery、skills、prompts、themes、TUI-backed tool renderers
packages/agent-core/：可复用 agent core、harness types、messages、compaction helpers、prompt templates、tool/session contracts
src/agents/runtime/：OpenClaw facade for @openclaw/agent-core
src/agents/agent-tools*.ts：OpenClaw-owned tool definitions、schemas、policy、hooks、host edit support
src/agents/agent-hooks/：built-in runtime hooks
src/llm/：model/provider registry 和 stream implementations

这基本就是 Agent Runtime 的地图。

不要把 Gateway 和 Runtime 混在一起

Gateway 负责接消息、路由、投递。

Runtime 负责真正的 Agent 运行。

如果 Telegram 消息没进来，优先查 channel/Gateway。

如果消息进来了但模型调用失败，优先查 runtime/provider/auth profile。

如果模型调用了不该调用的工具，优先查 tools policy/sandbox。

Runtime 难点在哪里

难点不只是“调用一次 LLM”。

真正复杂的是：

• 多 provider；
• 流式响应；
• session 持久化；
• tool schema 和 tool policy；
• before/after tool call hooks；
• compaction；
• sandbox；
• plugin tools；
• channel/sender/group 不同权限；
• 子 agent / envelope session。

所以读源码时要抓主线，不要被所有测试和策略文件带散。

下一篇看什么

下一篇看模型 provider 和流式响应。