1. 为什么我建议你用 nvm 装 Node.js 再上 OpenCodeOpenCode 是一款开源的 AI 编程助手能在终端里直接对话、读项目文件、改代码支持 75 模型供应商。它通过 npm 分发所以第一步绕不开 Node.js 环境。很多人卡住不是因为 OpenCode 本身难装而是系统里那个 Node.js 版本太旧、或者权限混乱导致npm install -g报 EACCES。我自己的做法是先用 nvm 把 Node.js 版本管起来再全局装 OpenCode最后把模型通道统一指向 TaoToken。这样换项目、换机器都能复现同一套环境。这篇教程适合三类人刚接触 AI 编程助手想跑通第一条命令的新手Node.js 版本被系统包管理器锁死、想干净重装的老手以及手里有多个模型 Key、想用一个统一入口管理的人。全程命令可复制配置骨架可直接改最后会用一个真实对话动作验证链路是否通。核心检索词先摆出来OpenCode 安装、nvm 管理 Node.js、npm 全局安装、TaoToken 统一 API、AI 编程助手配置。下面按安装链路一步步来。2. 前置准备TaoToken 统一 API 通道是什么TaoToken 提供的是一个统一的 API 入口你不需要在 OpenCode 里为每个模型供应商单独填 baseURL 和 Key而是把请求指向同一个通道由它去路由到具体模型。对 OpenCode 这种支持 OpenAI 兼容协议的工具来说配置成本很低一个 baseURL、一个 Key、一个模型名就能跑。你需要提前拿到两样东西API Key 和可用的模型名。Key 在控制台创建模型名在文档里能查到当前支持的列表。建议把 Key 写进环境变量而不是硬编码进配置文件后面配置骨架里我会用{env:...}的方式引用。注意Key 只创建一次就妥善保存页面关闭后通常不再完整显示。如果怀疑泄露直接在控制台吊销重建不要试图找回旧 Key。相关入口我整理成一张表按需点用途地址官网了解能力与计费https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址配置用https://taotoken.net/api创建与管理 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite模型对话验证https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite长期编码/Agent 套餐https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite拿到 Key 后先别急着配 OpenCode下一步先把 Node.js 环境弄干净。3. 用 nvm 装好指定 Node.js 版本3.1 安装 nvm 并重载 ShellmacOS 和 Linux 下推荐脚本安装。打开终端执行curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash如果这条命令拉取超时可以换手动方式下载安装包后按页面说明执行效果一样。安装脚本跑完后它只是把 nvm 写进了 Shell 配置当前会话还没生效必须重载source ~/.zshrc # macOS 默认 zsh # 或 source ~/.bashrc # Linux 常见 bash验证是否装好nvm --version能打印出版本号如0.40.3就说明 nvm 可用了。如果提示command not found八成是重载的配置文件不对确认你当前用的是 zsh 还是 bash再 source 对应的那个。3.2 安装并锁定 Node.js 版本OpenCode 要求 Node.js 18 LTS。我一般直接装当前 LTSnvm install --lts装完确认版本node --version # 期望 v20.x 或更高 npm --version # 期望 10.x 或更高如果你机器上有多个项目需要不同 Node 版本可以用nvm install 20指定大版本再用nvm use 20切换。nvm 的好处就在这里全局包跟着 Node 版本走不会互相污染。切换后建议再跑一次node --version确认避免切了个寂寞。3.3 配置 npm 镜像加速国内直连官方源装全局包容易卡住先换镜像npm config set registry https://registry.npmmirror.com npm config get registry # 应输出 https://registry.npmmirror.com需要恢复官方源时执行npm config set registry https://registry.npmjs.org。这一步不是必须但能显著减少npm install -g的等待时间后面装 OpenCode 会顺很多。4. 通过 npm 全局安装 OpenCode环境就绪后一条命令装 OpenCodenpm install -g opencode-ai如果刚才没配镜像或者临时想指定源可以这样装npm install -g opencode-ai --registryhttps://registry.npmmirror.com装完验证opencode --version能输出版本号即安装成功。如果报EACCES权限错误说明你在用系统级 Node 而不是 nvm 管理的 Node回到第 3 步确认which node指向的是 nvm 目录通常带.nvm路径而不是/usr/local/bin/node。其他安装方式我也列一下按平台选方式命令npm推荐跨平台npm install -g opencode-aiHomebrewmacOSbrew install anomalyco/tap/opencodeBunbun install -g opencode-aipnpmpnpm install -g opencode-ai装好后进入你的项目目录启动cd /path/to/your/project opencode首次进入项目在 TUI 里运行/init它会扫描项目结构并生成AGENTS.md这个文件建议提交到 Git方便团队共享上下文。5. 可复制配置把 OpenCode 接到 TaoToken5.1 设置环境变量先把 Key 写进 Shell 配置避免硬编码。编辑~/.zshrc或~/.bashrc追加export TAOTOKEN_API_KEY你的TaoToken API Key重载source ~/.zshrc验证变量已生效echo $TAOTOKEN_API_KEY5.2 编写 opencode.json 骨架在项目根目录创建或编辑opencode.json用 OpenAI 兼容协议接入 TaoToken{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} }, models: { 你的模型名: { name: TaoToken 模型 } } } }, model: taotoken/你的模型名 }把你的模型名替换成文档里查到的实际模型标识。{env:TAOTOKEN_API_KEY}这种写法让 OpenCode 运行时从环境变量读取 Key配置文件本身可以安全提交到仓库。注意不要把真实 Key 直接写进opencode.json的apiKey字段。一旦提交到 Git等于公开泄露吊销重建很麻烦。5.3 用 /connect 交互式配置备选不想手写 JSON 的话启动 OpenCode 后在 TUI 里运行/connect按提示选择 OpenAI 兼容供应商填入 baseURLhttps://taotoken.net/api和你的 Key再用/models选择模型。这种方式输入的 Key 存在本地~/.local/share/opencode/auth.json不会被 Git 追踪适合临时试用。6. 验证请求跑通一次真实对话配置写完后必须验证否则你不知道是 Key 错、模型名错还是网络问题。启动 OpenCodecd /path/to/your/project opencode在 TUI 里先确认模型已加载/models列表里应该能看到你配置的 TaoToken 模型。选中它然后发一条最简单的提问比如用一句话解释这个项目是做什么的如果模型正常返回内容说明整条链路通了OpenCode → TaoToken 通道 → 目标模型。返回报错的话对照下一节的排查表。想更直接地验证 Key 和通道是否可用也可以先用 curl 打一次接口curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: 你的模型名, messages: [{role: user, content: ping}] }能返回 JSON 结构且带choices字段就说明 Key 和通道没问题问题只可能在 OpenCode 配置层。这个分离排查法很省时间。7. 本篇常见错误排查报错一opencode: command not found全局包装了但 PATH 没包含 npm 全局目录。先跑npm bin -g看路径再确认它在 PATH 里。用 nvm 的话通常不会遇到因为 nvm 会自动处理。报错二EACCES: permission denied说明你在用系统 Node。执行which node如果指向/usr/local/bin/node而不是 nvm 目录回到第 3 步用 nvm 重装 Node别用sudo npm install -g硬扛那会埋更多权限坑。报错三模型返回 401 / UnauthorizedKey 没读到或写错了。先echo $TAOTOKEN_API_KEY确认变量有值再检查opencode.json里引用名是否一致大小写敏感。用/connect方式配的话检查auth.json里的 Key 是否完整。报错四模型返回 404 / model not found模型名写错了。去文档里核对准确的模型标识注意有些模型名带斜杠或版本后缀不能凭记忆写。报错五请求超时先确认baseURL是https://taotoken.net/api没有多余斜杠或路径。再用第 6 节的 curl 单独测一次区分是网络问题还是 OpenCode 配置问题。报错六npm install卡住不动镜像没配或配错。npm config get registry确认输出是https://registry.npmmirror.com不是的话重新 set 一次。排查顺序建议固定先 curl 测通道 → 再/models看模型 → 最后发对话。逐层缩小范围比盲目改配置快得多。8. 接下来怎么用按场景选入口环境跑通后日常使用就三件事写代码、调模型、管 Key。如果你主要是长期编码或跑 Agent 任务建议看一下 Coding Plan它针对高频调用做了额度设计比按次计费更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite想快速验证某个模型效果、对比不同模型输出直接用模型对话页面最省事不用改本地配置https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteKey 的创建、吊销、额度查看都在控制台https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite接入过程中遇到字段含义不清楚的翻文档比搜博客准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite最后给一个我自己的习惯每换一台机器先nvm install --lts再npm install -g opencode-ai然后把opencode.json从旧项目复制过来只改模型名。整套流程五分钟内能跑通比每次重新研究配置省心得多。