OpenClaw学习总结_I_核心架构系列_AgentLoop详解

I. 核心架构 - 2. Agent Loop

📍 课程位置

阶段：I. 核心架构
课序：第 2 课
前置知识 ：I-1. Gateway 架构
后续课程：I-3. Context 管理

🎯 本课核心问题

如果你问我："OpenClaw 的 Agent 是怎么工作的？一条消息进来后，它是怎么处理的？"

我会这样回答 ：Agent 有一个完整的工作循环 ，叫 Agent Loop ，像工厂的流水线，一条消息进来后，会经过 6 个阶段的处理。

📚 你需要理解的六个阶段

阶段 1：Message（消息接收）

发生了什么：

Gateway 收到一条消息
转发给 Agent
Agent 开始处理

类比：

工厂门口收到了一个订单
订单被放到传送带上

关键点：

消息来源：可以是 WhatsApp、Telegram、Discord 等
消息格式：被 Gateway 标准化后发送
消息内容：文本、图片、文件等都行

阶段 2：Context Assembly（上下文组装）

发生了什么：

Agent 把"需要知道的信息"组装起来
包括：系统提示词、对话历史、可用工具

类比：

工厂里，工人开始准备
查看订单要求（系统提示词）
翻看之前的加工记录（对话历史）
看看手边有哪些工具（可用工具）

关键点：

这个阶段决定 Agent "知道什么"
上下文太长会有成本问题
可以通过 Compaction 优化（后面会讲）

阶段 3：Model Inference（模型推理）

发生了什么：

把组装好的上下文发给 AI 模型
模型思考并决定：回复什么？用什么工具？

类比：

工人根据订单要求、历史记录、工具清单
思考："我应该怎么做？"
决定："我需要查一下库存，然后用原材料加工"

关键点：

这个阶段调用外部 AI 服务（如 Claude）
模型可以调用工具（Tool Calling）
可以设置多个模型作为备份（Model Failover）

阶段 4：Tool Execution（工具执行）

发生了什么：

如果模型决定需要调用工具，就执行
工具可以是：发消息、读文件、执行命令、浏览器操作等

类比：

工人去仓库查库存
或者操作机器加工产品
或者叫其他工人帮忙

关键点：

工具执行后，结果返回给模型
模型根据结果继续推理
可以多次执行工具（循环）

阶段 5：Streaming（流式输出）

发生了什么：

把回复内容实时显示给用户
不是等全部生成完再显示，而是一个字一个字地显示

类比：

工厂流水线上的产品
完成后不是一次性交付
而是在生产过程中就展示给客户看

关键点：

用户体验更好（更快看到回复）
可以显示"正在输入"状态
有两种模式：Block（等全部）和 Preview（实时）

阶段 6：Persistence（持久化）

发生了什么：

把对话内容保存到磁盘
这样下次对话时，Agent 知道"之前聊过什么"

类比：

工厂把这次的加工记录存档
下次有类似订单，可以参考之前的做法

关键点：

保存位置：~/.openclaw/agents/<agentId>/sessions/
格式：JSONL（每行一个 JSON）
Session 会被定期压缩（Compaction）来节省空间

🔄 完整的 Agent Loop 流程图

复制代码

Message（消息进来）
    ↓
Context Assembly（组装上下文）
    ↓
Model Inference（AI 思考）
    ↓
    ├─ 需要工具？ → Tool Execution（执行工具）
    │                    ↓
    │               回到 Model Inference（继续思考）
    │                    ↓
    └─ 不需要工具？
         ↓
Streaming（流式输出给用户）
    ↓
Persistence（保存到磁盘）
    ↓
结束，等待下一条消息

💡 这个设计的关键点

1. 可扩展性

每个阶段都可以干预和定制
就像工厂流水线的每个环节都可以调整
通过 Hooks 可以在关键点插入自定义逻辑

2. 上下文成本

上下文不是免费的
token 需要花钱
所以需要** Compaction** 来压缩（后面会讲）

3. 工具调用

Agent 不是只"说话"，还能"做事"
可以执行命令、读写文件、控制浏览器
通过 Tool Calling 实现

4. 会话管理

每次对话都会被保存
下次继续时可以"记得"
但如果太长，会压缩（Compaction）

🔧 实战：看看 Agent Loop 在做什么

查看当前会话

bash 复制代码

# 查看 Agent 的会话列表
openclaw sessions list

# 查看某个会话的详情
openclaw sessions show <sessionId>

# 查看对话历史
cat ~/.openclaw/agents/main/sessions/*.jsonl

查看日志

bash 复制代码

# 实时查看 Agent 处理的日志
openclaw logs --follow | grep "agent"

# 会显示每个阶段的详细信息

调试工具调用

bash 复制代码

# 如果你想看 Agent 调用了什么工具
# 查看日志中的 tool_call 相关内容
openclaw logs | grep -i tool

⚠️ 常见陷阱

陷阱	表现	原因	解决
上下文太长	"Token limit exceeded"	对话历史太长	使用 Compaction
工具执行失败	"Tool execution failed"	工具参数错误或权限问题	检查工具配置
模型超时	"Request timeout"	模型响应太慢	设置更长的超时时间
死循环	Agent 不停调用同一个工具	工具逻辑问题	检查工具设计

📝 学习心得

我学这一课时的体会

我之前以为 Agent 就是"收到消息 → 回复消息"的简单过程。

学完后才发现，中间有这么多复杂的阶段！尤其是：

Tool Execution 循环 - 模型可以多次调用工具，这让我想到"如果工具设计不好，可能会陷入死循环"
Context 成本 - 之前没意识到，每次对话都在"累积成本"，Compaction 是必须的
Hooks 的强大 - 原来可以在每个阶段插入自定义逻辑，这为自动化提供了无限可能

与其他课程的关联

前置课程：Gateway 架构 - 消息从 Gateway 来到 Agent
后续课程：Context 管理 - 详细讲阶段 2
配合课程：Session 管理 - 阶段 6 的持久化
配合课程：Compaction - 优化阶段 2 和 6

✅ 你现在应该理解的

说出 Agent Loop 的 6 个阶段
解释每个阶段在做什么
画出完整的流程图
知道 Context 成本是什么
理解工具调用和循环

📚 快速参考表

阶段	名称	做什么
1	Message	接收消息
2	Context Assembly	组装上下文（系统提示词+历史+工具）
3	Model Inference	AI 模型思考
4	Tool Execution	执行工具（如需要）
5	Streaming	流式输出回复
6	Persistence	保存对话到磁盘

🔗 相关资源

官方文档：

Agent Loop：https://docs.openclaw.ai/concepts/agent-loop
Hooks：https://docs.openclaw.ai/automation/hooks
Session：https://docs.openclaw.ai/concepts/session

相关课程：

上一课：I-1. Gateway 架构
下一课：I-3. Context 管理

📊 本课总结

最关键的 3 点：

6 阶段流水线
- Message → Context → Model → Tool → Stream → Persist
- 每个阶段都可以定制和干预
工具调用的循环
- 模型可以多次调用工具
- 需要注意不要陷入死循环
为后续课程打基础
- Context 管理（阶段 2）
- Session 管理（阶段 6）
- Compaction（优化 2 和 6）

现在你应该理解了 Agent 是怎么"思考"的。下一课会讲它"思考时需要什么"（Context 管理）。