1. 从一次工具调用超时说起Agent 运行时为什么绕不开 Node.js如果你最近在折腾 OpenClaw、Claude Code 这类工具调用型 Agent大概率遇到过一种很迷惑的现象模型明明已经把tool_use的 JSON 吐出来了本地却卡在“正在执行命令”不动日志里既没有报错也没有返回。我第一次碰到时以为是模型抽风后来把日志打到事件循环层面才发现问题根本不在模型而在运行时——Agent 的“思考—行动—观察”循环本质上是一个高并发异步事件系统选错运行时工具调用链就会在某个 await 上悄悄挂死。先把概念说清楚。OpenClaw 是一个以消息平台为入口的自主 AI 代理通过大语言模型执行任务核心是一个 WebSocket RPC 网关Claude Code 是 Anthropic 官方的终端编程 Agent专注文件读写、Shell 执行、Git 操作。两者定位不同但有一个共同点都用 Node.js 作为运行时都用 TypeScript 写核心逻辑。这不是巧合而是工具调用型 Agent 的工程必然。这篇文章面向三类人想搞懂 Agent 运行时选型的前端/全栈开发者、准备自己写最小 Agent 循环的工程师、以及被local proxy failed、reading choices这类报错卡住的人。我会从事件循环讲到工具调用链给出可复制的 Node 版本与依赖清单、最小 Agent 循环示例并演示用 TaoToken 统一 Key/API 通道跑通一次真实的工具调用与日志验证。读完你能自己判断为什么是 Node.js以及怎么把它跑起来。2. TaoToken 前置准备统一 Key 与 API 通道让 Agent 循环先跑通在写 Agent 循环之前得先解决一个现实问题工具调用型 Agent 每次循环都要请求模型如果 Key 管理混乱、Base URL 到处硬编码调试阶段会非常痛苦。我的做法是用 TaoToken 做统一的 API 通道一个 Key 管所有模型调用Agent 代码里只认一个环境变量。TaoToken 在这里的角色是模型 API 的统一入口官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置时直接用这个。你需要准备的东西不多一个 TaoToken 账号、一个 API Key、Node.js 18 以上版本。Key 在控制台创建地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建后复制保存后面写进.env文件。如果你还没决定用哪个模型可以先在模型对话页面试一下 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 确认工具调用能力正常再进代码。环境变量这样组织别把 Key 写进代码# .env TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api AGENT_MODELclaude-sonnet-4-6Node 版本建议 20 LTS 或 22 LTS原因是 Agent 循环里大量用到for await...of消费流式响应、AbortController做超时控制、原生fetch发请求这些在 18 以上都稳定20 以上体验最好。用 nvm 切换nvm install 20 nvm use 20 node -v # 应输出 v20.x.x依赖清单保持最小工具调用型 Agent 不需要重型框架npm init -y npm install anthropic-ai/sdk dotenv npm install -D typescript tsx types/node这里有个容易踩的坑anthropic-ai/sdk默认会去连 Anthropic 官方端点我们要通过baseURL参数把它指向 TaoToken 的 API 通道。SDK 支持自定义baseURL这是统一通道能生效的关键。初始化客户端时这样写import Anthropic from anthropic-ai/sdk import dotenv/config const client new Anthropic({ apiKey: process.env.TAOTOKEN_API_KEY!, baseURL: process.env.TAOTOKEN_BASE_URL!, // https://taotoken.net/api })如果你用的是 Claude Code 这类 CLI 工具配置方式不同走的是环境变量或 settings 文件。Claude Code 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 Base URL、Key、Model ID 三件套的完整写法。三件套缺一不可Base URL 决定请求打到哪Key 决定身份Model ID 决定用哪个模型。很多人只配了 Key 没改 Base URL结果请求还是发到默认端点报 401 或者连接失败。前置准备做到这一步就够了Node 20、两个依赖、一个.env、一个指向 TaoToken 的客户端实例。接下来写真正的 Agent 循环。3. 可复制配置最小 Agent 循环与工具调用链的完整代码这一节是全文的核心我会给出一个能直接跑的最小 Agent 循环包含工具定义、流式消费、工具执行、结果回填四个环节。代码基于anthropic-ai/sdk通过 TaoToken 通道请求模型。先看工具定义。工具调用型 Agent 的“工具”本质是一段 JSON Schema描述工具名、参数类型、必填项。模型看到这个 Schema 后会决定是否输出tool_use块。定义一个执行 Shell 命令的工具// tools.ts import { execSync } from node:child_process export const tools [ { name: bash, description: Execute a shell command and return stdout/stderr, input_schema: { type: object as const, properties: { command: { type: string, description: The shell command to execute, }, timeout: { type: number, description: Timeout in milliseconds, default 30000, }, }, required: [command], }, }, ] export function runTool(name: string, input: Recordstring, unknown) { if (name ! bash) throw new Error(Unknown tool: ${name}) const command String(input.command) const timeout Number(input.timeout ?? 30000) try { const stdout execSync(command, { encoding: utf-8, timeout }) return { ok: true, content: stdout } } catch (e: any) { return { ok: false, content: e.message } } }注意input_schema里的type: object as const这是 TypeScript 类型收窄的写法不加as const会被推断成string而不是字面量SDK 的类型检查会报错。这是我在实际项目里踩过的坑报错信息很隐晦只说类型不匹配。再看主循环。Agent 循环的结构是把用户消息和工具定义发给模型模型返回后检查stop_reason如果是tool_use就执行工具、把结果作为tool_result回填、继续下一轮如果是end_turn就输出最终文本、结束循环。// agent.ts import Anthropic from anthropic-ai/sdk import dotenv/config import { tools, runTool } from ./tools const client new Anthropic({ apiKey: process.env.TAOTOKEN_API_KEY!, baseURL: process.env.TAOTOKEN_BASE_URL!, }) export async function runAgent(userMessage: string) { const messages: Anthropic.MessageParam[] [ { role: user, content: userMessage }, ] let turn 0 while (turn 10) { turn console.log(\n--- turn ${turn} ---) const stream await client.messages.stream({ model: process.env.AGENT_MODEL!, max_tokens: 4096, tools, messages, }) // 流式消费实时打印模型输出 for await (const chunk of stream) { if ( chunk.type content_block_delta chunk.delta.type text_delta ) { process.stdout.write(chunk.delta.text) } } const response await stream.finalMessage() messages.push({ role: assistant, content: response.content }) if (response.stop_reason end_turn) { console.log(\n[agent] 任务完成) return } if (response.stop_reason tool_use) { const toolResults: Anthropic.ToolResultBlockParam[] [] for (const block of response.content) { if (block.type tool_use) { console.log(\n[tool] ${block.name}: ${JSON.stringify(block.input)}) const result runTool(block.name, block.input as Recordstring, unknown) console.log([tool result] ${result.content.slice(0, 200)}) toolResults.push({ type: tool_result, tool_use_id: block.id, content: result.content, is_error: !result.ok, }) } } messages.push({ role: user, content: toolResults }) } } console.log(\n[agent] 达到最大轮次停止) }入口文件// index.ts import { runAgent } from ./agent const task process.argv[2] ?? 列出当前目录下的文件并统计有多少个 .ts 文件 runAgent(task).catch(console.error)package.json里加一条脚本用 tsx 直接跑 TypeScript{ scripts: { agent: tsx index.ts } }这套配置的关键点有三个。第一client.messages.stream返回的是 AsyncIterable用for await...of消费这是 Node.js 原生支持的异步迭代协议Python 的 asyncio 要实现同样的效果得写不少样板。第二工具结果回填时必须带上tool_use_id模型靠这个 ID 把结果和之前的调用对应起来漏了会报错。第三循环要有最大轮次保护否则模型可能陷入无限工具调用。如果你用 Claude Code 做类似的事配置走的是另一套。Claude Code 的接入配置在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 核心还是 Base URL、Key、Model ID 三件套。Claude Code 的 Anthropic 兼容配置可以参考 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 里面说明了环境变量怎么设。4. 验证请求跑通一次工具调用并看日志确认链路代码写完跑一次看结果。执行npm run agent 列出当前目录下的文件并统计有多少个 .ts 文件预期输出会分几段。第一段是模型的思考文本可能是一句“我先看看目录结构”。第二段是工具调用日志--- turn 1 --- 我先查看当前目录的文件列表。 [tool] bash: {command:ls -la} [tool result] total 48 drwxr-xr-x 8 user staff 256 ... -rw-r--r-- 1 user staff 1234 agent.ts -rw-r--r-- 1 user staff 890 tools.ts ...第三段是模型拿到工具结果后的继续推理可能再调一次bash统计.ts文件--- turn 2 --- [tool] bash: {command:ls *.ts | wc -l} [tool result] 3第四段是最终回答当前目录下有 3 个 .ts 文件agent.ts、tools.ts、index.ts。 [agent] 任务完成看到这个输出说明整条链路通了请求经 TaoToken 通道到达模型模型返回tool_use本地执行工具结果回填模型继续推理直到end_turn。日志里turn的递增就是事件循环在驱动工具调用链每一轮都是一次异步等待加一次回调处理。如果你想验证模型本身是否正常可以先用模型对话页面发一条带工具调用的请求 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 确认返回里有tool_use块。这一步能快速区分是模型问题还是代码问题。再补一个验证点把AGENT_MODEL换成另一个支持工具调用的模型重跑同样的任务。如果都能跑通说明你的通道配置是模型无关的这对后续做多模型 Agent 很重要。TaoToken 的 API 端点 https://taotoken.net/api 是统一的换模型只改AGENT_MODEL一个变量。日志验证时重点看三样东西stop_reason是不是按tool_use→end_turn的顺序变化tool_use_id在回填时有没有对上流式输出的text_delta是不是逐字打印。这三样正常Agent 循环就是健康的。5. 本篇常见错排查401、local proxy failed、reading choices 怎么解跑 Agent 循环时报错集中在几个地方。我按实际遇到的频率排一下每个都给排查路径。401 未授权。最常见的原因是 Key 没读到或者 Base URL 没改。先确认.env文件在项目根目录且dotenv/config在文件顶部导入。然后打印一下客户端配置console.log(baseURL:, client.baseURL) console.log(key prefix:, process.env.TAOTOKEN_API_KEY?.slice(0, 6))如果baseURL显示的是 Anthropic 官方地址说明环境变量没生效检查.env里变量名有没有拼错。如果 Key 前缀不对去控制台重新复制 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。注意 Key 只在创建时完整显示一次丢了就重新建一个。local proxy failed。这个报错通常出现在你本地配了代理但代理进程没起来或者端口不对。Agent 循环里发请求走的是 Node 的fetch它会读HTTP_PROXY、HTTPS_PROXY环境变量。如果你之前为了别的用途设过这些变量现在代理没开请求就会失败。排查方法是临时清掉unset HTTP_PROXY HTTPS_PROXY ALL_PROXY npm run agent 测试如果清掉后正常说明是代理环境变量残留。另一种情况是公司网络要求走特定出口那就得把代理配好再跑别硬清。reading choices 报错。这个报错一般出现在流式响应解析阶段提示读取choices字段失败。原因是某些兼容层返回的响应结构和 SDK 预期不一致SDK 在解析流式 chunk 时找不到choices字段。排查方向确认baseURL指向的是 TaoToken 的 API 端点 https://taotoken.net/api 而不是某个中间层地址确认 SDK 版本是最新的老版本对非标准响应结构兼容性差。升级命令npm install anthropic-ai/sdklatest如果升级后还报把stream换成非流式的create试一次能跑通说明是流式解析的问题再针对性看 chunk 结构。OAuth 相关报错。如果你用 Claude Code 而不是自己写的循环可能会遇到 OAuth 登录失败。Claude Code 的认证方式和你自己写代码用 API Key 不同它默认走 OAuth 流程。用 TaoToken 通道时应该配置成 API Key 模式而不是 OAuth。具体配置看接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面区分了两种认证方式。配错模式会一直卡在登录环节。工具调用死循环。模型反复调用同一个工具不结束。原因是工具返回的结果让模型认为任务没完成。排查方法是看工具返回内容如果返回空字符串或者错误信息不明确模型会重试。给工具返回加上明确的状态比如{ ok: true, content: ... }错误时is_error: true并给出可读的错误信息。另外循环里加最大轮次保护我上面代码里设的是 10 轮。TypeScript 类型报错。input_schema的type字段报类型不匹配加as const。block.input报unknown类型用as Recordstring, unknown收窄。这些是 SDK 类型定义严格导致的不是逻辑问题。排查顺序建议先看 401 和 Base URL再看代理环境变量最后看流式解析。大部分问题在前两步就能定位。6. 语义一致 CTA把 Agent 循环接到你的真实项目里最小循环跑通后下一步是把它接到真实场景。如果你要做的是长期编码或 Agent 类项目建议用 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它适合需要持续调用、多轮工具执行的开发场景。如果你只是想先验证模型和通道用模型对话页面就够了 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。Key 管理在控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。回到开头那个问题为什么 OpenClaw、Claude Code 都选 Node.js。答案不在语言偏好而在工具调用链的工程特性。Agent 循环是一个持续的事件驱动系统每一轮都是异步等待模型响应、回调执行工具、回填结果再等待。Node.js 的事件循环和这个结构天然同构流式响应用for await...of直接消费多通道长连接用事件循环轻松支撑npm 生态里消息平台 SDK 覆盖最全。TypeScript 又是模型训练数据里占比最高的语言之一写工具 Schema 和插件系统时类型安全直接到位。你不需要从零学一套新东西。你写过的 Promise 链、用过的 EventEmitter、配过的 WebSocket就是 Agent 开发的技能树。把上面那 70 行循环跑起来改改工具定义接上你的真实任务剩下的就是工程化的事。