goclaw Agent核心循环剖析:一条消息如何驱动LLM与工具调用完成闭环
goclaw Agent核心循环剖析:一条消息如何驱动LLM与工具调用完成闭环
goclaw 是一个用 Go 编写的开源 AI Agent 框架(对标 OpenClaw)。本文将带你深入它的 Agent 核心循环:一条普通的用户消息,如何驱动 LLM 与工具调用反复迭代、自我纠错,最终形成完整闭环并流式返回给用户。读懂这套机制,你就掌握了构建任何"会动手"的 AI 助手的核心逻辑。

上图是 goclaw 真实运行场景:左侧终端滚动着
Agent iteration attempt 1/2/3、Executing tool等日志,右侧微信里用户正在追问天气。这正是"一条消息驱动 LLM 与工具调用闭环"的直观写照。
一条消息的旅程:闭环是如何跑通的
要理解核心循环,先看一条消息从"发出"到"收到回复"要跨越的几道关隘。整条链路被设计成清晰的单向流:
- Channel(通道层):消息从 Telegram、飞书、微信等渠道进入,由适配器统一规范化(见 channels/base.go)。
- Bus(消息总线):消息被推入总线队列,实现通道与 Agent 的解耦(见 bus/queue.go)。
- Agent(主代理):从总线消费消息,定位会话、装载历史,然后交给核心引擎(见 agent/agent.go)。
- Orchestrator(编排器):真正驱动"LLM ↔ 工具"反复迭代的引擎,是本文的主角。
- 回程:最终文本经总线发布,再由原通道发回给用户,闭环完成。
Agent 在 agent/agent.go 中的 handleInboundMessage 方法是入口。它做三件关键事:根据渠道 + 聊天 ID 生成会话 key;通过 session.Manager 获取或创建会话;用 GetHistorySafe 安全装载历史消息——注意这个"Safe"很关键,它会保证不会拆散"工具调用—工具结果"的成对关系,否则下次喂给 LLM 时上下文就会错乱。
核心引擎:Orchestrator 的双循环架构
真正的循环藏在 agent/orchestrator.go 里。它借鉴了 pi-mono 的 agent-loop.ts 设计,采用了一套双循环(Dual Loop)架构,把两种截然不同的"任务来源"分层处理:
图中右下角的 Agentic Loop 方框就是核心循环的精髓:
LLM response → tool_call? → Yes → execute,反复直到No → Final Text。
- 外层循环(Outer Loop):只负责一件事——处理 FollowUp(后续任务)。内层跑完后,它检查队列里有没有"任务完成后要自动触发的新任务",有就继续、没有就退出。
- 内层循环(Inner Loop):真正的干活区,条件是"还有工具调用 或 有待处理消息"。它负责调 LLM、执行工具、检查中断。
这套分层的妙处在于职责清晰:重试、故障转移、上下文压缩这些"恢复逻辑"全部封装在内层循环的 LLM 调用层,而外层循环只关心任务链的延续。对比之下,OpenClaw 是把恢复逻辑放在外层循环里,goclaw 选择了把复杂度收进调用层,代码更易读。
内层循环:LLM 与工具调用如何反复迭代
进入内层循环,每一轮(iteration)都按固定节拍推进,这正是"闭环"二字的核心:
- 取消检查:先看
context是否被取消(超时或用户停止),随时可优雅中断。 - 迭代上限检查:超过
MaxIterations(默认 15)就强制让 LLM 收束,避免无限打转。 - 注入待处理消息:把队列里的 Steering 中断消息塞进对话。
- 调用 LLM:通过
streamAssistantResponse构建系统提示词(含工具定义与已加载技能),支持流式返回。 - 提取工具调用:从 LLM 响应里解析出
tool_call。 - 执行工具:
executeToolCalls逐个执行,把结果作为新的tool角色消息追加回对话,然后回到第 1 步。
关键在于第 6 步之后:只要 LLM 还返回工具调用,hasMoreToolCalls 就为真,循环就继续。于是"问 LLM → LLM 要工具 → 执行工具 → 把结果喂回 LLM"这条链路会自动往复,直到 LLM 认为信息够了、直接吐出一段最终文本,循环才自然收敛。
工具从哪里来?由 agent/tools/registry.go 的 Registry 统一管理,内置了文件系统、Shell、Web、浏览器、记忆、技能等工具。每个工具实现统一的 Tool 接口(见 agent/types.go),执行时还会被放进独立 goroutine 并附带默认 3 分钟超时,防止某个工具卡死整个循环。
三道安全护栏:迭代上限、重试与上下文压缩
一个"会自己打转"的循环最怕失控,goclaw 在内层循环里内置了三道护栏,让它既灵活又稳健:
- 迭代上限:
MaxIterations是硬约束。达到上限时,Agent 不会直接报错,而是插入一条系统提示,"恳请"LLM 基于已有工具结果给出最终回答,再收束循环——给用户的是完整答案而非中断。 - 智能重试:LLM 调用失败时,agent/retry.go 的
RetryManager会先分类错误(认证、限流、超时、上下文溢出、计费),再对症下药:- 认证错误 → 轮换 Profile(换备用 LLM 配置)
- 限流错误 → 指数退避(默认起步 2 秒、最多 60 秒)
- 超时/计费 → 轮换 Profile
- 上下文溢出 → 压缩上下文
- 上下文压缩:当历史消息过长触发溢出时,
compressMessages会保留最近 4 条消息,把更早的部分压缩成一段"上下文摘要",既保住关键信息又压回窗口内,让循环得以继续。
这三道护栏共同保证:即使 LLM 抖动、网络闪断、上下文超长,闭环也能自我修复而不轻易对用户报错。
Steering 与 FollowUp:中断与任务链
goclaw 还给循环加了两个"人类可介入"的通道,这是很多简单 Agent 框架缺失的能力:
- Steering(转向/中断):在 Agent 执行过程中插入一条紧急消息,它会打断当前工具链。比如你让 Agent 跑长任务,中途发现方向不对,可以立即
Steer一条"停下,改做 X",循环会在下一个工具执行间隙捕获它并转向。 - FollowUp(后续任务):当前任务完成之后自动触发的新任务。它由外层循环消费,天然适合"分析项目 → 生成报告 → 发送邮件"这种链式流程。
两者都支持 all(一次注入全部)和 one-at-a-time(逐条注入)两种队列模式,定义见 agent/types.go 的 MessageQueueMode。这套机制让 Agent 不再是"一锤子买卖",而是一个可以被用户实时引导、还能自我续命的长跑选手。
事件系统与流式输出:让闭环"看得见"
循环每走一步都会向外发射事件,类型定义同样在 agent/types.go:从 agent_start、turn_start,到 stream_content、tool_execution_start,再到 agent_end。这些事件流经 Agent.Subscribe() 暴露的 channel,被 UI 或 TUI 实时消费。
上图是 goclaw 内置的 Dashboard 聊天面板。用户提问后,Assistant 的回复是流式逐字打出来的,中间穿插着代码块与工具执行过程——背后正是
stream_content与tool_execution_*事件在驱动。
这种"事件驱动 + 流式输出"的设计,让一条消息从"进"到"出"的闭环全程透明:你能看到 LLM 在思考什么、调了哪个工具、工具返回了什么。对新手来说,这是调试和建立信任的最佳抓手。
小结
goclaw 的 Agent 核心循环,本质是一条精心编排的闭环流水线:
- 进:Channel → Bus → Agent,消息被规范、排队、定位到会话。
- 转:Orchestrator 双循环里,"问 LLM → 执行工具 → 喂回结果"反复迭代,直到 LLM 给出最终文本。
- 守:迭代上限、智能重试、上下文压缩三道护栏,让循环在失控边缘自动纠偏。
- 控:Steering 与 FollowUp 把用户实时介入和任务链续命编织进循环。
- 出:事件系统与流式输出,让整条闭环对用户可见、可调试。
想动手读懂这套机制,建议从 docs/design/agent-design.md 的架构设计与 docs/design/agent-sequence.md 的序列图入手,再对照 agent/orchestrator.go 的 runLoop 逐行细读。你会发现,所谓"会动手的 AI",不过是把 LLM 和工具用一个健壮的循环稳稳串了起来。

