1. opencode 国内安装方法从 npm 权限报错到 endpoint 改到 TaoToken 的完整链路opencode 是一个跑在终端里的开源编码 Agent能读你本地仓库、按自然语言改文件、跑命令、做多轮任务编排适合习惯命令行、想把 AI 编码能力接进自己工作流的开发者。它的定位不是编辑器插件那种「补全式」助手而是能独立执行任务的 CLI Agent所以对模型服务的连通性要求比普通聊天工具高得多——一旦 endpoint 不通它连启动握手都过不去。国内环境装 opencode卡点通常不在「装」本身而在两件事一是 npm 全局目录权限不足导致EACCES二是装完之后默认要连的模型服务在国内网络下握手失败表现为一直转圈、fetch failed、或者干脆卡在初始化。这篇就按「先装干净、再改 endpoint、最后验证」的顺序走一遍把鉴权和 Base URL 统一收到 TaoToken 的 API 通道上让你在本地完成一次可复现的安装与调用测试。适合谁看Node 环境已经装好、想用 opencode 做真实项目改造的人被spawn opencode ENOENT或local proxy failed折腾过的人以及想把多个模型 Key 收敛成一个统一入口、不想每个工具配一遍的人。全程命令可直接复制配置片段按路径给全。先说清楚一个前提opencode 本身只是个客户端壳子它自己不产出模型能力真正干活的是你配置里指向的模型服务。所以「装好」和「能用」是两件事中间隔着 endpoint 和鉴权配置。很多人装完发现opencode --version有输出但一进交互就报错问题基本都在后半段。下面分步拆开。2. TaoToken 前置准备统一 Key 与 API 通道怎么拿在动 opencode 配置之前先把「模型服务入口」这件事定下来。TaoToken 提供的是统一的 API 通道你拿到一个 Key 和一组 Base URL就能在 opencode、Cline、Claude Code 这类工具里复用同一套鉴权不用每个工具单独申请。对 opencode 这种要频繁发请求的 Agent 来说统一入口的好处是排障时只需要盯一个地方。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。登录后进控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 这里能看到你的账户状态和用量。第二步创建 API Key。进 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 点新建复制出来的 Key 形如sk-xxxxxxxx。这个 Key 只显示一次建议先粘到本地临时文件里等配置写完再删。注意别把它提交进 gitopencode 的配置文件如果放在仓库目录里记得加进.gitignore。第三步确认 Base URL。TaoToken 的 API 根地址是 https://taotoken.net/api 注意这个地址不带任何查询参数配置里就写这个。opencode 走的是 OpenAI 兼容协议所以 Base URL 填到/api这一层即可后面的/v1/chat/completions由客户端自己拼。第四步确认你要用的 Model ID。在模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 里可以先手动发一条消息确认这个模型在你的账户下可用页面上会显示当前模型对应的 ID 字符串。把这个 ID 记下来opencode 配置里的model字段要一字不差地填它。如果你打算长期跑编码任务、Agent 调用量大可以顺带看下 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 按用量选合适的档位比单次调用更划算。到这里你手上有三样东西Base URLhttps://taotoken.net/api、API Keysk-...、Model ID。这三件套是后面所有配置的核心缺一个都跑不起来。文档页在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到字段含义不确定时可以对照查。3. 可复制配置opencode 安装与 endpoint 改写全片段这一节是全文最需要照着做的地方。先解决安装再改配置顺序别反。3.1 先修 npm 全局目录权限如果你直接npm install -g opencode-ai报EACCES不要用sudo硬来那会把全局目录的属主搞乱后面更麻烦。稳妥做法是把 npm 全局目录改到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrcWindows 下对应的是把 prefix 指到%USERPROFILE%\.npm-global再把该目录的bin加进用户 PATH。改完之后再装就不会有权限问题了。国内网络下建议顺手换镜像源装包速度会稳很多npm config set registry https://registry.npmmirror.com npm install -g opencode-ai opencode --version如果opencode --version能打印出版本号但where opencodeWindows或which opencodemacOS/Linux查不到实体路径说明你之前是临时解压运行的VSCode 插件会报spawn opencode ENOENT。这种情况要么用上面的 npm 全局装法重装一遍要么手动下载独立版解压到固定目录比如C:\Tools\opencode再把该目录加进系统 PATH然后完全关闭并重开 VSCode插件才能找到实体程序。3.2 写 opencode 配置文件opencode 的配置分两层全局配置放在用户目录项目配置放在仓库根目录。全局配置路径通常是~/.config/opencode/opencode.jsonmacOS/Linux或%USERPROFILE%\.config\opencode\opencode.jsonWindows。项目级配置放在仓库根的opencode.json会覆盖全局同名项。把下面这段 JSON 复制进去字段按你的实际值替换{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: sk-你的Key }, models: { your-model-id: { name: your-model-id } } } }, model: taotoken/your-model-id }几个关键点必须对齐baseURL写https://taotoken.net/api不要多加/v1也不要带任何查询参数apiKey填你在 api-keys 页面拿到的sk-开头的字符串models里的键名和model字段里的模型 ID 必须和你在模型对话页确认的一致写成taotoken/模型ID的形式。npm字段用ai-sdk/openai-compatible因为 TaoToken 走的是 OpenAI 兼容协议。如果你更习惯用环境变量而不是把 Key 写进文件可以把apiKey那行换成读取环境变量然后在 shell 里export TAOTOKEN_API_KEYsk-...。这样配置文件可以安全地提交进仓库Key 留在本地环境里。opencode 支持在options里用{env:变量名}的写法引用环境变量具体写法以文档页为准。3.3 VSCode 插件侧的路径配置如果你用 VSCode 的 opencode 插件还要在settings.json里告诉插件 CLI 在哪。用 npm 全局装的话直接写命令名即可{ opencode.cliPath: opencode }用手动解压的独立版就写绝对路径比如opencode.cliPath: C:\\Tools\\opencode\\opencode.exe。注意 Windows 下 JSON 里的反斜杠要转义成双反斜杠。改完settings.json后完全退出 VSCode 所有窗口再重开插件才会重新读取 PATH 和 cliPath。4. 验证请求确认 opencode 真的连上了 TaoToken配置写完不算完得跑一次真实请求确认链路通。最直接的方式是在终端里启动 opencode 的交互模式opencode进去之后发一条最简单的指令比如让它读一下当前目录的文件列表或者直接问一句「你现在用的是哪个模型」。如果配置正确你会看到它正常返回内容而不是卡在初始化或者报fetch failed。想更精确地验证 endpoint 是否可达可以先用 curl 单独打一次 TaoToken 的接口把 opencode 这一层排除掉curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: your-model-id, messages: [{role: user, content: ping}] }如果这条 curl 能返回正常的 JSON 结构里面有choices字段说明 Key、Base URL、Model ID 三件套都是对的问题只可能在 opencode 的配置格式上。如果 curl 就报 401那是 Key 的问题报 404多半是 Base URL 或 Model ID 写错了报连接超时那是网络层的事和配置无关。curl 通了之后回到 opencode再跑一次交互。这时候如果还报错重点看报错信息里的关键词reading choices说明返回体结构不对通常是 Base URL 多写了或漏写了路径段local proxy failed说明客户端在尝试走本地代理检查一下有没有残留的代理环境变量OAuth相关报错说明鉴权方式被识别成了 OAuth 而不是 API Key检查apiKey字段有没有写对位置。验证通过后你可以让 opencode 做一个真实的小任务比如「在当前目录新建一个 hello.py打印当前时间」看它能不能正确调用工具、写文件、返回结果。这一步过了说明整条链路从 CLI 到模型服务都是通的。5. 本篇常见错排查401、ENOENT、reading choices 对照表排障最怕的是报错信息看不懂。下面把 opencode 国内安装和接入过程中最常见的几类错误列出来对照着查。报错关键词大概率原因处理方式EACCESnpm 全局目录权限不足改 prefix 到用户目录别用 sudospawn opencode ENOENT插件找不到 CLI 实体确认where opencode有路径重开 VSCode401 UnauthorizedKey 错误或没带上检查apiKey字段curl 单独验证local proxy failed残留代理环境变量清掉HTTP_PROXY/HTTPS_PROXY再试reading choices返回体结构不符检查 Base URL 是否写成https://taotoken.net/apiOAuth相关鉴权方式识别错误确认走的是 API Key 而非 OAuth 流程一直转圈不返回endpoint 不通或模型 ID 错先用 curl 打接口再回来看配置重点说几个容易踩的坑。第一个是 Base URL 的写法很多人习惯性写成https://taotoken.net/api/v1结果 opencode 自己又拼一次/v1变成/api/v1/v1/...直接 404。记住只写到/api。第二个是 Model ID 的大小写和连字符。模型 ID 是精确字符串qwen3和Qwen3在有些服务端是两个东西。填之前一定在模型对话页复制一遍别手打。第三个是环境变量污染。如果你之前配过别的工具的代理shell 里可能残留HTTP_PROXYopencode 会尝试走这个代理然后报local proxy failed。用env | grep -i proxy查一下有就unset掉再启动。第四个是 VSCode 插件的缓存。改完settings.json和 PATH 之后如果只是关掉当前窗口重开插件可能还在用旧的进程环境。稳妥做法是任务管理器里确认所有 VSCode 进程都退干净了再重新打开。第五个是 Node 版本。opencode 对 Node 版本有要求太老的版本比如 v12会在装依赖或运行时直接报错。用node -v确认一下建议 v18 以上。版本太低的话先升级 Node 再装 opencode否则后面还会遇到各种奇怪的模块报错。如果 curl 能通但 opencode 不通九成是配置文件格式问题。JSON 对逗号和引号很敏感少一个逗号整个文件就解析失败。可以用opencode启动时的报错信息定位到具体行或者用在线 JSON 校验工具先过一遍。6. 收尾与后续把统一 Key 用在更多编码工具上opencode 跑通之后你会发现这套「Base URL Key Model ID」的三件套是可以复用的。同样的 TaoToken Key可以配到 Cline、Claude Code、Codex 这类工具里不用每个工具单独申请。对经常在多个 Agent 之间切换的人来说统一入口省掉的是重复配置和重复排障的时间。如果你打算长期用 opencode 做项目级改造建议把项目级配置opencode.json提交进仓库把 Key 用环境变量引用这样团队里其他人 clone 下来只要配一次环境变量就能用同一套模型通道。全局配置里放默认模型项目配置里按项目覆盖这个分层用起来会比较顺。验证模型可用性的时候除了在 opencode 里发指令也可以直接在模型对话页手动测一下同一个模型确认账户额度和模型状态都正常。遇到接入层面的报错先看接入文档里的字段说明再对照上面的排查表定位。长期跑编码任务、Agent 调用频繁的话Coding Plan 的档位比按次调用更稳具体可以在对应页面看用量说明。最后留一个实用习惯每次改完配置先用 curl 打一次接口确认三件套没变再启动 opencode。这样能把「配置问题」和「网络问题」分开排障效率会高很多。装好、配好、验证通过之后就可以让它真正开始读你的代码、改你的文件了。
