opencode 安装使用：用 npm 装好后配 TaoToken 的 opencode.json 骨架

1. 刚用 npm 装完 opencode第一次打开却卡在配置上如果你刚在终端里敲完npm install -g opencode-ai看到opencode --version正常输出版本号心里大概会松一口气——装是装上了。但紧接着第一次运行opencode它不会像某些 CLI 那样直接给你一个能聊天的界面而是需要你先准备好一份opencode.json配置文件。这个文件决定了 opencode 去哪个服务商、用哪个模型、拿什么 Key 去请求。很多人就是卡在这一步文件放哪、字段怎么写、API_KEY和END_POINT_ID到底填什么官方文档给的是通用结构但落到具体通道上还是得自己拼。这篇就围绕这个首次配置环节展开。目标很明确你已经在本地用 npm 装好了 opencode接下来要做的是在opencode.json里填入 TaoToken 的 API Key 和模型端点 ID让 opencode 通过 TaoToken 的统一 Key/API 通道发请求。我会给出一份可以直接复制、改两个值就能用的配置骨架再给一条验证命令确认配置真的生效然后你再去日常使用。适合人群是刚接触 opencode、对 JSON 配置不算陌生但不想反复试错的开发者。整个过程不需要你改 opencode 源码也不需要额外装插件就是编辑一个文件、跑一条命令。先说清楚 opencode 是什么、能做什么。它是一个跑在终端里的 AI 编码助手可以理解你的项目文件、执行命令、生成代码补丁交互方式偏命令行。它本身不绑定某一家模型服务而是通过 provider 配置去对接兼容 OpenAI 接口风格的服务。TaoToken 在这里扮演的角色就是提供统一的 Key 和 API 入口你不需要为每个模型单独申请账号只要在 opencode.json 里把 baseURL 指向 TaoToken 的 API 地址把 apiKey 换成你在 TaoToken 控制台拿到的 Key再指定一个模型端点 IDopencode 就能正常对话和干活了。下面从准备 Key 开始一步步来。2. 前置准备在 TaoToken 拿到 API_KEY 与 END_POINT_ID在动 opencode.json 之前先把两样东西准备好API Key 和你要用的模型端点 ID。这两样都在 TaoToken 这边获取。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台。控制台里一般会有 API Keys 管理页面你可以新建一个 Key复制出来先存到安全的地方。这个 Key 就是后面配置里apiKey字段要填的值形如一段长字符串。注意不要把它提交到 Git 仓库也不要在公开场合贴出来。接着是模型端点 ID。TaoToken 的 API 通道兼容 OpenAI 风格的调用方式模型通过一个端点 ID 来标识。你可以在控制台的模型列表或文档里找到当前可用的模型端点 ID比如类似glm-4-7这样的标识。这个值会填到 opencode.json 里models对象的键名位置同时也是你之后在 opencode 里用/models选择模型时看到的名称来源。如果你不确定用哪个可以先选一个通用对话模型等配置跑通后再换。这里有个容易混淆的点END_POINT_ID不是 URL也不是 Key它就是一个模型标识字符串。opencode 的配置结构里models下面每个键就是一个端点 ID值里再给这个模型起一个显示名。你填错端点 IDopencode 启动时可能不报错但一发请求就会返回模型不存在的错误。所以复制的时候尽量别手打直接从控制台或文档里粘贴。TaoToken 的 API 基础地址是 https://taotoken.net/api 这个地址会作为baseURL填进配置。注意它和官网地址不是同一个配置里用的是 API 地址不带后面的路径参数。opencode 会在这个 baseURL 基础上拼接/chat/completions之类的路径所以你不要自己再加/v1或别的后缀除非文档明确要求。把这三样记好API Key、端点 ID、baseURL接下来写配置。3. 可复制的 opencode.json 配置骨架opencode 读取配置文件的路径在 Windows 上通常是C:\Users\你的用户名\.config\opencode\opencode.json在 macOS 和 Linux 上通常是~/.config/opencode/opencode.json。如果.config/opencode目录不存在先手动创建。你可以用编辑器直接新建这个文件也可以用命令行创建。下面这份骨架就是围绕 TaoToken 通道写的你只需要替换两个占位值。{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: taotoken, options: { baseURL: https://taotoken.net/api, apiKey: 你的_API_KEY }, models: { 你的_END_POINT_ID: { name: taotoken-你的_END_POINT_ID } } } } }逐字段说明一下。$schema指向 opencode 官方的配置 schema保留它可以让编辑器给你补全和校验不写也不影响运行但建议留着。provider下面我们自定义了一个名为taotoken的提供方这个名字你可以改但改了之后 opencode 里选择模型时的前缀也会跟着变建议先保持taotoken。npm字段指定用ai-sdk/openai-compatible这个适配包因为 TaoToken 的接口是 OpenAI 兼容风格用这个适配器最省事。name是显示名随便起不影响请求。options里两个关键字段baseURL填https://taotoken.net/apiapiKey填你从控制台复制的 Key。注意 Key 是字符串直接放在双引号里不要加Bearer前缀opencode 和适配器会自己处理认证头。models对象里键名就是你的端点 ID值里的name是这个模型在 opencode 界面里显示的名字。你可以放多个模型每个键一个端点 ID之后用/models切换。如果你之前已经有一份 opencode.json只是里面配了别的 provider那不要整份覆盖而是把taotoken这个 provider 块加到现有provider对象里和原来的并列。JSON 里同级对象用逗号分隔注意别漏逗号也别多逗号。改完保存可以用python -m json.tool opencode.json或编辑器自带的格式化检查一下语法JSON 语法错误会导致 opencode 直接读不到配置。注意API Key 属于敏感信息不要把 opencode.json 提交到公开仓库。如果必须共享配置把 Key 抽成环境变量但 opencode 当前版本对环境变量插值的支持要看具体版本稳妥起见先本地明文保存并做好文件权限控制。4. 验证配置一条命令确认请求真的走通配置文件写好后先别急着进交互界面。用一条非交互命令验证配置是否生效能最快定位问题。opencode 支持通过命令行直接发一条 prompt 并打印结果具体子命令可能随版本略有差异常见的是opencode run或opencode -p。你可以先跑opencode --help看当前版本支持哪种。假设你的版本支持run可以这样验证opencode run --model taotoken/你的_END_POINT_ID 用一句话说明你现在使用的是哪个模型这条命令做了几件事指定使用我们刚配置的taotokenprovider 下的某个端点 ID发一条简单 prompt然后把模型返回打印到终端。如果配置正确你会看到模型返回的一句话说明 baseURL、apiKey、端点 ID 三者都对上了。如果返回的是认证失败、模型不存在或连接超时就对照下一节的排查清单逐项检查。另一种验证方式是进入交互界面后用/models命令。启动opencode在输入框里敲/models如果配置被正确加载列表里应该能看到你填的那个模型显示名。选中它再随便问一句能正常回复就说明通道通了。这种方式更接近日常使用但定位问题时不如命令行直接因为交互界面可能把错误信息折叠起来。我一般先用命令行跑通再进交互界面。验证时建议用一句非常短的 prompt比如“回复 ok”减少 token 消耗和等待时间。如果第一次请求特别慢可能是网络到 API 地址的延迟不一定是配置错。可以多试一次或者换一个端点 ID 再试。确认成功后你就可以正常用 opencode 做日常编码了比如让它读项目文件、生成补丁、解释代码。后续想换模型只改models里的端点 ID 即可不用动 baseURL 和 Key。5. 本篇常见错排查配置不生效的几种典型情况配置环节出错表现往往很相似opencode 启动正常但一发请求就报错或者干脆找不到模型。下面按我遇到过的顺序列几种典型情况你可以对照排查。第一种配置文件路径放错。opencode 只读固定路径下的opencode.json如果你把文件放在项目根目录或者用户主目录它不会自动加载。Windows 确认是C:\Users\你的用户名\.config\opencode\opencode.jsonmacOS/Linux 确认是~/.config/opencode/opencode.json。注意.config前面有个点是隐藏目录。可以用opencode --help或查看日志确认它实际读取的路径。第二种JSON 语法错误。多一个逗号、少一个引号、用了中文引号都会导致整个文件解析失败。表现是 opencode 完全不认识你配的 provider/models里看不到。用python -m json.tool opencode.json跑一下能过就说明语法没问题。另外注意$schema那行如果 URL 写错不影响运行但编辑器校验会报错别被误导。第三种apiKey 填错或带了多余前缀。常见错误是复制 Key 时带上了空格或者手动加了Bearer。配置里只填 Key 本身。如果 Key 已经失效或被删除请求会返回 401。去 TaoToken 控制台确认 Key 状态必要时重新生成一个。第四种端点 ID 写错。models的键名必须和控制台里的端点 ID 完全一致大小写敏感。写错的话/models里可能还能看到你自定义的显示名但请求会返回模型不存在。把键名和显示名分开看键名是给 API 用的显示名只是给你看的。建议键名直接粘贴不要手打。第五种baseURL 多写或漏写路径。TaoToken 的 API 地址是https://taotoken.net/api不要自己加/v1也不要加/chat/completions。适配器会拼接。如果你从别处抄了带/v1的地址很可能请求打到错误路径返回 404。改回标准地址再试。第六种网络或代理干扰。如果你本地有全局代理可能影响对 API 地址的请求。可以临时关掉代理再验证或者确认代理规则没有拦截该域名。这一条不是配置问题但表现和配置错误很像容易误判。排查时建议一次只改一个变量改完立刻用第 4 节的命令行验证不要同时改 Key 和端点 ID否则不知道是哪个起的作用。如果所有项都确认无误还是失败把命令行返回的完整错误信息记下来对照 TaoToken 的接入文档看错误码含义。文档入口在控制台或官网都能找到接入相关的说明比通用教程更贴合实际通道。6. 配置跑通之后日常使用与后续入口配置验证通过后opencode 的日常使用就顺了。你可以在项目目录下启动它让它读取当前目录的文件用自然语言描述需求它会给出代码修改建议或直接生成补丁。模型切换用/models想换端点 ID 就改 opencode.json 里的models键保存后重启 opencode 生效。Key 如果轮换同样改apiKey字段即可baseURL 一般不用动。如果你后面要长期用 opencode 做编码或跑 Agent 类任务可以关注 TaoToken 的 Coding Plan它更适合高频、长时间的编码场景入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。日常只是想快速验证某个模型对话效果用模型对话页面更直接https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要管理多个 Key 或查看用量去控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入过程中遇到字段或路径问题接入文档里有更细的说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你用的是 Claude Code 这类工具对应的 Anthropic 兼容配置也可以参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后提醒一句opencode.json 里的 Key 别外泄验证命令跑通后就可以正常干活了。配置这件事一次做对后面基本不用再碰把精力留给真正的编码任务。