OpenClaw Agent Loop 是一个“程序+模型”双重驱动的循环框架。一次使用者发来的消息并不等同于一次模型推理。而是可能触发多轮模型调用与工具执行，最终才得到一个完整回答。

一、概念梳理：Turn / Run / Model Call / Tool Call

概念	含义
Session	跨 Turn 的持续会话状态。
Run	一次完整 Agent 运行（runId)。
Model Call	Agent Loop 内一次 Provider 推理请求。
Tool Call	模型发出的工具执行请求。
Tool Result	工具执行后的返回结果，以toolCallId-匹配。
Final Answer	LIFO 最终文本（stopReason=stop)。
Transcript	Persisted 会话事件序列。
Trajectory"收尾快照"式运行记录。
Slogan：A single Turn ≠ one Model Call;a Run may contain many.
User Pain Point: 开发者往往把“Turn”当作“一次完整推理”，导致在调试时误判耗费和性能瓶颈。

User Pain Point: 错误地把单个 Turn 视为单次模型调用，导致计费估算失真和性能调优困难。

二、Agent Loop 主要结构

sequenceDiagram
autonumber
participant U as 使用者
participant R as Runtime
participant E as Context Engine
participant M as Model
participant X as Tool
U->R : 一条消息
loop 直到模型不再要求工具
R->E : 组装本轮 Context
E->M : 提交 Prompt
alt stopReason = toolUse
M-->R : 返回 Tool Call
R-->X : 校验并执行工具
X-->R : Tool Result
R-->R : 回填 Transcript。进入下一圈
else stopReason = stop
M-->R : 返回最终文本
end
end
R-->U : Final Answer

This diagram shows that outer loop is hard‑coded,but wher to call a tool or finish is decided by model each round.

User Pain Point: 缺乏可视化流程导致难以快速定位哪一步触发了额外工具调用，从而造成不可预期的延迟和成本飙升。

Pseudo Code

while True:
context = assemble_context
response = model
if response.has_tool_call:
result = runtime.execute
transcript.append
transcript.append
continue # 继续循环
return response.text # 收尾

The loop itself is deterministic;decision tree is entirely in model’s natural language reasoning.

User Pain Point: 不了解“stopReason”字段是 Provider 层面的标记，导致日志分析时误读控制流逻辑。

三、实验设计：两跳读取案例逼出真实多步循环

关键在让接下来无法提前预测。使模型必须实际走两圈：

1. 先读 manifest.txt'.
2. 第二个文件方法写在 Manifest 中，仅在第一条 Tool Result 后才知晓；
3. 再读 target.txt'.
4. 返回 MARKER/VALUES/SUM 等结果。

若第二方法已知则可提前完成，否则模型必须按顺序循环。该实验用 DeepsSeek-official/DeepSeek-v4-flash** 实例演示，无任何全局配置改动。

User Pain Point: 无法确定循环长度导致费用不确定性和实时监控缺失。

四、主实验结果：一次 Turn → 多次 Model Call & Tool Call

< < td> < td>5

#	事件	stopReason	关键内容
1	Model Call toolUse read	toolUse
2	Tool Result—Manifest 暴露 TARGET_FILE=…/target.txt
3	Model Call toolUse read
4	Tool Result—VALUE_A= …,VALUE_B= ，
No more tools → Final Answer SUM=…​

从 Transcript 可以看到，一个 Turn 产生了： {Run}={1} · {Model Calls}={5} · {Tool Calls}={2} · {Tool Results}={2} · {Final Answers}=1.

• The loop red‑green light： toolUse⇒continue ;stop⇒exit . Note that only Assistant messages carry stopReason.
• The pairing anchor： ID ↔ toolCallId matches exactly.
• The re‑feed effect： The first Tool Result feeds back into next Context and triggers second read.
• Caching note： Cumulative input shows repeated cache hits but per‑call input remains small.
  • Runtime只检查技术成功；怎么说呢，Model决定语义后续动作。
  • A rule change in manifest changes only one line of result → different loop length demonstrates probabilistic decision making.
  • The system equals “programmed loop + model driven actions.”

User Pain Point: 对“stopReason”和“toolCallId”混淆导致日志分析错误，并错估是否真正完成任务。

""

""

"

"

---