OpenCode 安装与使用：把 settings 改到 TaoToken 的完整配置流程

1. 为什么第一次装 OpenCode 最容易卡在模型通道上

OpenCode 是一款完全开源的 AI 编程 Agent，用 Go 写，跑在终端里，能读你整个项目、拆任务、执行命令、改代码、跑测试。它自己不带模型，走 BYOK（自带 Key）模式，所以“装完能不能用”这件事，本质上取决于你把模型通道配对了没有。适合谁？适合习惯命令行、又想让 Agent 真正动项目文件的开发者；也适合之前用过闭源方案、想换成能自由接模型的人。

我见过太多人卡在同一处：opencode --version能打印版本，/connect也点了，但一发请求就报401或者local proxy failed。问题不在 OpenCode 本身，而在 settings 里那段模型配置——Base URL、API Key、Model ID 三件套只要有一个不对，请求就发不出去。这篇就按“从零安装 → 改 settings 到 TaoToken → 三步验证”的链路走一遍，每一步都给可复制的片段，你照着填就能跑通第一条请求。

先把结论放前面：OpenCode 的模型配置写在项目根目录的opencode.json里，你要做的是把 provider 的baseURL指向 TaoToken 的 API 地址，把 key 填进去，把 model 写成你要用的模型 ID。下面从安装开始。

2. 安装 OpenCode 并确认版本：三种方式与 opencode --version 校验

安装方式有三种，选一种就行，不用全装。

方式一是官方脚本，一行命令：

curl -fsSL https://opencode.ai/install | bash

方式二是包管理器，前提是本机有 Node.js 运行时：

npm install -g opencode-ai

如果你用 bun / pnpm / yarn，也可以对应替换：

bun install -g opencode-ai pnpm install -g opencode-ai yarn global add opencode-ai

方式三是桌面客户端或 IDE 插件，去官网下载对应平台安装包即可。Windows 用户建议在 PowerShell 或 WSL 里跑，macOS 也可以用 Homebrew。

装完第一件事不是急着连模型，而是确认版本，这一步能帮你排除“装了个旧版导致配置字段不认”的坑：

opencode --version

正常会输出类似opencode 0.x.x的版本号。如果提示 command not found，说明 PATH 没生效，重开一个终端，或者检查包管理器的全局 bin 目录有没有加进环境变量。版本确认没问题，再进下一步。

这里插一句：OpenCode 支持终端 TUI、桌面客户端、IDE 插件三种形态，配置是共用的，都读项目根目录的opencode.json。所以你不管用哪种入口，settings 改法一致。

3. 把 settings 改到 TaoToken：opencode.json 完整配置片段

这是全文最关键的一节。OpenCode 的模型配置放在项目根目录的opencode.json，如果文件不存在就新建一个。下面是一段可直接复制的配置，把 provider 指向 TaoToken 的 API 通道：

{ "$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-4.1": { "name": "GPT-4.1" } } } }, "model": "taotoken/claude-sonnet-4-5" }

几个字段逐个说清楚，别填错：

baseURL必须是https://taotoken.net/api，注意结尾不要多加/v1之类，OpenCode 会按兼容协议自己拼路径。apiKey填你在 TaoToken 控制台生成的密钥，以sk-开头。model这一行是默认模型，格式是provider名/模型ID，上面 provider 叫taotoken，模型 ID 是claude-sonnet-4-5，所以合起来写taotoken/claude-sonnet-4-5。

三件套对照表，方便你核对：

密钥从哪来？去 TaoToken 控制台创建，入口在 API Keys 页面。生成后立刻复制，页面刷新可能就不再完整显示。拿到 key 填进上面的apiKey字段。

注意：opencode.json是项目级配置，放在项目根目录。如果你想让所有项目共用，也可以放到用户级配置目录，但首次跑通建议先用项目级，隔离清楚好排查。

配置写完后，OpenCode 启动时会读取它。你也可以在 TUI 里用/connect查看当前 provider 状态，确认taotoken已经被识别。如果/connect里看不到你配的 provider，八成是 JSON 语法错了——比如多了个逗号、少了引号，用编辑器或python -m json.tool opencode.json校验一下格式。

4. 三步验证：确认配置生效并发起第一条最小请求

配置写完不代表生效，得验证。我习惯用三步，每步都有明确的成功信号。

第一步，确认安装版本，前面已经做过，再跑一次确保没被覆盖：

opencode --version

第二步，检查配置文件是否被正确解析。最直接的办法是启动 OpenCode 后执行/connect，看列表里有没有taotoken，以及默认模型是不是你写的那条。如果 TUI 里显示 provider 已加载，说明 JSON 解析通过。

第三步，发起一次最小请求。进项目目录启动：

cd /path/to/your/project opencode

然后在对话框里输入一句最简单的需求，比如“用一句话说明这个项目是做什么的”。如果模型正常返回内容，说明 Base URL、Key、Model ID 三件套全部打通。返回结果里能看到模型输出，就代表第一条请求跑通了。

想更纯粹地验证通道，也可以直接用 curl 打一次 API，排除 OpenCode 层面的干扰：

curl https://taotoken.net/api/chat/completions \ -H "Authorization: Bearer sk-你的TaoToken密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "ping"}] }'

返回 JSON 里带choices字段和内容，就说明通道没问题。这一步过了，OpenCode 里再报错就基本是配置字段写法问题，而不是网络或密钥问题。

5. 常见报错排查：401、local proxy failed、reading choices 怎么解

跑不通时别慌，对照下面几个真实报错定位。

401 Unauthorized：密钥问题。检查apiKey是不是完整、有没有多余空格、是不是过期或额度用尽。重新去控制台生成一个再试。注意别把 key 提交到 Git 仓库，建议用环境变量注入，或者确认.gitignore里排除了opencode.json。

local proxy failed：通常是 Base URL 写错，或者本机网络到taotoken.net不通。先确认baseURL是https://taotoken.net/api，没有多余路径；再用上面的 curl 单独测一次通道。curl 通、OpenCode 不通，就是配置字段问题。

reading choices相关报错：一般是返回体不是预期的 chat completions 结构，多半是 Model ID 写错，或者 baseURL 多写了/v1导致请求打到了错误路径。把 model 改成配置里models下真实存在的 ID，baseURL 保持https://taotoken.net/api。

OAuth相关提示：OpenCode 某些 provider 走 OAuth 登录，但你用的是 API Key 模式，不该触发 OAuth。如果出现，说明 provider 类型配错了，确认npm字段是@ai-sdk/openai-compatible，走的是兼容接口而非官方 OAuth 流程。

配置文件不生效：确认opencode.json在项目根目录，JSON 语法正确，重启 OpenCode。改完配置一定要重启进程，热加载不一定生效。

提示：排查顺序建议“先 curl 测通道 → 再查 JSON 语法 → 最后看 Model ID”。这个顺序能最快把问题范围缩小到某一层。

6. 跑通之后：把 OpenCode 用顺手的几个配置建议

第一条请求通了，接下来是让它真正干活。几个实用点：

先在 Plan 模式描述需求，让 Agent 给方案，确认后再按 Tab 切到 Build 执行，避免它直接改错文件。执行/init生成项目上下文文件，Agent 理解项目结构会更快。大型重构用会话持久化和 fork，把任务拆成可追溯的多个会话。

模型想换的时候，只改opencode.json里model那一行即可，比如从taotoken/claude-sonnet-4-5换成taotoken/gpt-4.1，前提是models里已经声明了对应 ID。想长期跑编码任务、频繁调用 Agent，可以了解下 Coding Plan 这类按周期计费的方式，比纯按量更可控；只是偶尔验证模型效果，用模型对话页面直接测就行。

密钥管理上，别把sk-开头的 key 硬编码进会提交的文件。可以用环境变量，在opencode.json里引用，或者至少确保它不进版本库。接入文档里有更细的字段说明，遇到不确定的参数先去查一遍再改，比反复试错快。

最后一句实在话：OpenCode 的配置就那三件套，Base URL、Key、Model ID，把这三个对齐，剩下的都是使用习惯问题。第一次跑通后，把这份opencode.json存成模板，下个项目直接复制改 model 就行。