1. OpenCode Agent 本地代理为什么会卡住setTimeout 超时与重试的真实场景如果你在用 OpenCode 这类 Agent 工具做本地开发大概率遇到过这种情况终端里 Agent 转了半天没反应日志停在某一行不动CPU 和内存看着也不高但就是不出结果。我试过在 Node.js 环境下跑本地代理转发请求QPS 一上来或者上游接口偶发抽风整个链路就会挂起。核心原因往往不是模型慢而是 HTTP 客户端请求没有设置合理的超时边界。OpenCode Agent 的工作模式是客户端发起请求 → 本地代理接收 → 代理转发到目标 endpoint → 等待响应 → 回传结果。这个链路里proxyReq是一个 Node.js 原生http.ClientRequest对象。如果目标 endpoint 迟迟不返回或者 TCP 连接建立了但响应头一直不来proxyReq就会一直挂在事件循环里。接收回调不执行闭包引用的logEntry就无法被 GC 回收内存会随着挂起请求的数量线性累积。这就是为什么需要setTimeout。它给整个请求生命周期设一个上限DNS 查询、TCP 连接、TLS 握手、发送请求头/体、等待响应头/体全部算在内。一旦超时触发timeout事件你可以在回调里决定是重试还是直接销毁连接。不设置的话一个卡住的请求可能挂几分钟甚至更久高并发下就是灾难。这篇内容聚焦三件事第一把 OpenCode Agent 的本地代理 endpoint 切到 TaoToken 统一 Key 通道让请求链路可观测第二给出可复制的setTimeout参数配置和重试策略代码第三通过日志和状态码验证超时行为是否真正生效。适合正在用 OpenCode、Cline、Claude Code 这类工具做 Agent 开发并且自己维护本地代理层的同学。2. TaoToken 统一 Key 通道前置准备endpoint 切换与模型 ID 对齐在改超时配置之前先把请求目标固定下来。本地代理最容易出问题的地方就是 endpoint 散落在多个配置文件里改了一处漏了另一处最后请求打到哪个上游都不清楚。TaoToken 提供统一 Key 和 API 通道把模型调用收敛到一个入口这样超时和重试的观测才有意义。你需要准备三样东西Base URL、API Key、Model ID。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数。API Key 在控制台的 API Keys 页面生成建议单独建一个给本地代理用的 Key方便按项目排查用量。Model ID 根据你实际调用的模型填写比如 Claude 系列或 GPT 系列的具体标识。拿到这三件套后先确认你的 OpenCode 或本地代理配置里请求地址指向 TaoToken。如果你用的是 Claude Code 类的配置通常在settings.json或环境变量里设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。如果是 Cline 或类似插件在 MCP 或 provider 配置里填 Base URL 和 Key。Codex 的话看auth.json里的字段。这里有个容易踩的坑Base URL 末尾不要多加/v1或/chat/completions具体路径由客户端 SDK 拼接。你只需要填到/api这一层。填错的话请求会 404但日志里可能只显示连接成功让你误以为链路通了。配置完成后先用一个最简单的 curl 验证 Key 是否有效curl -s -o /dev/null -w %{http_code} \ -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:your-model-id,messages:[{role:user,content:ping}],max_tokens:8}返回 200 说明 Key 和 endpoint 都对。返回 401 就是 Key 问题返回 404 就是路径拼错了。这一步过了再往下改代理层的超时逻辑否则你分不清是超时配置的问题还是鉴权的问题。另外提醒一点本地代理转发时请求头里的Authorization要透传或替换成 TaoToken 的 Key。如果你在代理层做了 Key 映射确保映射后的 Key 有对应模型的权限。模型 ID 也要和 TaoToken 支持的列表对齐写错模型名会返回 400 或 404而不是超时这两种错误的排查方向完全不同。3. 可复制的 setTimeout 与重试配置Node.js 代理层完整代码片段现在进入核心部分。假设你的本地代理用 Node.js 原生http或https模块转发请求下面是一段可以直接抄的配置。先看setTimeout的基本用法const http require(http); const https require(https); function forwardRequest(clientReq, clientRes, targetOptions, body) { const transport targetOptions.protocol https: ? https : http; const proxyReq transport.request(targetOptions, (proxyRes) { // 正常响应处理 clientRes.writeHead(proxyRes.statusCode, proxyRes.headers); proxyRes.pipe(clientRes); }); // 关键设置超时单位毫秒 proxyReq.setTimeout(15000, () { console.warn([proxy] timeout after 15000ms, destroying request); proxyReq.destroy(new Error(PROXY_TIMEOUT)); }); proxyReq.on(error, (err) { console.error([proxy] request error:, err.message); if (!clientRes.headersSent) { clientRes.writeHead(502, { Content-Type: application/json }); clientRes.end(JSON.stringify({ error: upstream_error, detail: err.message })); } }); proxyReq.write(body); proxyReq.end(); }这段代码里setTimeout(15000, callback)设置的是整个请求生命周期的超时。触发后必须手动destroy()否则连接会挂起。destroy传入 Error 对象会触发error事件方便你统一处理。接下来是重试策略。超时不一定意味着要放弃可能是上游偶发慢。但重试要有上限否则会放大下游压力。下面是一个带指数退避的重试封装const MAX_RETRIES 2; const BASE_DELAY 500; async function requestWithRetry(options, body, attempt 0) { return new Promise((resolve, reject) { const transport options.protocol https: ? https : http; const req transport.request(options, (res) { let data ; res.on(data, (chunk) { data chunk; }); res.on(end, () { if (res.statusCode 500 attempt MAX_RETRIES) { const delay BASE_DELAY * Math.pow(2, attempt); console.warn([retry] status ${res.statusCode}, retry in ${delay}ms); setTimeout(() { requestWithRetry(options, body, attempt 1).then(resolve).catch(reject); }, delay); } else { resolve({ statusCode: res.statusCode, body: data }); } }); }); req.setTimeout(15000, () { req.destroy(new Error(TIMEOUT)); }); req.on(error, (err) { if (attempt MAX_RETRIES err.message TIMEOUT) { const delay BASE_DELAY * Math.pow(2, attempt); console.warn([retry] timeout, retry in ${delay}ms); setTimeout(() { requestWithRetry(options, body, attempt 1).then(resolve).catch(reject); }, delay); } else { reject(err); } }); req.write(body); req.end(); }); }参数说明MAX_RETRIES 2表示最多重试两次加上首次请求共三次。BASE_DELAY 500是首次重试延迟第二次翻倍到 1000ms。setTimeout统一设 15000ms对于大多数模型调用够用。如果你的场景是长文本生成可以调到 30000ms但不要无限大否则失去保护意义。如果你用配置文件管理可以写成 JSON 形式方便不同环境切换{ proxy: { timeoutMs: 15000, maxRetries: 2, baseDelayMs: 500, retryOnStatus: [500, 502, 503, 504], retryOnError: [TIMEOUT, ECONNRESET, ECONNREFUSED] }, upstream: { baseUrl: https://taotoken.net/api, modelId: your-model-id } }这份配置里retryOnStatus只对 5xx 重试4xx 不重试因为 401 是 Key 问题重试没意义。retryOnError覆盖了超时和连接类错误。baseUrl和modelId和前面 TaoToken 的三件套对齐改一处即可全局生效。4. 验证请求链路日志、状态码与超时行为确认配置写完不代表生效必须验证。验证分三层链路通不通、超时触没触发、重试有没有执行。第一层链路验证。启动代理后发一个正常请求看日志里是否出现上游返回的 200。如果代理层打印了[proxy] request error且状态码是 401说明 Key 没透传对。如果是 404检查 Base URL 和模型 ID。这一步可以用前面那个 curl 命令对照curl 通了代理不通问题在代理的请求头或路径拼接。第二层超时验证。手动制造一个超时场景把setTimeout临时改成 1000ms然后请求一个响应较慢的模型或者在上游加一个延迟。观察日志是否打印[proxy] timeout after 1000ms以及客户端是否收到 502。如果日志没打印说明setTimeout没生效检查是不是在request之后才调用或者被其他中间件覆盖了。第三层重试验证。把上游 endpoint 临时改成一个返回 503 的地址观察日志是否出现[retry] status 503, retry in 500ms然后第二次retry in 1000ms。如果只重试了一次就停了检查MAX_RETRIES和attempt的边界条件。常见错误是attempt MAX_RETRIES写成了attempt MAX_RETRIES导致多一次重试。状态码对照表状态码含义是否重试排查方向200成功否链路正常401鉴权失败否检查 API Key 和 Authorization 头404路径或模型不存在否检查 Base URL 和 Model ID429限流是带退避降低并发或联系上游500/502/503/504上游错误是检查上游服务状态超时无响应连接挂起是检查 setTimeout 和网络日志建议加上请求 ID 和时间戳方便串联一次请求的完整生命周期const reqId Math.random().toString(36).slice(2, 10); console.log([${new Date().toISOString()}][${reqId}] proxy start, timeout15000ms);这样一次请求从开始到超时到重试都能用同一个reqId串起来。排查时直接 grep 这个 ID比翻整个日志快得多。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth实际跑起来报错集中在几个地方。下面按真实报错逐条对照。401 Unauthorized。最常见。原因通常是代理层没有正确透传Authorization头或者 TaoToken 的 Key 没有对应模型的权限。检查两点代理转发时headers里是否带了Authorization: Bearer keyKey 是否在控制台被禁用或额度耗尽。如果用的是 Claude Code 类配置确认ANTHROPIC_API_KEY环境变量在代理进程里可见而不是只在当前 shell 生效。local proxy failed。这个报错通常来自 OpenCode 或 Cline 客户端意思是本地代理进程没起来或者端口不通。检查代理监听的端口是否和客户端配置一致比如客户端写的是http://127.0.0.1:8080代理实际监听3000就会报这个。另外确认代理进程没有因为未捕获异常退出加一个process.on(uncaughtException)兜底。reading choices。这个报错出现在解析响应体时通常是上游返回的结构和客户端预期不一致。比如客户端期望choices[0].message.content但上游返回了错误对象{ error: ... }。排查时先把原始响应体打印出来看statusCode和body的实际内容。如果statusCode是 200 但body里没有choices说明模型 ID 或请求格式有问题。OAuth 相关报错。如果你用的是需要 OAuth 的客户端注意 OAuth token 和 API Key 是两套东西。TaoToken 的 API Key 走Authorization: Bearer不要和 OAuth 的access_token混用。如果客户端强制走 OAuth 流程检查是否可以在 provider 配置里切换到 API Key 模式。还有一个隐蔽的坑setTimeout触发后调用了destroy()但error事件里又尝试写响应头此时clientRes.headersSent可能已经是 true导致ERR_HTTP_HEADERS_SENT。解决办法是在写响应前统一判断headersSent或者把超时处理放在最外层确保只写一次响应。6. 把超时和重试固定下来从能跑到跑得稳超时和重试不是配一次就完事。模型调用有波动上游有维护窗口你的并发量也会变。建议把timeoutMs、maxRetries、baseDelayMs做成环境变量或配置中心的值不同环境用不同参数。本地开发可以宽松一点timeoutMs设 30000重试 3 次生产代理收紧到 15000重试 2 次避免雪崩。验证动作要常态化。每次改完配置跑一遍正常请求、超时请求、503 请求三个用例确认日志和状态码符合预期。把这三个用例写成脚本集成到你的启动检查里。这样下次换模型或换 endpoint不会因为漏改一处配置导致整条链路挂起。如果你还在用散落的 endpoint 和多个 Key建议先把请求收敛到 TaoToken 统一通道再叠加超时和重试。链路清晰了排查才有方向。需要生成 Key 或查看接入文档可以从 API Keys 页面和接入文档入手想先验证模型对话是否正常用模型对话页面发一条测试消息如果长期跑编码类 AgentCoding Plan 更适合持续调用场景。