OpenCode(CLI) 保姆级教程：从 npm/Node.js/NVM 到 TaoToken 统一 Key 接入

1. 为什么第一次装 OpenCode(CLI) 总卡在环境这一步

OpenCode 是一个开源的 AI Agent 编程助手，跑在终端里，能读写你本地的代码文件、执行命令、按会话维护上下文。它本身不绑定某一家模型，你可以把它接到任意兼容 OpenAI 风格接口的服务上，包括 Claude、GPT、Gemini 这类模型。对开发者来说，它更像一个能直接操作项目目录的命令行智能体，而不是一个只会聊天的网页。

适合谁用？三类人最合适：一是习惯在终端里干活、不想开重型 IDE 的人；二是想把 AI 能力串进脚本、做批量任务的人；三是手上已经有统一模型 Key、想让多个 CLI 工具共用一套鉴权通道的人。这篇就是写给第一次接触 OpenCode(CLI) 的开发者，从 npm、Node.js、NVM 一路装到能正常发请求。

真正让人卡住的，往往不是 OpenCode 本身，而是它前面的环境链：Node.js 版本不对、npm 全局路径混乱、镜像源太慢、装完opencode命令找不到。我见过太多人npm install -g opencode-ai跑完，敲opencode却提示「不是内部或外部命令」。这不是 OpenCode 的问题，是 Node 环境和 PATH 没理顺。

所以这篇的路线是：先用 NVM 把 Node.js 版本管起来，再用 npm 全局装 OpenCode，最后把 endpoint 和鉴权改到 TaoToken 的统一 Key 通道。每一步都给可复制的命令和验证动作，装完就能发一次真实请求确认链路通。环境准备这件事，一次做对，后面接别的 AI CLI 工具都能复用。

2. 用 NVM 管好 Node.js 版本再装 OpenCode

OpenCode 依赖 Node.js 运行，官方要求 Node 18 以上、npm 9 以上。但这里有个坑：Node 18 和 20 都已经进入 EOL（停止维护），只满足最低门槛，长期跑不建议。新项目直接上 Node 22 LTS 或 Node 24 LTS，自带 npm 10+，天然满足要求。

为什么不直接装一个 Node 就完事？因为后面你大概率还会碰别的 AI Agent、前端脚手架，它们对 Node 版本要求不一样。全局只装一个版本，迟早会遇到「这个工具要 20、那个要 22」的冲突。NVM（Node Version Manager）就是干这个的：多版本隔离，一条命令切换。

NVM 装完后第一件事是换国内镜像源，否则下载 Node 二进制包会慢到怀疑人生。打开 NVM 安装目录下的settings.txt，在末尾加两行：

node_mirror: https://mirrors.cloud.tencent.com/nodejs-release/ npm_mirror: https://mirrors.cloud.tencent.com/npm/

node_mirror负责下载 Node.js 安装包，npm_mirror负责 npm 拉第三方依赖，一套配置解决两类下载慢的问题。保存后（Ctrl+S），验证 NVM 是否可用：

nvm version

能打印出版本号就说明装好了。接着装 Node 22 并切换：

nvm install 22 nvm use 22 node --version npm --version

node --version应该输出v22.x.x，npm --version输出10.x以上。如果nvm use 22报权限错误，Windows 下用管理员身份开终端再执行一次。

Node 就绪后，确认 npm 镜像源生效：

npm config get registry

预期返回https://mirrors.cloud.tencent.com/npm/。如果不是，手动切一次：

npm config set registry https://mirrors.cloud.tencent.com/npm/

然后全局安装 OpenCode：

npm install -g opencode-ai

装完敲opencode --version验证。如果提示命令找不到，先查 npm 全局路径：

npm config get prefix

把这个路径（通常是C:\Users\你的用户名\AppData\Roaming\npm）加进系统环境变量 Path，重开终端即可。这一步是「命令找不到」类问题的根因，记住它。

3. 把 OpenCode 的 endpoint 与鉴权改到 TaoToken 统一 Key

OpenCode 装好后默认可能连的是内置免费模型，但免费通道不稳定、能力有限。要让它稳定跑起来，得把请求指向一个统一的 API 通道。这里用 TaoToken 做统一入口：一个 Key 管多个模型，endpoint 固定，省得每个工具单独配。

先拿 Key。打开 TaoToken 控制台创建 API Key：

https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite

创建后复制那串sk-开头的 Key，只显示一次，存好。API 基础地址是：

https://taotoken.net/api

注意这个地址不带任何查询参数，配置里就填这个。接下来是 OpenCode 的配置文件。OpenCode 读取的是项目根目录或用户目录下的opencode.json（部分版本也认~/.config/opencode/opencode.json）。新建或编辑这个文件，写入：

{ "$schema": "https://opencode.ai/config.json", "provider": { "taotoken": { "npm": "@ai-sdk/openai-compatible", "name": "TaoToken", "options": { "baseURL": "https://taotoken.net/api", "apiKey": "sk-你的TaoToken密钥" }, "models": { "claude-sonnet-4-5": { "name": "Claude Sonnet 4.5" }, "gpt-4o": { "name": "GPT-4o" } } } }, "model": "taotoken/claude-sonnet-4-5" }

三个关键字段对齐一下：Base URL 填https://taotoken.net/api，Key 填你刚创建的sk-串，Model ID 填taotoken/前缀加模型名。这三件套（Base URL + Key + Model ID）是任何 OpenAI 兼容工具接入的通用公式，OpenCode、Cline、Codex 都一样。

如果你不想把 Key 写死在文件里（推荐），可以用环境变量。把配置里的apiKey改成引用：

"apiKey": "{env:TAOTOKEN_API_KEY}"

然后在终端设置环境变量。Windows PowerShell：

$env:TAOTOKEN_API_KEY="sk-你的TaoToken密钥"

macOS / Linux：

export TAOTOKEN_API_KEY="sk-你的TaoToken密钥"

想永久生效，Windows 用setx TAOTOKEN_API_KEY "sk-..."，macOS/Linux 写进~/.zshrc或~/.bashrc。这样 Key 不进版本库，团队协作也安全。

配置保存后，在项目目录启动：

opencode

进去后用/models命令查看可用模型列表，应该能看到taotoken/claude-sonnet-4-5这类条目。选中它，就完成了从默认通道到 TaoToken 统一 Key 的切换。整个过程没有改 OpenCode 源码，全靠配置文件，升级 OpenCode 也不会丢。

4. 发一次真实请求验证链路是否打通

配置写完不代表通了，得发一次真实请求确认。最直接的方式是在 OpenCode 交互界面里让它做一件小事，比如读当前目录的文件列表。

启动 OpenCode：

opencode

进入 TUI 后，输入一句自然语言指令：

列出当前目录下所有 .js 文件，并告诉我每个文件大概做什么

如果链路正常，OpenCode 会调用模型、返回结果，并在终端里展示它执行的工具调用过程。你能看到它实际跑了ls或读取文件的操作，这说明 Agent 的工具链和模型通道都通了。

想更纯粹地验证 API 通道，可以绕过 OpenCode，直接用 curl 打一次 TaoToken 的接口：

curl https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的TaoToken密钥" \ -d '{ "model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "只回复两个字：通了"}] }'

返回 JSON 里choices[0].message.content是「通了」，说明 Key 和 endpoint 都没问题。这一步能把「OpenCode 配置错」和「Key/通道错」两类问题分开定位，非常有用。

再验证一下模型列表接口：

curl https://taotoken.net/api/v1/models \ -H "Authorization: Bearer sk-你的TaoToken密钥"

返回的模型 ID 列表，就是你在 OpenCode 配置里能填的 Model ID 来源。如果这里没有你想要的模型，说明该模型没在你的 Key 权限范围内，去控制台确认。

成功的结果长这样：OpenCode 里能正常对话并执行文件操作，curl 能拿到 200 和正常 JSON，/models能看到模型列表。三者都过，链路就算彻底打通。任何一环失败，对照下一节的报错排查。

5. 常见报错逐条排查：401、local proxy failed、reading choices

装和配的过程中，报错基本集中在几个固定位置。下面按真实报错逐条拆。

401 Unauthorized / invalid api key

最常见。原因通常是 Key 复制时带了空格、换行，或者用了过期的 Key。先确认环境变量或配置文件里的 Key 是完整的sk-串，没有多余字符。用上面的 curl 单独测一次，如果 curl 也 401，就是 Key 本身的问题，去控制台重新创建一个。如果 curl 通了但 OpenCode 报 401，检查配置文件里apiKey字段有没有被 JSON 转义搞坏，或者环境变量名拼错。

local proxy failed / connection refused

这个报错说明 OpenCode 尝试连的地址不对，或者本地有残留的代理配置在拦截。先确认baseURL是https://taotoken.net/api，没有多写/v1或少写协议头。然后检查系统环境变量里有没有HTTP_PROXY、HTTPS_PROXY这类残留设置，有的话临时清掉再试。注意：这里说的是清理本地无效代理配置，不是让你去配代理，方向别搞反。

reading 'choices' / cannot read properties of undefined

这个报错通常出现在模型返回结构不符合预期时。根因多半是 Model ID 填错了，比如填了claude-sonnet-4-5但没加taotoken/前缀，OpenCode 找不到对应 provider，返回体里没有choices字段。回到配置文件，确认model字段是taotoken/模型名的完整格式，且这个模型名在/models接口返回列表里存在。

OAuth / 登录相关报错

如果你之前用 OpenCode 登录过 GitHub Copilot 或 ChatGPT 账号，配置里可能残留了 OAuth 凭据，和新的 API Key 通道冲突。找到 OpenCode 的凭据存储目录（通常在用户目录下的.local/share/opencode或%APPDATA%\opencode），清理旧的 auth 文件，只保留配置文件里的 Key 方式。清理前先备份。

opencode 命令找不到

回到第 2 节：npm config get prefix拿到全局路径，加进系统 Path，重开终端。Windows 下改完环境变量必须重开终端才生效，这是高频坑。

装完启动报 Node 版本不符

node --version确认是 22 或 24。如果是 18/20，nvm install 22 && nvm use 22切过去。切完重开终端，因为 PATH 里的 node 指向可能被缓存。

排查顺序建议：先 curl 测 Key 和通道，再查配置文件格式，最后查环境变量和 PATH。这样能把问题范围一层层缩小，不用瞎试。

6. 后续怎么用：把统一 Key 复用到其他 CLI 工具

OpenCode 跑通之后，你会发现这套「Base URL + Key + Model ID」的配置模式是通用的。Cline、Codex、Claude Code 这类工具，接入逻辑几乎一样，只是配置文件位置和字段名不同。比如 Codex 用~/.codex/auth.json，Cline 在 VS Code 设置里填，Claude Code 走环境变量。学会一次，后面都是复制粘贴改字段。

如果你打算长期用 OpenCode 跑编码任务、做 Agent 自动化，建议直接上 Coding Plan，额度更稳，适合高频调用：

https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite

只是想先验证模型效果、偶尔对话，用模型对话页就够了：

https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite

需要管理多个 Key、看用量，去控制台：

https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite

配置字段和接入细节，官方文档写得比较全，遇到字段不确定就查：

https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

最后给个实用习惯：把 OpenCode 的配置文件纳入项目模板，新项目直接复制，Key 走环境变量。这样换机器、换项目都不用重新配，也不会把密钥提交进 Git。环境这件事，一次理顺，后面所有 AI CLI 工具都省心。