从零实现ReAct Agent：230行代码构建AI智能体核心循环

1. 项目概述：一个极简的ReAct Agent实现

如果你对AI Agent（智能体）感兴趣，想亲手实现一个能“思考-行动”的循环，但又觉得像LangChain、AutoGen这类框架过于庞大、依赖复杂，那么这个项目就是为你准备的。Wscats/miniclaw，或者说我更习惯叫它“Mini OpenClaw”，是一个用纯JavaScript写成的、零外部依赖的ReAct Agent引擎。它的全部代码就一个文件，230行，却能完整地实现一个可以自主调用工具（比如读文件、执行命令）来完成任务的智能助手。

简单来说，ReAct（Reasoning + Acting）是一种让大语言模型（LLM）像人一样工作的模式：先思考（Reasoning），判断是否需要使用工具，如果需要就行动（Acting），使用工具，然后把工具的结果作为新的信息，再继续思考，如此循环，直到解决问题。这个模式听起来高级，但实现它的核心逻辑其实并不复杂。Mini OpenClaw的魅力就在于，它用最直白、最精简的代码，把这个核心逻辑清晰地呈现了出来，没有任何多余的包装，非常适合学习和理解ReAct Agent的底层工作原理。

我自己在研究和教学Agent开发时，经常需要向学生解释ReAct的运作机制。用那些成熟框架的例子，学生往往被海量的抽象层和配置项淹没，反而抓不住重点。而Mini OpenClaw就像一张清晰的解剖图，把Agent的“骨骼”和“肌肉”都暴露在你面前。它不依赖任何npm包，运行它只需要Node.js和一个能调用大模型的命令行工具（CodeBuddy CLI）。对于开发者，尤其是前端或Node.js背景的开发者来说，这降低了上手门槛，让你能专注于理解Agent的思维流程本身。

2. 核心架构与设计哲学

2.1 单文件架构拆解

整个项目的核心就是mini-openclaw.mjs这一个文件。这种极简设计并非偷懒，而是一种强烈的教学和理念声明：一个具备基础工具调用能力的Agent，其核心循环可以如此紧凑。文件内部清晰地划分为四个逻辑部分，我们可以逐一拆解：

1. 工具定义：这是Agent的“手”和“眼睛”。项目内置了四个最基础但极其实用的工具：read_file（读文件）、write_file（写文件）、list_dir（列目录）和run_command（执行Shell命令）。每个工具都是一个简单的异步函数，接收参数，执行操作，返回结果或错误。例如，run_command就是利用Node.js的child_process.spawn来执行命令并捕获输出。这种设计让你一眼就能看懂工具是如何被封装和调用的。
2. LLM调用层：这是Agent的“大脑”。项目没有使用常见的HTTP API客户端（如openai包），而是选择通过child_process.spawn直接调用一个名为CodeBuddy的命令行工具。这样做的好处是零依赖，你不需要安装任何额外的HTTP客户端库（如axios,node-fetch）。它通过命令行参数-p（表示prompt模式）和--output-format json来告诉CodeBuddy：“我给你一段提示词，你以JSON格式把回复吐出来”。这种设计巧妙地绕开了网络请求的复杂性，将LLM交互简化为一个进程间通信问题。
3. ReAct循环引擎：这是项目的“心脏”，也是代码最精妙的部分。它维护着一个不断增长的“对话历史”字符串。每次循环，它都把当前的对话历史拼接到预设的系统提示词后面，形成完整的prompt，发送给LLM。然后，它用正则表达式/<tool_call>(.*?)<\/tool_call>/s去“监听”LLM的回复。如果匹配到了<tool_call>标签，就解析里面的JSON，调用对应的工具函数，把工具执行的结果以[工具结果]: ...的格式追加到对话历史中，然后开启下一轮循环。如果没匹配到标签，说明LLM认为不需要或无法使用工具，已经给出了最终答案，循环结束，将答案输出给用户。
4. 交互式REPL：这是Agent的“嘴巴”和“耳朵”。利用Node.js的readline模块，它构建了一个简单的命令行交互界面。你可以持续输入问题，Agent会保持对话历史（记忆），直到你输入/clear清空，或者exit退出。这为测试和演示提供了极大的便利。

注意：这种基于正则表达式解析工具调用的方式，虽然简单直观，但对LLM输出的格式稳定性有较高要求。它要求模型必须严格遵循<tool_call>{...}</tool_call>的格式。在实际使用中，如果模型“不听话”，输出了多余的解释或格式错误，循环就会中断。这是极简设计在健壮性上做出的权衡。

2.2 关键设计决策背后的考量

为什么选择这些看似“非主流”的实现方式？这背后有很实际的考量：

• 文本标签 vs. Function Calling：OpenAI的Function Calling是一种更结构化、更可靠的方案，但它绑定在特定的API协议里。使用<tool_call>这种自定义的文本标签，使得这个Agent引擎与模型提供商解耦。理论上，任何能遵循简单文本指令的LLM都可以驱动它，兼容性更好。这也更贴近ReAct论文中描述的“Thought-Action-Observation”的文本交互模式。
• CLI调用 vs. HTTP SDK：使用CLI工具（CodeBuddy）而不是直接调用HTTP API，最大优势就是依赖最小化。你只需要在系统层面安装一个可执行程序，项目本身没有任何package.json和node_modules。这对于分享、演示和快速启动来说非常友好。缺点是，你被绑定在了CodeBuddy这个特定的CLI工具及其支持的模型上。
• 纯文本对话历史：将所有交互（用户输入、助手回复、工具结果）都用特定前缀（User:，Assistant:，[工具结果]:）拼接成一个长字符串，是最简单、最兼容的上下文管理方式。它不需要维护复杂的状态对象，直接将其作为prompt的一部分喂给LLM，LLM天然就能理解这种对话格式。缺点是，当对话轮数非常多时，可能会触及模型的上下文长度限制，且历史无法被结构化查询或修改。

3. 环境准备与快速启动

3.1 前置条件检查

要运行Mini OpenClaw，你需要准备两样东西，它们都不复杂：

1. Node.js运行环境：版本需要大于等于18。这是因为代码中使用了较新的ES模块语法（.mjs后缀）和一些稳定的API。你可以在终端输入node --version来检查。如果没有安装，去Node.js官网下载LTS版本安装即可。
2. CodeBuddy CLI及其API Key：这是本项目与LLM通信的桥梁。
   • 安装CLI：在终端运行npm install -g @tencent-ai/codebuddy-code。这是一个腾讯云推出的命令行AI编程工具，安装后你可以在任何地方使用codebuddy命令。
   • 获取API Key：你需要一个以ck_开头的API Key。通常你需要注册腾讯云相关服务来获取。请务必妥善保管你的Key，不要泄露。

3.2 一步到位的启动流程

准备好了环境，启动它只需要三步：

# 1. 获取代码。你可以直接下载，或者用git克隆（推荐，方便后续更新）。 git clone https://github.com/wscats/enoclaw.git cd enoclaw # 2. 设置环境变量。将你的CodeBuddy API Key设置到当前终端会话中。 # 在Linux/macOS上： export CODEBUDDY_API_KEY=ck_your_actual_key_here # 在Windows PowerShell上： $env:CODEBUDDY_API_KEY="ck_your_actual_key_here" # 3. 运行！ node mini-openclaw.mjs

如果一切顺利，你会看到一个简洁的ASCII艺术logo和欢迎界面，提示你模型已加载（默认是deepseek-v3-2-volc），工具已就绪，光标在You>后面等待你的输入。

3.3 模型选择与配置

默认使用的是deepseek-v3-2-volc模型。如果你希望尝试其他模型，可以在启动前通过环境变量指定：

# 尝试混元2.0思考模型 MODEL=hunyuan-2.0-thinking node mini-openclaw.mjs # 或者GLM-5.0 MODEL=glm-5.0 node mini-openclaw.mjs

可用的模型取决于你的CodeBuddy CLI版本和授权，常见的有deepseek-v3-2-volc,hunyuan-2.0-thinking,glm-5.0,glm-4.7,minimax-m2.5,kimi-k2.5等。不同模型在工具调用的格式遵循能力、推理深度和速度上会有差异，你可以根据任务需求进行选择。

实操心得：在第一次运行前，建议先单独测试一下CodeBuddy CLI是否工作。在终端输入codebuddy -p "Hello"，看看是否能正常返回AI的回复。这能帮你快速定位问题是出在Key配置、网络还是CLI安装上，避免在运行Agent时一头雾水。

4. 核心工作流程深度解析

理解Mini OpenClaw如何工作，最好的方式就是跟踪一次完整的工具调用。我们以“请列出当前目录下所有以.js结尾的文件”这个任务为例，拆解每一步。

4.1 初始状态与用户输入

启动Agent后，其内部维护的conversationHistory是一个空字符串。系统提示词（包含工具定义和调用规则）被预先定义好。当你输入问题后：

You> 请列出当前目录下所有以.js结尾的文件

程序会将你的输入，加上User:前缀，追加到对话历史中。此时，准备发送给LLM的完整prompt是：

[系统提示词]...（此处是详细的工具描述和调用规则）... User: 请列出当前目录下所有以.js结尾的文件

4.2 第一次LLM调用与思考

这个完整的prompt通过codebuddy -p --output-format json命令发送给大模型。模型收到后，会进行“思考”（Reasoning）。它分析系统提示词，知道自己有list_dir这个工具可以列出目录内容。它也读到了用户的请求是“列出.js文件”。一个合理的推理路径是：要列出特定类型的文件，我需要先知道当前目录下有什么。因此，它决定调用list_dir工具。

根据系统提示词中规定的格式，它必须在回复中只包含工具调用标签。于是，它生成如下回复：

{ "content": "<tool_call>{\"name\":\"list_dir\",\"args\":{\"path\":\".\"}}</tool_call>" }

CodeBuddy CLI会把这个JSON对象输出到标准输出。

4.3 工具调用与结果观察

Mini OpenClaw的主循环函数（比如叫react）接收到这个JSON回复后，会提取content字段。然后用正则表达式去匹配<tool_call>标签。成功匹配后，解析出里面的JSON：{"name":"list_dir","args":{"path":"."}}。

接着，它在预定义的工具字典里查找list_dir函数，并以{"path":"."}为参数调用它。list_dir函数内部执行了Node.js的fs.readdir操作，读取当前目录（.），并区分文件和文件夹。假设当前目录下有mini-openclaw.mjs,test.js,README.md和一个node_modules文件夹。

工具执行成功，返回一个结果字符串，例如：

文件: mini-openclaw.mjs, test.js 目录: node_modules

程序将这个结果以[工具结果]: 文件: mini-openclaw.mjs, test.js\n目录: node_modules的格式，追加到对话历史中。此时对话历史变为：

User: 请列出当前目录下所有以.js结尾的文件 [工具结果]: 文件: mini-openclaw.mjs, test.js 目录: node_modules

4.4 第二次LLM调用与最终回答

由于检测到了工具调用，循环继续。程序将更新后的对话历史再次拼接到系统提示词后，形成新的prompt，发送给LLM。

这次，LLM看到的上下文是：用户问了.js文件，然后工具列出了所有内容。它需要进行第二次“思考”：从工具结果中，筛选出以.js结尾的文件。它发现test.js符合要求，而mini-openclaw.mjs虽然也是JavaScript模块，但后缀是.mjs，严格来说不符合用户“.js”的要求（除非用户意图包含.mjs，这取决于模型的判断）。

这次，它判断不需要再调用工具，因为信息已经足够。于是它生成一个自然语言回复：

{ "content": "根据列出的目录内容，当前目录下以.js结尾的文件是：test.js。" }

程序没有检测到<tool_call>标签，因此判定循环结束。它将content字段中的文本输出到终端，作为Assistant的最终回答：

🤖 Assistant: 根据列出的目录内容，当前目录下以.js结尾的文件是：test.js。

至此，一个完整的“思考（需要list_dir）→ 行动（执行list_dir）→ 观察（得到文件列表）→ 再思考（筛选并回答）”的ReAct循环完成。

4.5 循环终止与防呆设计

循环不会无限进行下去。代码中设置了一个最大迭代次数（比如15次）。如果LLM在15轮内还在不停地请求调用工具，却没有给出最终答案，循环会被强制终止，并提示“达到最大迭代次数”。这是一种重要的防呆机制，防止模型陷入“工具调用-结果观察-再次调用同一工具”的死循环。

此外，系统提示词里有一条重要规则：“如果对话历史中已有 [工具结果] 且与当前问题相关，禁止再调用同一工具，直接根据结果回答”。这条规则是“教”模型学会利用历史，避免重复劳动。但在实际测试中，模型并不总是严格遵守，所以最大迭代次数的兜底措施是必要的。

5. 内置工具详解与扩展指南

5.1 四大基础工具实战

Mini OpenClaw内置的四个工具，覆盖了本地文件操作和系统交互的基本面。理解它们的实现和边界很重要。

1. read_file(path)：

   • 作用：读取指定路径的文本文件内容。
   • 实现：使用fs.readFile的Promise版本，编码为utf-8。
   • 注意：它只能读文本文件。如果尝试读取二进制文件（如图片），会得到乱码。路径可以是相对路径（如./config.json）或绝对路径。如果文件不存在或没有读取权限，工具会返回错误信息，这个错误信息也会被如实追加到对话历史中，LLM需要能理解并处理这个错误。

2. write_file(path, content)：

   • 作用：将文本内容写入指定路径的文件。如果文件已存在，会覆盖；如果不存在，会创建（前提是目录存在且有写入权限）。
   • 实现：使用fs.writeFile的Promise版本。
   • 注意：这是一个有风险的工具，因为它会直接覆盖磁盘文件。在更复杂的Agent系统中，通常会对这种写操作进行确认或沙盒化。在这里，它体现了极简设计的“信任”原则——信任LLM和用户的指令。切勿在重要项目目录或生产环境中随意测试此工具。

3. list_dir(path)：

   • 作用：列出指定目录下的条目，并区分文件和文件夹。
   • 实现：使用fs.readdir获取所有条目名，然后对每个条目使用fs.stat判断是文件还是目录。
   • 注意：参数path默认为当前目录（.）。它只做浅层列出，不会递归遍历子目录。返回的结果是格式化的字符串，便于LLM阅读。

4. run_command(command)：

   • 作用：在系统Shell中执行一条命令，并返回其标准输出（stdout）和标准错误（stderr）。
   • 实现：使用child_process.spawn，并监听stdout和stderr流来收集输出。
   • 注意：这是威力最大也最危险的工具。通过它，Agent可以执行任何Shell命令。这意味着它理论上可以安装软件、删除文件、重启服务等。绝对不要在不受信任的环境或拥有高权限的账户下运行此类Agent。在Mini OpenClaw的教学场景中，它展示了可能性，但也必须强调其安全隐患。

5.2 如何自定义和扩展工具

扩展工具集是让这个迷你Agent变得更强大的关键。假设我们想添加一个http_get工具，用于获取网页内容。

步骤非常简单，只需要修改mini-openclaw.mjs文件中的两个部分：

第一步：在“工具定义”部分添加新的工具函数。

// ... 其他工具定义之后 async function http_get(args) { const { url } = args; if (!url) { return '错误：缺少参数 url'; } try { // 注意：为了保持零依赖，我们使用Node.js原生的https/http模块 // 这里以https为例 const https = require('https'); return new Promise((resolve, reject) => { const req = https.get(url, (res) => { let data = ''; res.on('data', chunk => data += chunk); res.on('end', () => { // 简单返回前1000个字符，避免上下文过长 resolve(`请求成功（状态码：${res.statusCode}）:\n${data.substring(0, 1000)}`); }); }); req.on('error', (err) => { resolve(`请求失败：${err.message}`); }); req.setTimeout(5000, () => { req.destroy(); resolve('请求超时'); }); }); } catch (error) { return `工具内部错误：${error.message}`; } } // 将新工具添加到 tools 对象中 const tools = { read_file, write_file, list_dir, run_command, http_get, // 添加这一行 };

第二步：在系统提示词中更新工具描述。

找到定义systemPrompt的地方，在工具列表中添加对新工具的描述：

你是一个智能助手，拥有以下工具： - read_file: 读取文件内容... - ... - http_get: 发起HTTP GET请求获取网页内容 参数: {"url":"string: 目标网址"}

第三步：重启Agent，即可使用。

现在，你可以问它：“用http_get工具获取一下百度首页的标题”。LLM在思考后，就会生成<tool_call>{"name":"http_get","args":{"url":"https://www.baidu.com"}}</tool_call>，然后执行你刚定义的函数。

扩展技巧：工具函数的返回值最好是清晰的文本字符串，方便LLM理解。对于复杂数据（如JSON），可以将其JSON.stringify后返回。工具函数内部要做好错误处理，并将错误信息以自然语言形式返回，这样LLM才能知道发生了什么并调整策略。

6. 常见问题与排查技巧实录

在实际运行和实验过程中，你可能会遇到一些典型问题。下面是我踩过的一些坑和解决方法。

6.1 启动与连接问题

6.2 工具调用与逻辑问题

6.3 性能与优化思考

• 速度慢：每次调用LLM都需要启动一个CodeBuddy CLI进程，进程创建和模型加载都有开销。这对于快速交互体验有影响。但这在教学中不是大问题，它让你更清晰地感知到每一次“思考-行动”的回合。
• 上下文长度：对话历史以纯文本形式不断增长，如果进行非常长的多轮对话，最终可能会超过模型的上下文窗口限制，导致模型“失忆”。在生产系统中，需要对历史进行摘要、裁剪或使用向量数据库。但在这个迷你版中，这提醒我们“上下文管理”是Agent设计中的一个重要课题。
• 工具可靠性：文件读写和命令执行没有沙盒保护。一个“聪明”的LLM如果被恶意提示，可能会执行危险操作。因此，这个项目绝对只适合在安全的、隔离的开发环境中用于学习和实验。

7. 从教学工具到生产原型的思考

Mini OpenClaw作为一个教学工具，无疑是成功的。它用200多行代码揭示了ReAct Agent的本质。但如果我们想把它变成一个更可靠、更强大的原型，甚至用于轻量级生产，有哪些方向可以探索呢？这里分享一些我个人的实践和思考。

1. 增强提示词（Prompt）的鲁棒性目前的系统提示词比较简单。我们可以让它更健壮：

• 加入少样本示例（Few-shot Examples）：在提示词中直接给出几个正确调用工具和直接回答的例子。这能极大地提高模型输出格式的准确性。
• 结构化输出要求：除了要求工具调用用标签包裹，还可以要求最终答案也用一个特定的标签包裹，如<final_answer>...</final_answer>，这样程序能更精确地判断循环何时结束。
• 分步骤思考（Chain-of-Thought）：鼓励模型在调用工具前，先在回复中输出它的“思考”过程（可以用<thought>...</thought>标签），这不仅能提升任务完成的准确性，也让我们更容易调试Agent的决策逻辑。

2. 改进工具调用与执行

• 参数验证与安全沙盒：在工具函数被调用前，对传入的参数进行类型和范围校验。对于run_command，可以建立一个允许列表（Allow List），只允许执行少数几个安全的命令（如ls,pwd,cat（限制路径）等），或者在一个 Docker 容器或临时目录中执行命令。
• 异步与并行工具调用：目前的循环是严格串行的：一次思考，调用一个工具，等待结果，再思考。一些复杂的任务可能需要并行调用多个工具（比如同时查询多个API）。可以扩展协议，让模型能在一个回复中指定多个<tool_call>，然后由Agent并行执行。

3. 升级通信层

• 替换CLI为HTTP客户端：虽然CLI实现了零依赖，但HTTP客户端（如fetch,axios）能提供更稳定的连接、更灵活的配置（超时、重试）和更广泛的模型支持（任何提供OpenAI兼容API的模型）。你可以写一个简单的callLLM函数来替换掉spawnCodeBuddy的部分，这样就能轻松接入GPT、Claude、国产大模型等各种API。
• 支持流式输出：目前是等待LLM生成完整回复后再处理。可以改为流式（Streaming）接收，让模型一边“思考”一边输出，用户能更快地看到部分结果，体验更好。

4. 引入记忆与状态管理

• 短期记忆摘要：当对话历史过长时，可以触发一个摘要过程：将旧的对话历史发送给LLM，让它生成一段简短的摘要，然后用摘要替换掉旧的历史，释放上下文窗口。
• 长期记忆向量库：对于需要跨会话记忆的知识，可以将重要的工具执行结果或对话结论，通过嵌入模型（Embedding）转化为向量，存入本地的轻量级向量数据库（如chroma的本地模式）。当遇到相关问题时，先进行向量检索，将相关内容作为上下文注入。

实现这些改进中的任何一项，都会让代码量增长，背离“极简”的初衷。但这正是学习的路径：先通过Mini OpenClaw理解核心原理，然后根据实际需求，亲手为它添砖加瓦。最终，你可能会自己搭建出一个更适合你特定场景的Agent框架。这个从简到繁、从理解到创造的过程，才是这个项目带给开发者最大的价值。