1. 项目概述从源码视角拆解AI Agent的“思考”过程最近在社区里看到不少朋友对AI Agent的开发跃跃欲试但一提到“Agent是怎么思考的”往往就停留在“LLM工具调用”的模糊概念上。正好我最近花了不少时间深入研究了OpenClaw这个开源AI Agent框架的源码特别是它的核心执行循环与工具调用机制。这就像拆开一个精密的钟表看里面的齿轮如何咬合运转。今天我就结合OpenClaw的代码和大家聊聊一个AI Agent从“接收指令”到“完成任务”的完整“思考”链路。无论你是想自己动手搭建一个Agent还是单纯想理解其背后的工作原理相信这篇从实战源码出发的解析都能给你带来启发。我们会避开空洞的理论直接深入到代码逻辑和设计模式中看看一个成熟的Agent框架是如何处理规划、执行、反思这些关键环节的。2. OpenClaw执行循环的深度解析2.1 核心循环结构从step到_loopOpenClaw的执行引擎核心是一个状态机驱动的循环。在它的源码中你会发现一个名为Agent的基类或核心运行类其中包含了一个run或start方法而真正的“思考”循环往往封装在类似_main_loop、_step或_reasoning_cycle的方法里。这个循环的本质是在达到终止条件如任务完成、失败、超时前不断地“感知-思考-行动”。以典型的伪代码结构为例这个循环可能长这样def _run_loop(self, initial_task): state self._initialize_state(initial_task) while not self._should_stop(state): # 1. 观察与状态更新 observation self._observe(state) state.update(observation) # 2. 思考与规划核心推理 reasoning_result self._reason(state) state.update(reasoning_result) # 3. 决策与行动 action self._decide(state) execution_result self._act(action) # 4. 反思与状态演进 reflection self._reflect(state, execution_result) state.update(reflection, execution_result) return state.final_result这个循环的每一轮step都是一次完整的“认知-行动”周期。OpenClaw的巧妙之处在于它将这个循环的各个阶段如_reason、_act设计成了可插拔的组件比如通过不同的Planner规划器、Executor执行器来实现。在阅读源码时你需要重点关注while循环的条件判断_should_stop它通常由几个因素决定任务是否被标记为完成state.is_finished、循环步数是否超过最大限制steps_exceeded、是否出现了无法处理的错误has_fatal_error等。理解这个终止逻辑对于调试Agent卡死或提前结束的问题至关重要。注意在实际的OpenClaw源码中类和方法名可能有所不同例如核心循环可能在一个Engine或Orchestrator类中。关键是抓住“循环”、“状态”、“阶段”这几个核心概念去追踪代码流。2.2 状态管理记忆、上下文与历史轨迹Agent的“思考”离不开状态。OpenClaw内部维护着一个核心的State或Context对象它贯穿整个执行循环是信息流动的载体。这个状态对象通常包含以下几个关键部分任务目标Objective用户最初提出的请求例如“帮我分析这个季度的销售数据报告”。这是所有行动的北极星。执行历史History一个按时间顺序排列的列表记录着每一轮循环中Agent的思考过程、做出的决策、执行的动作以及动作返回的结果。格式可能类似于(thought, action, observation)的三元组。这是Agent进行反思和规划的重要依据。工作记忆Working Memory当前循环步骤中临时的、需要重点关注的信息。例如上一步工具调用返回的JSON数据中的某个关键字段。长期记忆Long-term Memory如有一些框架会引入向量数据库等让Agent能记住跨会话的信息。OpenClaw的基础循环可能更侧重于工作记忆和短期历史。在源码中你会看到state对象在各个组件间被传递和修改。例如在_reason阶段规划器会读取state.history来理解已经做了什么在_act阶段执行器会将工具执行的结果追加到state.history中。一个常见的实现细节是为了控制上下文长度避免给LLM的提示词过长state中保存的历史记录可能会被截断、总结或只保留最近N条。在OpenClaw中可能需要关注HistoryTruncator或类似组件。2.3 规划与推理模块LLM的提示工程执行循环中的_reason阶段是Agent的“大脑”通常由一个或多个LLM调用驱动。OpenClaw的规划器比如ReActPlanner或ZeroShotPlanner负责组织提示词Prompt引导LLM进行结构化思考。一个经典的ReActReasoning Acting模式提示词模板在源码中可能这样构建def _build_react_prompt(self, state): prompt_template 你是一个AI助手。你的任务是{objective} 到目前为止你已经完成了以下步骤 {history} 当前情况是{current_situation} 请逐步思考。你可以使用以下工具{tool_descriptions} 你的思考过程应该遵循‘Thought:’ ‘Action:’ ‘Observation:’的格式。 Thought: 这里分析当前情况决定下一步做什么 Action: 这里调用工具格式为 JSON例如 {{tool_name: search_web, parameters: {{query: ...}}}} # ... 填充模板变量 return filled_prompt关键点在于OpenClaw的源码会严格定义LLM输出的解析逻辑。它不会简单地让LLM自由发挥而是期望一个特定格式如JSON、YAML或带关键字的文本的响应。解析器OutputParser会从LLM的回复中提取出结构化的Thought思考和Action行动指令。如果解析失败框架通常会进入错误处理流程比如要求LLM重试或触发降级策略。在阅读这部分源码时要特别注意异常处理try-catch块这是Agent鲁棒性的体现。3. 工具调用机制的实现细节3.1 工具的定义、注册与发现工具Tool是Agent延伸能力的“手脚”。在OpenClaw中一个工具通常被定义为一个Python类或函数并使用装饰器或注册机制告知框架。核心的Tool基类或接口可能会要求定义几个关键属性name: 工具的唯一标识符LLM将通过这个名字来调用它。description: 工具功能的自然语言描述。这个描述至关重要它是LLM理解何时以及如何使用该工具的“说明书”。描述应清晰说明功能、输入参数和预期输出。parameters_schema: 输入参数的JSON Schema定义。这确保了LLM生成的调用参数是结构化的、类型安全的。func或_run方法工具的实际执行逻辑。工具注册通常在一个中心化的ToolRegistry或Toolkit中完成。源码中会有一个地方可能是Agent初始化时将所有可用工具加载到这个注册表中。当规划器构建提示词时会从注册表中获取所有工具的name和description拼接到提示词里供LLM参考。这种设计使得工具系统非常易于扩展你只需要按照框架约定编写新的工具类并注册即可。3.2 从指令到执行工具调用的完整链路当LLM输出一个格式正确的Action后执行循环就进入了_act阶段。这个过程在源码中是一条清晰的链路动作解析Action Parsing首先将LLM输出的字符串如{tool_name: calculator, parameters: {expression: 5*82}}解析成一个内部的Action对象。这个对象包含了工具名和参数字典。工具查找Tool Lookup根据Action对象中的工具名去ToolRegistry中查找对应的工具实例。如果找不到会抛出ToolNotFoundError。参数验证Parameter Validation使用工具的parameters_schema对传入的参数进行验证。检查参数类型字符串、数字等、是否必填、格式是否符合要求。这是防止LLM“胡言乱语”导致运行时错误的重要防线。安全与权限检查Security Check可选但重要在一些企业级或注重安全的Agent框架中这里会有一层钩子Hook检查当前Agent上下文是否有权限调用这个工具特别是涉及数据删除、网络访问、系统命令等敏感操作的工具。OpenClaw可能提供了类似的扩展点。工具执行Tool Execution调用工具对象的_run方法传入验证后的参数。执行是同步的并会捕获任何异常。结果封装Result Packaging将工具执行的结果或异常信息封装成一个Observation观察对象。这个对象随后会被添加到state.history中成为下一轮“思考”的输入。实操心得工具执行的超时控制是生产环境必须考虑的。在源码中你可能会看到工具调用被包裹在timeout上下文管理器中。如果一个工具如网络请求长时间没有返回框架应该能中断它避免整个Agent被阻塞。3.3 错误处理与重试策略工具调用不可能一帆风顺。网络可能超时API可能返回错误参数可能虽然通过验证但逻辑上无效。一个健壮的Agent框架必须有完善的错误处理机制。在OpenClaw的源码中你可能会看到如下模式执行层错误在_act阶段工具_run方法抛出的异常会被捕获。框架不会让这个异常直接崩溃整个Agent而是会将一个格式化的错误信息如Tool ‘XXX‘ execution failed: Connection timeout作为Observation返回。这样LLM在下一轮思考时就能“看到”这个错误并有机会调整策略例如重试、换一种方式或向用户求助。LLM输出解析错误如果LLM没有按照预定格式输出解析器会抛出ParsingError。框架的处理策略可能是1) 将解析错误信息反馈给LLM要求它重新生成格式正确的响应这通常需要在一个修复循环中2) 达到最大重试次数后降级为更简单的动作或直接失败。重试逻辑框架可能在多个层面设置重试。例如对于网络工具调用本身可能有重试对于因LLM输出格式错误导致的步骤可能有循环重试。源码中的max_retries、retry_delay等配置参数需要关注。4. 结合源码看典型工作流与调试技巧4.1 一个完整的“搜索-总结”任务流程拆解让我们通过一个假设的、但贴合OpenClaw设计模式的任务来串联上述所有模块。任务目标是“查询今天纽约的天气并判断是否适合户外跑步。”初始化Agent创建state.objective被设置为任务目标。工具注册表加载了search_web和get_weather等工具。循环第一步_reason: 规划器构建提示词包含目标、空历史和工具列表。LLM思考后输出Thought: 我需要先获取纽约今天的天气信息。Action: {tool_name: get_weather, parameters: {location: New York}}。_act: 解析动作调用get_weather工具可能调用一个天气API获得结果Observation: {location: New York, temp: 22°C, condition: Sunny, humidity: 65%}。该结果被加入历史。循环第二步_reason: 规划器再次构建提示词这次历史中包含了上一步的观察。LLM输出Thought: 天气晴朗温度22度湿度适中。这非常适合户外跑步。Action: {tool_name: final_answer, parameters: {answer: 今天纽约天气晴朗22度湿度65%非常适合户外跑步。}}。_act: 调用final_answer工具可能是一个特殊工具用于向用户输出最终结果。Observation: Task completed.。循环终止_should_stop检测到任务完成状态循环结束。在OpenClaw源码中跟踪这个流程你可以设置断点或添加日志观察state对象在每个阶段的变化特别是history列表的逐步增长。4.2 源码级调试日志、追踪与可视化开发或调试自己的Agent时深入理解框架的日志输出是关键。OpenClaw通常会有不同级别的日志DEBUG, INFO, WARN。开启DEBUG日志这能让你看到最详细的信息包括每一轮循环的完整提示词、LLM的原始响应、工具调用的参数和原始结果。这是理解Agent“内心独白”的最直接方式。追踪State变化可以临时修改源码在每轮循环开始和结束时打印或导出state对象的快照尤其是history。这有助于你发现信息在传递过程中是否丢失或被误解。工具调用监控重点关注工具执行前后的日志。参数是否正确传递执行耗时是否异常返回的结果结构是否符合LLM的预期利用可视化工具如果框架支持一些先进的Agent框架或监控平台能图形化展示Agent的执行轨迹Execution Trace以流程图或时间线的方式清晰呈现“Thought-Action-Observation”的链条。查看OpenClaw是否提供了类似的trace或session导出功能。4.3 常见问题排查清单结合源码分析和实际经验以下是一些典型问题及其排查思路问题现象可能原因排查方向结合源码Agent陷入死循环不断重复相同或无效动作。1. LLM的思考未能基于历史观察产生有效进展。2. 工具返回的观察结果未能被正确解析或纳入状态。3. 终止条件_should_stop逻辑有误永远无法满足。1. 检查DEBUG日志看每一轮的Thought是否在有效分析Observation。2. 检查state.history确认Observation是否被正确追加。3. 检查_should_stop方法的实现看判断任务完成的条件是否过于严格或永远无法触发。LLM总是调用错误的工具或参数格式总是不对。1. 工具描述description不够清晰误导了LLM。2. 提示词模板中工具描述的排列或格式有问题。3. 输出解析器OutputParser的正则表达式或逻辑有缺陷无法正确提取信息。1. 优化工具描述明确使用场景和参数格式。2. 审查构建提示词的代码确保工具列表被正确格式化插入。3. 测试输出解析器用一些边界案例如LLM回复包含额外说明验证其鲁棒性。工具执行成功但Agent似乎“忽略”了结果。1. 工具返回的结果结构过于复杂或非结构化LLM难以理解。2. 观察结果Observation在放入历史时被过度截断或总结丢失了关键信息。1. 让工具返回的结果尽可能简洁、结构化优先使用JSON。2. 检查state更新逻辑看是否有对Observation进行预处理如截断的代码调整其策略。Agent执行速度很慢。1. LLM API调用延迟高。2. 某个工具执行耗时过长如网络请求。3. 循环步数过多。1. 考虑使用更快的LLM或配置合理的超时、重试。2. 为慢速工具添加异步调用或缓存机制。3. 优化Agent的规划能力通过更好的提示工程减少不必要的步骤。5. 超越基础循环高级模式与扩展思考5.1 多Agent协作与子任务分解复杂的任务往往需要分解。在OpenClaw的架构中你可能会发现它支持将一个Agent本身也注册为一个“工具”。这意味着一个主AgentOrchestrator可以将子任务分发给另一个专门的AgentWorker去完成。这体现在执行循环中就是_act阶段可能调用的是一个“子Agent工具”这个工具会启动另一个独立的执行循环并将最终结果返回给主Agent。在源码中这通常通过一个SubAgentTool类来实现它内部封装了另一个Agent实例的启动和运行逻辑。这种模式非常适合构建分层、模块化的Agent系统。5.2 外部记忆与知识库集成基础的执行循环依赖state.history作为短期记忆。但对于需要大量背景知识或跨会话记忆的任务就需要引入外部记忆体。OpenClaw可能通过Memory接口或类似抽象来支持。例如在_reason阶段之前可以有一个_retrieve步骤根据当前状态从向量数据库中检索相关的知识片段并将其作为上下文注入到给LLM的提示词中。在_act阶段之后可能还有一个_store步骤将重要的执行结果存储到长期记忆中。在源码中寻找与VectorStoreRetriever、Memory等相关的组件和它们在主循环中的调用点。5.3 评估与持续改进Agent的“元思考”一个真正强大的Agent应该具备评估自身表现并改进的能力。这超出了单次执行循环涉及更上层的“元”管理。虽然OpenClaw的核心循环可能不直接包含这点但其设计可能为这种扩展留出了空间。例如你可以设计一个外部的Evaluator在Agent运行结束后根据任务目标、执行步骤和结果生成一个评分或反馈。这个反馈可以被用来微调提示词、调整工具配置甚至作为训练数据来优化LLM本身。在架构上这要求Agent的运行过程轨迹能被完整地记录和导出以便进行分析。从OpenClaw的源码出发我们清晰地看到了一个AI Agent“思考”的骨架一个以状态为中心、循环推进、通过工具与环境交互的自动机。理解这个执行循环和工具调用机制是构建和调试任何AI Agent的基石。它不仅仅是代码更是一套关于如何让大语言模型具备目标导向行动能力的工程范式。当你再看到“AI Agent”这个词时希望你的脑海里能浮现出这个清晰的、由代码构成的循环图景。