Claude Code内核解密：30行代码实现智能体循环

从一个常见痛点说起

你是否遇到过这样的场景：让大模型帮你读取目录、修改文件、运行脚本，它很快给出一条命令，然后就停住了。命令没有真的执行，结果也没有回到模型手里，你只能手动复制粘贴，再重新提问。每一个来回，你都在充当模型与真实世界之间的"中间层"。

这种体验的根源，在于模型缺少一个持续行动的机制。它有判断能力，却没有执行和获取反馈的通道。要解决这个问题，答案并不是去堆砌一段更长、更复杂的提示词，而是给模型一个最小的 Agent Loop（智能体循环）——让模型负责判断下一步，让宿主环境负责调用工具、执行动作、把结果送回来。

Agent Loop 是一种源自强化学习中"感知-决策-行动"范式的工程模式。在传统的大模型对话中，交互是单轮或多轮的问答，模型不具备主动执行能力。而 Agent Loop 将模型置于一个持续运行的控制回路中，使其能够像一个自主代理人一样反复观察环境状态、做出判断并采取行动。这一概念的理论基础可追溯到 1980 年代的 BDI（Belief-Desire-Intention）架构和强化学习中马尔可夫决策过程（MDP）的 agent-environment interaction loop。BDI 架构最早由 Michael Bratman 在哲学层面提出，后由 Anand Rao 和 Michael Georgeff 在 1990 年代形式化为软件代理的设计蓝图——代理维护对世界的信念（Belief）、持有欲望达成的目标（Desire）、并形成具体的行动意图（Intention）。这种"先想清楚要什么，再决定怎么做"的决策结构，与今天 LLM Agent 在每轮循环中"分析当前状态→确定下一步目标→选择工具执行"的模式高度对应。2023 年，随着 GPT-4 等大模型展现出强大的推理能力，研究者将传统 agent 架构与 LLM 结合，催生了 ReAct（Reasoning + Acting）范式——模型在每一步同时输出推理过程和行动指令。ReAct 由 Yao 等人在 2022 年的论文中正式提出，其核心洞察是：如果让模型在调用工具前先用自然语言"思考"（Thought），工具选择的准确率和任务完成率会显著提高。AutoGPT、BabyAGI 等项目正是这一范式的早期实践，而 Claude Code 的实现将其精简到了极致，证明了核心机制并不需要复杂的架构支撑。

第一步用户提出任务

这正是 Claude Code 内核的核心设计思路。令人惊讶的是，这个内核的最小实现，代码量不到 30 行。

智能体循环的七个步骤

要理解 Agent Loop，我们先把它拆解成七个清晰的步骤：

用户提出任务——把需求交给模型；
模型决定要调用工具——模型判断自己需要执行某个动作；
宿主执行工具——由外部程序真正运行命令；
工具结果回到消息列表——执行结果被追加进对话上下文；
模型读到结果后再次判断——基于真实反馈决定下一步；
如果还有动作就继续——循环重复上述路径；
模型发出 end turn——任务完成，循环退出。

整个智能体的本质，就是不断重复这条路径。它的关键在于：让模型看到真实世界的反馈，再决定下一步该怎么做。

这个七步循环与经典控制论中的"OODA Loop"（观察-定向-决策-行动）有异曲同工之处。OODA Loop 由美国空军战略家 John Boyd 在冷战时期提出，用于描述战斗飞行员的决策过程——快速观察战场态势、判断敌方意图、做出战术决策、执行机动动作，然后进入下一个循环。Boyd 通过对朝鲜战争中美军 F-86 与苏联 MiG-15 空战数据的分析发现，F-86 的压倒性胜率（10:1 的击落比）并非源于飞机性能优势，而是因为 F-86 的气泡座舱和液压操纵系统让飞行员能更快地观察和反应——换言之，更短的 OODA 循环。不同的是，传统 OODA Loop 中的决策者是人类指挥官，而在 Agent Loop 中，决策者是大语言模型。模型的"观察"来自工具返回的结果，"定向"对应模型结合上下文理解当前状态，"决策"由其推理能力完成，"行动"则通过工具调用实现。循环速度越快、反馈越准确，Agent 的表现就越好——这与 Boyd 的核心观点"谁的 OODA 循环更快，谁就能赢得空战"本质相通。在 Agent 语境下，"更快的循环"意味着更低的 API 延迟、更精准的工具输出解析、以及更少的冗余推理步骤。

两个信号决定循环的进退

把七步翻译成代码，你会发现真正驱动循环的其实只有两个信号，它们都来自模型返回的 stop_reason 字段：

当 stop_reason == tool_use 时，说明模型"举手"说：我要用工具。此时宿主执行工具、收集结果、追加消息，然后回到下一轮；
当 stop_reason 不是 tool_use 时，说明模型认为"我做完了"，循环随即退出。

stop_reason 是 Anthropic Claude API 响应中的一个关键字段，它指示模型停止生成的原因。常见的值包括：end_turn（模型自然结束回复）、max_tokens（达到 token 上限）、tool_use（模型请求调用工具）。这一设计源自 Anthropic 在 2024 年推出的 Tool Use 功能——模型在训练阶段就学会了在适当时机发出结构化的工具调用请求，而非仅仅输出描述性的文本。具体实现上，当开发者在 API 请求中定义了可用工具（包含工具名称、描述和参数的 JSON Schema）时，模型会在认为需要外部信息或执行操作时，生成一个特殊的 tool_use 内容块，其中包含工具 ID、工具名称和符合 Schema 约束的参数对象。这种能力并非简单的提示词工程，而是通过在训练数据中加入大量工具调用示例、并通过 RLHF 强化模型对"何时该调用工具"的判断来实现的。Anthropic 的设计允许模型在单次响应中混合输出自然语言文本和多个工具调用请求，这意味着模型可以先解释自己的思路，然后同时请求执行多个相关命令——例如先说"我需要检查这两个文件的内容"，然后同时发出两个 cat 命令的工具调用。这与 OpenAI 的 Function Calling 机制理念相似——两者都是让模型输出结构化的动作指令而非纯文本——但在协议层面各有设计取舍：OpenAI 使用 function_call 和后来的 tool_calls 字段，支持并行函数调用；Anthropic 则将工具调用嵌入到内容块数组中，与文本块并列存在，在消息结构上更加统一。

模型说我做完了，循环退出

这里有一个值得反复强调的认知：模型不是因为循环而变聪明的。循环本身不会提升模型的推理能力。但如果没有这个循环，模型就永远没有机会看到真实世界的反馈——它只能凭空猜测，无法验证，也无法迭代。循环的价值，在于把"判断"和"执行"连接成一个闭环。

这就像一个棋手，即使棋力再高，如果看不到对手的落子，也无法下出好棋。循环提供的不是智力，而是"视野"——让模型能够基于真实状态做出后续决策，而不是在想象中推演。这也解释了为什么同一个模型在有工具循环和没有工具循环时，表现差距巨大：不是能力变了，而是信息通路打开了。认知科学中有一个概念叫"具身认知"（Embodied Cognition），主张智能不仅仅存在于大脑中，更依赖于身体与环境的持续交互。Agent Loop 在某种意义上就是给 LLM 提供了一种"具身性"——通过工具调用，模型获得了感知环境和作用于环境的能力，从而将其内在的推理潜力释放到现实世界中。

最小实现：五步拆解代码逻辑

把上述逻辑落地为代码，工作原理可以拆成五步：

把用户问题放进 messages（消息列表）；
把消息和工具定义一起发送给模型；
追加模型的回答，检查它有没有请求工具；
找到 tool_use，运行对应工具（如 Bash），收集每个工具的结果；
把结果作为新消息追加，再回到第二步。

本质上，这就是一个 while True 循环加上工具调用。整段代码不到 30 行，就是最小可运行的 Agent 内核。它没有复杂的类层级、没有额外的规划框架，只有几个函数和一个统一的工具入口。

值得注意的是，messages 列表在这里承担了"记忆"的角色。每一轮工具调用的输入和输出都被完整保留在消息历史中，模型在下一轮决策时能够"回忆"之前做过什么、得到了什么结果。这种基于上下文窗口的短期记忆机制虽然简单，但在大多数任务场景下已经足够有效。以 Claude 3.5 Sonnet 的 200K token 上下文窗口为例，这足以容纳数十轮工具交互的完整记录——一次典型的工具调用（命令+输出）大约消耗 200-2000 个 token，意味着理论上可以支持 100-1000 轮交互而不丢失任何历史信息。然而在复杂的长时任务中——比如重构一个大型代码库——每次命令输出（编译错误日志、大文件内容、测试结果）都会消耗大量 token，消息历史可能迅速逼近上下文上限。此时需要引入外部记忆或摘要机制：常见策略包括消息截断（保留首尾、压缩中间）、用模型生成之前交互的摘要（将 20 轮交互压缩为一段 500 token 的摘要）、或将关键信息写入外部文件供后续检索（类似于人类做笔记）。更先进的方案包括向量数据库检索（RAG）——将历史交互编码为向量，在需要时按相关性检索——以及分层记忆系统，模仿人类的工作记忆与长期记忆分离机制。Claude Code 在实际实现中采用了智能截断策略，保留任务开头的用户指令和最近的交互记录，确保模型始终知道"最初的目标是什么"和"刚刚发生了什么"。

为什么一个 Bash 工具就够了

用一个安全的临时目录做实验

在实验中，我们先用一个安全的临时目录做验证：安装依赖、运行 Python SDK，然后输入三个提示词——创建 hello.py、列出当前目录的 Python 文件、查看当前 Git 分支。

观察的重点不是模型输出得多漂亮，而是要看清楚：它什么时候调用工具，什么时候结束。

文件、脚本、系统命令都可通过统一入口接入

深入 Claude Code 的设计，你会发现它为什么只靠一个 Bash 工具就够用。原因在于：文件读写、脚本执行、系统命令，都可以通过一个统一的入口接入。甚至"子代理"也可以通过递归创建进程的方式派生出来。这里没有额外的规划模块，模型完全根据工具返回的结果，自己决定下一步。

选择 Bash 作为唯一工具入口是一种 Unix 哲学的体现——"做一件事，把它做好"。在 Unix/Linux 系统中，几乎所有操作都可以通过 Shell 命令完成：文件操作（cat、echo、cp）、进程管理（ps、kill）、网络请求（curl）、文本处理（grep、sed、awk）、包管理（pip、npm）、版本控制（git）等。Unix 哲学由 Ken Thompson 和 Dennis Ritchie 在 1970 年代贝尔实验室开发 Unix 系统时确立，其核心原则包括："做一件事并做好"、"程序的输出应该能成为另一个程序的输入"、"尽早构建原型"。Shell 作为这些工具的胶合层（glue layer），通过管道（pipe）、重定向和脚本将简单命令组合成复杂操作。这意味着一个能执行 Bash 命令的工具，理论上就等价于拥有操作系统级别的完整能力——它不是一个工具，而是通往所有工具的入口。这种设计避免了为每种操作定义独立工具接口的复杂性，也避免了工具数量膨胀导致模型在选择工具时产生困惑的问题——研究表明，当可用工具超过 15-20 个时，模型的工具选择准确率会明显下降，因为它需要在过多选项中判断哪个最适合当前任务。Anthropic 自己的研究也指出，工具描述的清晰度和数量的精简对模型表现至关重要。

不过值得指出的是，单一 Bash 入口在生产环境中也有其代价。错误处理的粒度较粗——模型需要从 stderr 输出中自行判断错误类型，而不同命令的错误格式千差万别；安全边界较模糊——Bash 的能力范围过于宽泛，一条 rm -rf / 就可能造成灾难性后果。此外，某些操作通过结构化 API 实现会更可靠：比如文件编辑，直接用 echo 或 sed 修改文件容易出错（特殊字符转义、多行内容处理），而专用的文件编辑工具可以接受"在第 15 行后插入以下内容"这样的结构化指令，大幅降低出错概率。因此 Claude Code 在实际内部实现中还包含了专用的文件编辑工具（支持精确的行级编辑而非整文件重写）和搜索工具等，只是对外呈现的核心理念仍然是统一的命令执行入口。

这是最小实现的取舍哲学：少一点抽象，先让循环跑通。

一个工具加一个循环，就是一个最小 Agent

请记住这句话：一个工具 + 一个循环 = 一个最小 Agent。

这是整个智能体开发体系的地基。后面所有更复杂的能力——工具权限管理（tool permission）、更丰富的工具集、多智能体协作——都会在这个循环之上逐层叠加。理解了这个 30 行的内核，你就掌握了 Claude Code 乃至绝大多数 AI 智能体的运行本质。

工具权限管理（Tool Permission）是 Agent 系统从实验走向生产的关键安全机制。当 Agent 拥有执行 Shell 命令的能力时，它理论上可以删除文件、访问网络、修改系统配置，甚至执行恶意代码。这不是理论风险——早期的 AutoGPT 实验中就出现过 Agent 试图获取 root 权限或向外部服务器发送数据的案例；2023 年还有研究者演示了通过 prompt injection 让 Agent 执行未经授权操作的攻击路径。因此在实际部署中，需要建立分级权限体系：哪些命令可以自动执行（如 ls、cat、pwd——只读且无副作用的操作），哪些需要用户确认（如 rm、pip install、写入文件——有副作用但可控的操作），哪些完全禁止（如 sudo、curl | bash、访问 ~/.ssh 等敏感路径——风险过高的操作）。这种分级类似于 Android 和 iOS 的运行时权限模型：应用不是一次性获得所有权限，而是在需要时逐项请求，用户可以选择"允许一次"、"始终允许"或"拒绝"。Claude Code 通过沙箱环境、命令白名单和用户确认弹窗来控制风险，这也是为什么实验演示中特意使用临时目录而非真实项目目录的原因。更进一步，生产级 Agent 系统通常还会引入审计日志（记录每一条执行的命令和结果）、资源限制（CPU 时间、内存、网络带宽上限）和撤销机制（自动 Git commit 以便回滚），形成纵深防御体系。

很多人在初学智能体开发时，容易被各种框架和抽象概念淹没——LangChain 的 Agent Executor、AutoGen 的多代理通信、CrewAI 的角色定义——误以为智能体的"智能"来自复杂的架构。但真相恰恰相反：智能来自模型本身，而工程要做的，只是给它一个能持续获取反馈、持续行动的最小闭环。LangChain 的 AgentExecutor 本质上就是对这个 while 循环的封装，加上了工具路由（根据模型输出自动分发到对应工具函数）、输出解析（处理模型返回的各种格式）、错误重试（工具执行失败时自动重试或让模型换一种方式）等生产级功能；AutoGen（由微软研究院开发）引入了多代理对话的概念，让多个 Agent 在共享消息空间中协作——例如一个"程序员 Agent"负责写代码，一个"审查员 Agent"负责检查代码质量，它们通过消息传递讨论直到达成一致。每个 Agent 本身仍然运行自己的循环，但它们之间通过消息传递实现协调。CrewAI 则进一步将角色（Role）、目标（Goal）和背景故事（Backstory）等概念引入 Agent 定义，试图通过拟人化设计提升任务分工的合理性。框架提供的是便利性和可扩展性，但如果你不理解底层的循环机制，再多的框架也只是黑箱。知道何时该从零构建（快速验证核心假设、学习底层原理、或当框架引入的抽象反而增加复杂度时），何时该使用框架（处理工具选择歧义、执行超时、并发控制、可观测性、多模型兼容等生产问题时），是工程成熟度的体现。

下一节，我们将在这个循环基础上，为它接入更多真正有用的工具。

核心要点

Agent Loop 的本质是"感知-决策-行动"的持续循环，理论源自 BDI 架构和强化学习的 MDP 范式，工程实现只需一个 while 循环
驱动循环的核心信号是 stop_reason：tool_use 继续循环，其他值退出循环
循环不提升模型智力，但打开了信息通路——让模型基于真实反馈而非想象做决策
单一 Bash 工具入口体现 Unix 哲学，避免工具膨胀导致的选择困难，但生产环境需补充专用工具
messages 列表即短期记忆，上下文窗口是其天然边界，长时任务需引入截断或摘要策略
安全是 Agent 从实验到生产的必经之路：分级权限、沙箱隔离、审计日志缺一不可
框架是循环的封装而非替代——理解 30 行内核，才能驾驭任何框架