Pi Agent 接入 opencode 免费模型：models.json 与 User-Agent 配置避坑指南

1. Pi Agent 调用 opencode 免费模型为什么总报流量耗尽Pi Agent 是一个跑在本地的命令行 Agent 框架它的定位很直接把大模型能力接到你的终端里让模型帮你读写文件、执行命令、跑测试。opencode 则是一个开源的编码助手项目它对外暴露了兼容 OpenAI 协议的接口并且提供了一批免费模型额度。很多人第一反应就是把这两个拼起来用——本地 Agent 负责调度opencode 负责出 token看起来是零成本方案。但真正动手之后报错会来得比想象中快。最常见的两类现象是第一请求直接返回流量耗尽或者额度不足可你明明刚注册、额度还是满的第二模型列表拉出来是空的/models返回 200 但data数组里什么都没有。这两个问题看起来像鉴权失败实际上根因往往不在 Key而在两个特别容易被忽略的地方models.json里的字段结构以及请求头里的User-Agent。我先把结论摆出来方便你对号入座。opencode 的服务端会校验请求来源它期望看到的是自家客户端发出的请求特征。如果你的 Agent 用默认的 HTTP 客户端 UA比如python-requests/2.x、node-fetch、Go-http-client服务端可能直接判定为非官方流量于是返回额度耗尽的错误——这个错误信息具有误导性它不告诉你 UA 不对只告诉你没流量了。另一个坑是models.json的层级很多人把headers写在 provider 同级而不是嵌在 provider 内部配置加载时被静默忽略UA 根本没生效。这篇面向的是本地 Agent 开发者尤其是已经在用 Pi Agent、想接 opencode 免费模型做联调的人。你需要的基础是会编辑 JSON 配置文件能用 curl 发请求看得懂 HTTP 状态码。下面我会给出可直接复制的models.json片段、UA 覆盖写法、curl 验证命令以及把 endpoint 切到 TaoToken 统一 Key 通道完成联调的完整动作。全程不需要任何额外网络工具纯本地配置。2. TaoToken 统一 Key 通道的前置准备与模型清单确认在讲 opencode 的坑之前先说一下为什么建议你同时准备一条 TaoToken 的通道。原因很实际opencode 免费模型有额度限制而且它的 UA 校验规则可能随版本变化今天能用的写法下个月未必能用。当你需要稳定联调、或者免费额度用完之后把 endpoint 切到一个统一的 Key 通道是最省事的做法不用改 Agent 代码只改配置里的 base URL 和 Key。TaoToken 的接入地址是https://taotoken.net/api它兼容 OpenAI 的/v1/chat/completions和/v1/models协议所以 Pi Agent 里凡是走 OpenAI 兼容格式的 provider基本都能直接指过来。你需要先去控制台创建一个 API Key入口在https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。创建完之后把 Key 复制出来格式通常是一串以sk-开头的字符串先存到环境变量里别硬编码进配置文件。模型清单这块你可以先用模型对话页面确认一下当前可用的模型 ID地址是https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。为什么要先确认因为 Pi Agent 的models.json里要写死模型 ID如果你写的 ID 在服务端不存在请求会返回 404 或者model not found这个错误和 UA 问题混在一起排查会很痛苦。把模型 ID 抄准能省掉一半的排障时间。环境变量建议这样设Linux/macOS 用export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api设完之后用echo $TAOTOKEN_API_KEY确认一下有没有生效。这一步看着简单但我见过太多人配置文件里写的是$TAOTOKEN_API_KEY结果 shell 没导出Agent 读到的字面量就是那个美元符号加变量名然后报 401。如果你打算长期用编码类 Agent也可以了解一下 Coding Plan地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content它更适合高频调用场景。3. models.json 字段结构与 User-Agent 覆盖的可复制配置现在进入正题。Pi Agent 的配置文件默认在~/.pi/agent/models.jsonWindows 下是%USERPROFILE%\.pi\agent\models.json。这个文件的结构是providers对象下面挂各个 provider每个 provider 里有baseUrl、apiKey、models等字段。关键点在于headers的位置它必须是 provider 的直接子字段和baseUrl平级不能写到models数组里面去。先给你一份接 opencode 免费模型的完整配置可以直接复制{ providers: { opencode: { baseUrl: https://opencode.ai/api, apiKey: opencode-free, headers: { User-Agent: opencode/1.18.18 }, models: [ { id: opencode/grok-code, name: Grok Code Fast } ] } } }这里有几个细节要盯住。第一User-Agent的值写成opencode/1.18.18这种「客户端名/版本号」的格式服务端就是靠这个判断你是不是官方客户端。版本号可以跟着 opencode 的 release 走但不要写成浏览器 UA那样反而更可疑。第二apiKey在免费模型场景下通常填一个占位符就行因为 opencode 免费额度不校验真实 Key但字段不能缺缺了 Pi Agent 加载时会报 provider 配置不完整。第三models数组里的id必须和服务端实际暴露的模型 ID 完全一致大小写敏感。如果你要把 endpoint 切到 TaoToken配置改成这样{ providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, headers: { User-Agent: opencode/1.18.18 }, models: [ { id: claude-sonnet-4-5, name: Claude Sonnet 4.5 } ] } } }注意apiKey这里用了${TAOTOKEN_API_KEY}的变量引用写法Pi Agent 支持从环境变量插值。如果你不确定你的版本支不支持就直接把 Key 字符串填进去先跑通再优化。User-Agent我建议保留因为有些网关对 UA 有白名单策略保留一个正常的客户端标识比裸奔更稳。再强调一次headers的层级。下面这种写法是错的UA 不会生效{ providers: { opencode: { baseUrl: https://opencode.ai/api, models: [ { id: opencode/grok-code, headers: { User-Agent: opencode/1.18.18 } } ] } } }错在哪headers被塞进了models数组的元素里而 Pi Agent 读取请求头是从 provider 层级读的模型层级的headers会被忽略。这个错误不会报错只会表现为「配置改了但没用」非常隐蔽。改完配置后建议用python -m json.tool ~/.pi/agent/models.json校验一下 JSON 合法性避免逗号或括号问题导致整个文件加载失败。4. 用 curl 与日志验证模型可用性的具体动作配置写完别急着在 Agent 里跑先用 curl 单独验证把配置问题和网络问题分开。第一步验证模型列表curl -s https://opencode.ai/api/models \ -H User-Agent: opencode/1.18.18 \ -H Authorization: Bearer opencode-free | python -m json.tool如果返回的 JSON 里data数组有内容说明 UA 和鉴权都过了。如果data是空的先检查 UA 是不是被 shell 转义了再检查 URL 路径对不对。如果返回 401把Authorization头去掉再试一次有些免费端点不认这个头。第二步验证对话接口curl -s https://opencode.ai/api/chat/completions \ -H Content-Type: application/json \ -H User-Agent: opencode/1.18.18 \ -H Authorization: Bearer opencode-free \ -d { model: opencode/grok-code, messages: [{role: user, content: say hi}], max_tokens: 16 } | python -m json.tool正常返回里会有choices[0].message.content。如果返回choices字段读取失败或者报reading choices之类的错误八成是响应体根本不是 JSON可能是 HTML 错误页这时候把-s换成-i看完整响应头状态码会告诉你真相。切到 TaoToken 通道后验证命令换成curl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: say hi}], max_tokens: 16 } | python -m json.toolcurl 通了之后再回到 Pi Agent 里跑。开启调试日志的方式通常是设环境变量PI_LOG_LEVELdebug然后启动 Agent观察它实际发出的请求头里有没有你配置的 UA。日志里会打印request headers如果看到User-Agent: python-requests/2.x而不是你配的值说明配置没被加载回去检查models.json的路径和层级。实测下来把 curl 验证和 Agent 日志这两步做扎实排障时间能从半天压缩到十分钟。5. 401、local proxy failed、reading choices 等报错逐条排查这一节把常见报错和根因对应起来你按现象查就行。401 Unauthorized先确认 Key 有没有正确注入。如果你用的是${TAOTOKEN_API_KEY}变量写法在 shell 里echo一下确认非空。如果 Key 是对的还报 401检查Authorization头的格式必须是Bearer加空格加 Key少个空格也会 401。还有一种情况是 Key 前后带了换行或引号从控制台复制时容易带上用cat -A看一下配置文件里有没有隐藏字符。local proxy failed这个错误通常出现在你本地配了 HTTP 代理但代理进程没起来或者端口不对。Pi Agent 会读取HTTP_PROXY/HTTPS_PROXY环境变量如果你之前设过先unset HTTP_PROXY HTTPS_PROXY再跑。注意这里说的是本地代理进程配置问题不是让你去用什么网络工具纯粹是环境变量清理。reading choices / cannot read properties of undefined这是响应体结构不符合预期。根因一般是服务端返回了错误 JSON比如{error: {message: ...}}而 Agent 代码直接去读choices就崩了。解决办法是先用上一节的 curl 命令看原始响应把error.message读出来。常见的有model not found模型 ID 写错、insufficient quota额度真用完了、invalid user agentUA 没生效。OAuth 相关报错如果你之前用 opencode 官方客户端登录过本地可能残留了 OAuth token 文件Pi Agent 读取时可能和你的 API Key 冲突。检查~/.opencode/或~/.config/opencode/下有没有auth.json之类的文件临时改名备份再试。如果你用的是 Codex 系的 Agentauth.json里通常存OPENAI_API_KEY和base_url确认这两个字段指向的是你要用的通道。模型列表为空但状态码 200这是最迷惑的一种。状态码 200 说明请求通了但data为空说明服务端认为你没有可用模型。除了 UA 问题还要检查请求的路径是不是/models而不是/v1/models有些服务两种路径返回不同结果。另外确认你的账号有没有完成必要的初始化步骤有些平台新账号需要先调一次对话接口才会激活模型列表。排查顺序建议固定下来先 curl 看原始响应再开 Agent debug 日志看实际请求头最后对照配置文件层级。三步走完90% 的问题都能定位。6. 把 endpoint 切到 TaoToken 完成联调的收尾动作当你用 opencode 免费模型把 Pi Agent 的调用链路跑通之后最后一步是把 endpoint 切到 TaoToken 统一 Key 通道做一次完整联调。这么做的好处是免费额度用完不用改代码模型 ID 想换就换而且 UA 校验的不确定性也绕开了。具体动作就三步。第一步把models.json里的 provider 从opencode改成taotokenbaseUrl改成https://taotoken.net/apiapiKey换成你的真实 Key。第二步把models数组里的id换成你在模型对话页面确认过的模型 ID。第三步重启 Pi Agent跑一个真实任务比如让它读一个文件并总结观察日志里请求是否正常返回。如果你在切通道过程中遇到鉴权问题接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content里面有各语言的请求示例和错误码说明。Key 管理在https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content可以随时创建和吊销。需要快速验证模型是否可用时直接用模型对话页面发一条消息最直观。最后留一个我踩过的坑改完配置后一定要完全退出 Pi Agent 进程再重启有些版本会缓存models.json热重载不生效你会以为配置没写对其实是进程没重启。确认进程重启后日志里能看到新的 base URL 和模型 ID就说明切换成功了。