1. 云服务器上跑 OpenCode先把坑踩明白OpenCode 是一个跑在终端里的 AI 编码助手能读你当前项目的文件、按自然语言改代码、执行命令适合习惯 SSH 连服务器干活的人。这篇要解决的是在一台全新的 Ubuntu 云服务器上从零把 Node.js、npm、OpenCode 装好再用 TaoToken 的统一 Key 和 API 通道接上模型最后用一条 curl 确认通道真的通了。适合手里有云主机、想搭一个云端 AI 编码环境、又不想在每台机器上分别配一堆厂商 Key 的人。我试过在一台 2 核 4G 的 Ubuntu 22.04 上完整走一遍从裸机到opencode能对话大概十几分钟中间卡过两次一次是系统自带的 Node 版本太低一次是全局安装权限报 EACCES。下面把顺序、命令、配置骨架和排错都摊开写你照着敲就行。整体链路是Ubuntu 基础环境 → Node 20 → OpenCode CLI → TaoToken 统一 Key → settings.json 骨架 → curl 验证 → 进入项目用起来。每一步都有可复制的命令配置部分给的是能直接改的 JSON 骨架不是伪代码。2. TaoToken 前置统一 Key 与 API 通道是什么TaoToken 在这里扮演的角色是「一个 Key 对接多个模型通道」。传统做法是 Claude 配一个 Key、GLM 配一个 Key、别的模型再配一个环境变量和配置文件里散落一堆密钥换机器就得重新抄一遍。TaoToken 把这些收敛成一个统一 Key 加一个 API 地址OpenCode 只认这一组凭据后面换模型只改模型名不动鉴权。对云服务器场景来说这点很关键服务器上的配置文件往往会被你复制到第二台、第三台机器统一 Key 意味着你只需要维护一份凭据。API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 base URL 用。你需要提前准备两样东西一个 TaoToken 账号下的 API Key以及确认你要用的模型名。Key 在控制台的 API Keys 页面生成模型名在文档里能查到当前可用的列表。这两样拿到后剩下的就是写进配置文件。注意API Key 属于敏感凭据不要提交到 Git 仓库也不要在多人共用的服务器上放进全局可读的文件。建议放在用户级配置或环境变量里权限设成 600。如果你还没生成 Key可以先到控制台建一个模型名和接入方式在文档里有对照表。这两个页面建议开着配的时候直接抄。3. 可复制配置从裸机到 settings.json 骨架3.1 系统更新与基础工具先用 SSH 连上服务器把包索引更新一遍装好 git 和 curl后面拉 NodeSource 脚本和验证请求都要用。ssh ubuntu你的公网IP sudo apt update sudo apt upgrade -y sudo apt install -y git curl3.2 清理旧 Node 并安装 Node 20Ubuntu 仓库自带的 Node 版本通常偏低OpenCode 要求 Node 18推荐 20。先移除可能存在的旧版本避免和 NodeSource 的包冲突。sudo apt remove nodejs libnode-dev nodejs-doc -y sudo apt autoremove -y sudo apt clean curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs node -v npm -vnode -v应该输出v20.x.x。如果还是旧版本说明 PATH 里残留了别的 node用which -a node看一下有几个把旧的清掉。3.3 安装 OpenCode CLI全局安装 OpenCodesudo npm install -g opencode-ai opencode --version版本号能打印出来就说明 CLI 装好了。如果这里报 EACCES 权限错误说明 npm 的全局目录权限不对最省事的做法就是像上面这样加sudo不想用 sudo 的话可以改 npm 的 prefix 到用户目录但服务器上单人使用sudo 更直接。3.4 settings.json 配置骨架OpenCode 的配置放在用户目录下的配置文件夹里。先建目录再写配置文件mkdir -p ~/.config/opencode下面是~/.config/opencode/settings.json的骨架把你的TaoTokenKey换成实际 Key{ provider: { taotoken: { type: openai-compatible, baseURL: https://taotoken.net/api, apiKey: 你的TaoTokenKey, models: { default: { name: claude-sonnet-4-5, maxTokens: 8192 } } } }, defaultProvider: taotoken, defaultModel: claude-sonnet-4-5 }几个字段说明一下type用openai-compatible是因为 TaoToken 的 API 走的是兼容 OpenAI 的调用格式baseURL固定为https://taotoken.net/api不要在后面加斜杠或路径apiKey填你的统一 Keymodels里可以放多个模型defaultModel指向默认用的那个。模型名以文档里当前可用的为准上面只是个示例占位。3.5 环境变量写法可选但推荐不想把 Key 写死在 JSON 里可以用环境变量配置文件里引用变量名。在~/.bashrc末尾追加export TAOTOKEN_API_KEY你的TaoTokenKey export TAOTOKEN_BASE_URLhttps://taotoken.net/api然后source ~/.bashrc生效。对应的 settings.json 改成引用{ provider: { taotoken: { type: openai-compatible, baseURL: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, models: { default: { name: claude-sonnet-4-5, maxTokens: 8192 } } } }, defaultProvider: taotoken, defaultModel: claude-sonnet-4-5 }用apiKeyEnv指向环境变量名这样配置文件本身可以安全地放进版本控制或复制到别的机器Key 留在各机器的环境变量里。记得给配置文件设权限chmod 600 ~/.config/opencode/settings.json4. 验证请求一条 curl 确认通道连通配置写完别急着开 OpenCode先用 curl 直接打一次 API确认 Key、地址、模型名三者都对。这一步能把「配置问题」和「CLI 问题」分开排错时省很多时间。curl -sS https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [ {role: user, content: 只回复两个字通了} ], max_tokens: 32 }如果 Key 是直接写在 JSON 里、没走环境变量把$TAOTOKEN_API_KEY换成实际 Key 字符串。返回体里应该能看到choices数组里面message.content是模型回复。看到正常 JSON 返回说明通道是通的。接着验证 OpenCode 本身能不能读到配置opencode --version cd ~/your-project opencode进入交互界面后随便问一句比如「列出当前目录的文件」能正常返回就说明 CLI 和配置都对上了。如果 curl 通但 OpenCode 不通问题基本在 settings.json 的字段名或路径上回头核对baseURL有没有多写斜杠、apiKeyEnv名字和环境变量是否一致。5. 本篇常见错排查5.1 EACCES 权限错误现象npm install -g opencode-ai报EACCES: permission denied。原因是 npm 全局目录归 root 所有普通用户写不进去。解决命令前加sudo或者把 npm prefix 改到用户目录。服务器单人用直接sudo npm install -g opencode-ai最省事。5.2 Node 版本过低现象运行 OpenCode 报SyntaxError: Unexpected token ?之类的语法错误。这是旧版 Node 不认识新语法。解决按 3.2 的步骤升到 Node 20用node -v确认版本必要时which -a node清掉残留的旧二进制。5.3 Node 安装冲突现象装 NodeSource 包时报trying to overwrite ... libnode-dev。这是系统里已有 libnode-dev 和 NodeSource 的包打架。解决sudo apt remove nodejs libnode-dev -y sudo apt autoremove -y清干净再重装。5.4 curl 返回 401 或 403Key 不对或没带上。检查Authorization头是不是Bearer加 Key中间有空格检查环境变量有没有source生效echo $TAOTOKEN_API_KEY看有没有值。Key 前后不要有引号或换行。5.5 curl 返回 404多半是地址写错。baseURL和 curl 里的路径要拼成https://taotoken.net/api/v1/chat/completions。如果 settings.json 里baseURL末尾多加了/或者 curl 里少写了/v1都会 404。核对地址拼出来的完整 URL。5.6 OpenCode 读不到配置现象curl 通但 OpenCode 说没配置 provider。检查配置文件路径是不是~/.config/opencode/settings.json注意是opencode不是opencode-ai检查 JSON 有没有语法错误可以用python3 -m json.tool ~/.config/opencode/settings.json验证格式。6. 配好之后怎么用起来通道验证通过后日常使用就是进项目目录直接跑opencode。它会读取当前目录的上下文你可以让它解释代码、改 bug、写测试。模型切换只改 settings.json 里的defaultModelKey 和地址不动这就是统一 Key 的价值——换模型不换凭据。如果你打算长期在服务器上跑编码任务或者接 Agent 做自动化可以了解一下 Coding Plan它更适合持续性的编码场景不用每次手动起会话。想先验证不同模型的效果直接在模型对话页面里试确认哪个模型适合你的任务再写进配置。Key 的管理和重新生成在 API Keys 页面接入细节和模型名对照看接入文档。最后留一个实用习惯把 settings.json 和环境变量分开管理配置文件进 GitKey 留在服务器环境变量里。这样你复制环境到第二台机器时只需要在新机器上设一次环境变量配置直接拉下来就能用。