1. 为什么要在 OpenCode 里加一层本地代理如果你正在用 OpenCode 这类终端里的 Agent 工具写代码大概率遇到过几个很实际的问题想换模型要改一堆配置、想看请求到底发了什么只能靠猜、多个项目共用一套 Key 时权限和额度不好隔离。本地代理就是解决这些问题的中间层——它在你自己机器上起一个 HTTP 服务OpenCode 把请求发给它它再转发给真正的模型服务中间所有流量你都能看到、能改、能记日志。OpenCode 是一个跑在终端里的开源编码 Agent支持 Node.js 生态配置走opencode.json和config.toml。它本身能直连模型服务但直连意味着你没法在请求链路上做手脚。加一层本地代理之后请求链路变成OpenCode → 本地代理127.0.0.1:2048→ 统一 API 通道 → 模型服务。这条链路的好处是你可以在代理层统一注入鉴权头、统一记录 token 消耗、统一做失败重试而 OpenCode 那边只需要把 baseURL 指向本地端口就行。这篇面向用 Node.js/JavaScript 做 Agent 开发的读者交付一份可复制的config.toml骨架、TaoToken 统一 Key 的接入步骤以及本地代理请求链路和效果呈现的验证动作。你跟着做完能亲眼看到 OpenCode 发出的请求经过代理转发、拿到流式响应、在终端里逐字打印出来的完整过程。需要提前说清楚的是本地代理不是必须的。如果你只是临时用一下直连也能跑。但只要你开始做 Agent 开发、需要观察请求行为、需要多模型切换、需要把 Key 管理收敛到一处代理层的价值就出来了。下面从环境准备开始一步步搭起来。2. TaoToken 前置准备统一 Key 与 API 通道本地代理要转发请求就得有一个稳定的上游通道。这里用 TaoToken 作为统一入口它的作用是给你一个兼容 OpenAI 格式的 API 地址和一把 Key代理层把请求转发到这个地址即可。这样你换模型、换项目代理代码不用动只改配置里的模型名。先拿到访问凭证。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在里面创建 API Key。创建完记得复制保存Key 只显示一次。API 的基础地址是 https://taotoken.net/api 这个地址不加任何查询参数直接作为 baseURL 用。注意它和官网地址的区别官网带 UTM 参数用于来源统计API 地址是纯接口地址代理代码里填的是后者。拿到 Key 之后建议先单独验证一下通道是否通再往代理里接。验证用模型对话页面最直观 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 在里面选一个模型发一句话能正常返回就说明 Key 和通道没问题。这一步别跳过因为后面代理报错时你需要知道是通道问题还是代理代码问题。如果你打算长期用 OpenCode 做编码 Agent可以了解一下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它面向的就是这类持续编码场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。这几个地址后面配置时会反复用到先记下来。环境方面你需要 Node.js 18 以上版本因为代理代码里会用到较新的 HTTP 模块行为。检查一下node -v npm -v如果版本低于 18建议先升级。OpenCode 本身也依赖 Node 环境版本太老会出现各种奇怪的模块加载错误。3. 可复制的 config.toml 骨架与代理代码这一节是核心分两部分OpenCode 的配置文件和本地代理的 Node.js 实现。先给配置骨架再给代理代码最后说两者怎么对接。3.1 OpenCode 的 config.toml 骨架OpenCode 的模型配置走config.toml放在项目根目录或用户配置目录下。下面这份骨架你可以直接复制把api_key换成你自己的# config.toml # OpenCode 模型配置骨架指向本地代理 [provider.local_proxy] name Local Proxy # 关键baseURL 指向本地代理端口不是上游地址 base_url http://127.0.0.1:2048/v1 api_key sk-你的TaoToken密钥 [model.default] provider local_proxy name claude-sonnet-4-20250514 max_tokens 8192 temperature 0.7 [model.fast] provider local_proxy name gpt-4o-mini max_tokens 4096 temperature 0.3这里有个容易踩的点base_url填的是本地代理地址http://127.0.0.1:2048/v1不是 TaoToken 的地址。上游地址写在代理代码里。这样设计的原因是OpenCode 只认本地代理代理再去认上游职责分离。你换上游、换 Key只改代理OpenCode 配置不动。api_key这里填 TaoToken 的 Key代理会把它透传给上游。你也可以在代理里硬编码 Key然后这里随便填一个占位符但更推荐把 Key 放在 OpenCode 配置里代理只做透传这样 Key 不散落在代码中。3.2 本地代理的 Node.js 实现代理代码用原生http和https模块不引入额外依赖方便你直接跑。核心逻辑是监听本地 2048 端口收到/v1/chat/completions的 POST 请求后读取请求体构造转发请求到 TaoToken拿到响应后原样 pipe 回客户端。// proxy.js // OpenCode 本地代理转发到 TaoToken 统一通道 const http require(http); const https require(https); // 上游配置 const UPSTREAM_HOST taotoken.net; const UPSTREAM_PATH /api/v1/chat/completions; const UPSTREAM_PORT 443; const server http.createServer((req, res) { console.log([IN] ${req.method} ${req.url}); if (req.method POST req.url /v1/chat/completions) { let body ; req.on(data, chunk { body chunk; }); req.on(end, () { // 透传客户端带来的 Authorization const authHeader req.headers[authorization] || ; console.log([AUTH] ${authHeader.slice(0, 20)}...); console.log([BODY] ${body.length} bytes); const options { hostname: UPSTREAM_HOST, port: UPSTREAM_PORT, path: UPSTREAM_PATH, method: POST, headers: { Authorization: authHeader, Content-Type: application/json, Content-Length: Buffer.byteLength(body) } }; const proxyReq https.request(options, (proxyRes) { console.log([UPSTREAM] status${proxyRes.statusCode}); // 原样回传状态码和响应头 res.writeHead(proxyRes.statusCode, proxyRes.headers); // pipe 自动处理流式和非流式并自动 end proxyRes.pipe(res); }); proxyReq.on(error, (e) { console.error([ERROR], e.message); res.writeHead(502); res.end(Bad Gateway); }); proxyReq.write(body); proxyReq.end(); }); return; } res.writeHead(404); res.end(Not Found); }); server.listen(2048, 127.0.0.1, () { console.log(Proxy running on http://127.0.0.1:2048); });这段代码里有个值得展开的机制。https.request是同步返回一个请求对象的但整个 IO 是异步的。proxyReq.end()只是把请求发出去了并不代表请求完成。Node.js 的事件循环会持续监听网络事件当上游返回响应头时自动调用(proxyRes) {...}这个回调。即使外层函数已经 return回调依然能访问res变量这是闭包在起作用。proxyRes是回调触发时系统新建的对象不是你自己定义的变量。proxyRes.pipe(res)完成后引用自然解除连接关闭时res也会被清理不会有内存泄漏。这套非阻塞、事件驱动的模型正是 Node.js 能高效处理大量并发 AI 请求的原因。3.3 启动与对接先启动代理node proxy.js看到Proxy running on http://127.0.0.1:2048就说明起来了。这个终端保持开着日志会实时打印请求信息。再开一个终端进入你的项目目录确认config.toml已经按 3.1 配好然后启动 OpenCode。OpenCode 会读取配置里的base_url把请求发到本地 2048 端口。4. 验证请求链路与效果呈现配置搭好之后最关键的一步是验证请求真的走了代理并且能看到效果。这一节给你三个验证动作从简单到完整。4.1 用 curl 直接打代理先不经过 OpenCode直接用 curl 打本地代理确认代理本身能转发curl -X POST http://127.0.0.1:2048/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 你是哪个模型}], stream: false }如果代理正常你会看到上游返回的 JSON同时代理终端打印出[IN] POST /v1/chat/completions、[AUTH] Bearer sk-...、[UPSTREAM] status200这几行日志。这一步能通说明代理到上游的链路没问题。4.2 在 OpenCode 里发问打开 OpenCode输入一句简单的话比如「你是哪个模型」。观察两个地方一是 OpenCode 终端里逐字打印的响应二是代理终端里的日志。代理日志里你会看到请求进来、鉴权头透传、上游返回状态码。如果开了流式proxyRes.pipe(res)会把上游的 SSE 数据块原样推给 OpenCodeOpenCode 再逐字渲染出来。这就是效果呈现的完整链路。有个现象你可能会注意到一次提问代理日志里出现了两次请求转发。这不是 bug。OpenCode 在会话初始化或某些操作时可能会先发一个轻量请求做探测或上下文准备再发真正的对话请求。具体原因和请求类型有关你可以通过日志里的[BODY]字节数来区分——通常第一次请求体较小第二次才是完整对话。4.3 观察流式响应把 curl 的stream改成true再打一次curl -N -X POST http://127.0.0.1:2048/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 用一句话解释闭包}], stream: true }-N关闭 curl 的缓冲你会看到data: {...}一行行实时吐出来。这就是 OpenCode 终端里逐字效果的底层数据。代理层没有做任何缓冲上游吐一块它就转一块延迟几乎为零。验证到这里整条链路就通了OpenCode 发请求 → 本地代理接收 → 透传鉴权 → 转发 TaoToken → 流式回传 → OpenCode 渲染。你可以在代理代码里加更多日志比如记录每次请求的模型名、token 数、耗时这些数据对 Agent 开发很有用。5. 本篇常见错误排查搭代理的过程中报错基本集中在几个地方。下面按现象列出来你对号入座。代理启动报EADDRINUSE2048 端口被占用了。可能是你之前启动的代理没关或者别的程序占了这个端口。换端口的话改server.listen的第一个参数同时config.toml里的base_url也要跟着改。查端口占用lsof -i :2048OpenCode 报连接被拒绝说明 OpenCode 没连上代理。检查三件事代理是否在运行、config.toml里的base_url是否是http://127.0.0.1:2048/v1、端口是否一致。注意127.0.0.1不要写成localhost某些环境下解析会有差异。代理日志显示[UPSTREAM] status401鉴权失败。检查 OpenCode 配置里的api_key是否是有效的 TaoToken Key以及代理代码里Authorization头是否正确透传。如果 Key 里有多余空格或换行也会导致 401。代理日志显示[UPSTREAM] status404上游路径不对。确认UPSTREAM_PATH是/api/v1/chat/completions。TaoToken 的 API 基础地址是https://taotoken.net/api所以完整路径是/api/v1/chat/completions别漏了/api这一段。响应卡住不返回多半是流式处理的问题。检查proxyRes.pipe(res)是否执行到了以及Content-Length头是否正确。流式响应不应该带Content-Length如果你手动设置了会导致客户端一直等。代理代码里透传的是上游的响应头一般不会有这个问题但如果你改过代码要留意。代理终端没有任何日志说明请求根本没到代理。检查 OpenCode 是否真的读取了config.toml有些情况下配置文件路径不对会被忽略。可以在 OpenCode 启动时加详细日志参数确认它加载的配置。中文乱码请求体或响应体编码问题。确保Content-Type是application/json且没有手动改过编码。Node.js 默认按 UTF-8 处理一般不会乱码除非你在读取 body 时用了错误的编码。排查的核心思路是先看代理日志有没有请求进来再看上游状态码最后看响应有没有回传。三段定位基本能覆盖大部分问题。如果代理日志正常但 OpenCode 没反应问题在 OpenCode 侧如果代理日志显示上游报错问题在通道或 Key如果代理根本没日志问题在 OpenCode 到代理的连接。6. 继续深入的方向代理跑通之后你可以在这套骨架上做不少扩展。比如在代理层加请求日志落盘把每次对话的模型、耗时、token 数记下来方便做成本分析。比如加一层简单的缓存对相同请求直接返回上次结果省额度。比如加失败重试上游 5xx 时自动重试一次提高 Agent 的稳定性。如果你想把 Key 管理收敛得更干净可以在代理层统一注入鉴权头OpenCode 配置里就不需要放真实 Key 了。这样多个项目共用一套代理Key 只存在一个地方。TaoToken 的 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 。长期做编码 Agent 的话Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 模型对话验证在 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。代理层还有一个值得做的方向是请求改写。比如 OpenCode 发来的模型名是default代理层根据配置映射成实际上游模型名这样切换模型不用改 OpenCode 配置。或者根据请求内容做路由简单问题走快模型复杂问题走强模型。这些逻辑放在代理层OpenCode 完全无感。最后提醒一点代理代码里的错误处理要写全。proxyReq.on(error)只是其中一处客户端断开连接、上游超时、响应体过大这些情况都要考虑。生产用的代理建议加上超时控制和连接数限制避免单个请求卡死拖垮整个服务。