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

从一个常见痛点说起

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

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

Agent Loop 是一种源自强化学习中"感知-决策-行动"范式的工程模式。在传统的大模型对话中，交互是单轮或多轮的问答，模型不具备主动执行能力。而 Agent Loop 将模型置于一个持续运行的控制回路中，使其能够像一个自主代理人一样反复观察环境状态、做出判断并采取行动。这一概念在 2023 年随着 AutoGPT、BabyAGI 等项目的出现而被广泛讨论，但 Claude Code 的实现将其精简到了极致，证明了核心机制并不需要复杂的架构支撑。

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

智能体循环的七个步骤

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

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

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

这个七步循环与经典控制论中的"OODA Loop"（观察-定向-决策-行动）有异曲同工之处。不同的是，传统 OODA Loop 中的决策者是人类指挥官，而在 Agent Loop 中，决策者是大语言模型。模型的"观察"来自工具返回的结果，"决策"由其推理能力完成，"行动"则通过工具调用实现。

两个信号决定循环的进退

把七步翻译成代码，你会发现真正驱动循环的其实只有两个信号，它们都来自模型返回的 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 功能——模型在训练阶段就学会了在适当时机发出结构化的工具调用请求，而非仅仅输出描述性的文本。这与 OpenAI 的 Function Calling 机制理念相似，但在协议层面各有设计取舍。

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

这就像一个棋手，即使棋力再高，如果看不到对手的落子，也无法下出好棋。循环提供的不是智力，而是"视野"——让模型能够基于真实状态做出后续决策，而不是在想象中推演。

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

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

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

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

值得注意的是，messages 列表在这里承担了"记忆"的角色。每一轮工具调用的输入和输出都被完整保留在消息历史中，模型在下一轮决策时能够"回忆"之前做过什么、得到了什么结果。这种基于上下文窗口的短期记忆机制虽然简单，但在大多数任务场景下已经足够有效。当任务足够复杂、消息历史超出上下文窗口限制时，才需要引入外部记忆或摘要机制。

为什么一个 Bash 工具就够了

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

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

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

选择 Bash 作为唯一工具入口是一种 Unix 哲学的体现——"做一件事，把它做好"。在 Unix/Linux 系统中，几乎所有操作都可以通过 Shell 命令完成：文件操作（cat、echo、cp）、进程管理（ps、kill）、网络请求（curl）、文本处理（grep、sed、awk）等。这意味着一个能执行 Bash 命令的工具，理论上就等价于拥有操作系统级别的完整能力。这种设计避免了为每种操作定义独立工具接口的复杂性，也避免了工具数量膨胀导致模型在选择工具时产生困惑的问题——研究表明，当可用工具超过一定数量时，模型的工具选择准确率会明显下降。

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

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

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

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

工具权限管理（Tool Permission）是 Agent 系统从实验走向生产的关键安全机制。当 Agent 拥有执行 Shell 命令的能力时，它理论上可以删除文件、访问网络、修改系统配置，甚至执行恶意代码。因此在实际部署中，需要建立分级权限体系：哪些命令可以自动执行（如 ls、cat），哪些需要用户确认（如 rm、pip install），哪些完全禁止（如 sudo、curl | bash）。Claude Code 通过沙箱环境、命令白名单和用户确认弹窗来控制风险，这也是为什么实验演示中特意使用临时目录而非真实项目目录的原因。

很多人在初学智能体开发时，容易被各种框架和抽象概念淹没——LangChain 的 Agent Executor、AutoGen 的多代理通信、CrewAI 的角色定义——误以为智能体的"智能"来自复杂的架构。但真相恰恰相反：智能来自模型本身，而工程要做的，只是给它一个能持续获取反馈、持续行动的最小闭环。框架提供的是便利性和可扩展性，但如果你不理解底层的循环机制，再多的框架也只是黑箱。

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

核心要点