1. 从零装好 opencode 并跑通第一条 AI 编码请求opencode 是一个跑在终端里的开源 AI 编码助手你可以把它理解成「命令行版的结对程序员」它读你当前项目的文件、按你的自然语言指令改代码、跑命令、解释报错。和那些绑定单一模型厂商的工具不同opencode 走的是 provider 抽象层只要某个服务兼容 OpenAI 风格的/v1接口就能挂上去当后端。这一点对国内开发者特别关键——你不需要为了用哪个模型而反复换工具只要有一个稳定的统一 Key 通道就能在 opencode 里自由切换模型。这篇教程面向第一次接触 opencode 的人目标很明确从装 Node、装 opencode 包到写好配置文件、接上 TaoToken 的统一 Key最后用一条 curl 请求确认通道真的通了再进 CLI 发出第一条 AI 编码指令。整个过程我会把每一步的命令、配置片段、预期返回都写清楚你照着敲就行。踩过的坑我也会标出来尤其是 401、local proxy failed 这类高频报错提前知道能省不少时间。先说清楚适合谁如果你已经会用终端、电脑上装过 Node那这篇基本是 20 分钟能跑完的活如果你完全没碰过命令行也没关系命令我都给全了复制粘贴即可。唯一的前提是你得有一个能用的模型 API Key这里我们用 TaoToken 的统一 Key 来打通整条链路。2. TaoToken 前置准备拿到统一 Key 和 Base URL在装 opencode 之前先把「后端」准备好否则配置写完发现没 Key 可用还得回头折腾。TaoToken 在这里扮演的角色是统一入口你注册后拿到一个 Key配合固定的 Base URL就能访问它支持的多个模型。opencode 侧只需要认这个 Base URL 和 Key模型 ID 按你实际要用的填。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号。注册流程很常规邮箱加密码验证完就能进控制台。第二步进控制台创建 API Key。地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面点新建复制出来的那串就是你的统一 Key。注意这串 Key 只显示一次先存到记事本里等会儿要填进配置文件。第三步确认你要用的模型 ID。opencode 的配置里models字段的键名就是模型 ID填错了请求会直接报模型不存在。你可以先在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 里试一下目标模型能不能正常回话确认可用再写进配置避免配置写完才发现模型名不对。这里有个概念要理清opencode 的 provider 配置里baseURL指向的是兼容 OpenAI 的接口根路径。TaoToken 的 API 根地址是 https://taotoken.net/api 在 opencode 里通常要写成带/v1的形式也就是https://taotoken.net/api/v1。这个/v1别漏漏了大概率会 404 或者返回一堆 HTML 而不是 JSON。注意Key 属于敏感凭证别直接提交到 Git 仓库。生产项目里建议用环境变量注入本地测试图省事可以直接写配置文件但心里要有数。把这三样东西备齐——Base URL、API Key、Model ID——后面的配置就是填空题。如果你还想了解 opencode 支持哪些 provider 写法可以翻一下接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面把常见客户端的接法都列了。3. 安装 opencode 与可复制配置文件这一节是全文的技术核心命令和配置都给全你按顺序执行即可。3.1 安装 Node 20 并配置镜像opencode 依赖 Node 运行版本要求 20 及以上。先确认版本node -v如果低于 20去 Node 官网下 LTS 版本装上。国内网络下 npm 装包容易慢先换镜像源npm config set registry https://registry.npmmirror.com换完可以npm config get registry确认一下。这一步不是必须但能明显加快后面的安装速度。3.2 全局安装 opencodenpm install -g opencode-ai装完验证opencode --version能打印出版本号就说明 CLI 装好了。如果提示command not found多半是 npm 全局 bin 目录没进 PATH用npm config get prefix看下路径把它加到环境变量里。3.3 写 opencode 配置文件配置文件放在用户目录下的.config/opencode/opencode.json。Windows 是C:\Users\你的用户名\.config\opencode\opencode.jsonmacOS/Linux 是~/.config/opencode/opencode.json。目录不存在就先建mkdir -p ~/.config/opencode然后创建opencode.json内容如下。这里我用 TaoToken 作为 providerbaseURL指向它的 API 根路径apiKey填你刚才复制的统一 Keymodels里放你要用的模型 ID{ $schema: https://opencode.ai/config.json, provider: { taotoken: { name: TaoToken, npm: ai-sdk/openai-compatible, models: { claude-sonnet-4-5: { name: Claude Sonnet 4.5 }, gpt-5: { name: GPT-5 } }, options: { baseURL: https://taotoken.net/api/v1, apiKey: sk-你的TaoToken统一Key } } } }几个字段解释一下npm指定用哪个适配包OpenAI 兼容接口统一用ai-sdk/openai-compatiblemodels的键是模型 ID值是显示名键名必须和 TaoToken 侧的真实模型 ID 一致options.baseURL是接口根options.apiKey是凭证。这三件套——Base URL、Key、Model ID——缺一不可任何一处写错都会在请求时报错。如果你之前配过别的 provider比如本地 lmstudio可以保留opencode 支持多 provider 并存用/connect时选择即可。想禁用某个 provider在顶层加disabled_providers数组把名字填进去。3.4 可选装 oh-my-opencode 插件opencode 支持插件扩展oh-my-opencode 是社区里比较常用的一个提供多 agent 编排。装法npm install oh-my-opencode3.12.3 -g然后在opencode.json顶层加一行plugin: [oh-my-opencode]再在同目录建oh-my-opencode.json把各 agent 的模型指到你的 provider 上比如{ agents: { sisyphus: { model: taotoken/claude-sonnet-4-5 }, oracle: { model: taotoken/claude-sonnet-4-5 }, quick: { model: taotoken/gpt-5 } } }模型写法是provider名/模型ID和上面配置里的 provider 键对应。插件不是跑通首条请求的必需品先跳过也行等基础链路通了再回来加。4. 验证请求curl 打通与 CLI 首条指令配置写完别急着进 CLI先用 curl 确认通道本身是通的这样能把「网络/Key 问题」和「opencode 配置问题」分开排查。4.1 curl 验证请求curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken统一Key \ -d { model: claude-sonnet-4-5, messages: [ {role: user, content: 只回复两个字通了} ] }预期返回是一段 JSON结构大致如下{ id: chatcmpl-xxxx, object: chat.completion, choices: [ { index: 0, message: { role: assistant, content: 通了 }, finish_reason: stop } ], usage: { prompt_tokens: 12, completion_tokens: 2, total_tokens: 14 } }只要choices[0].message.content里有内容就说明 Base URL、Key、Model ID 三件套全对。如果返回 401是 Key 问题返回 404多半是/v1漏了或模型 ID 写错返回一坨 HTML说明 URL 指到了网页而不是 API。4.2 进 CLI 发第一条编码指令curl 通了再进 opencodecd 你的项目目录 opencode进去后输入/connect回车在 provider 列表里选taotoken然后按提示确认模型。接着就可以用自然语言下指令了比如读一下当前目录的 package.json告诉我这个项目用了哪些依赖然后帮我在 README 里加一段安装说明opencode 会读取文件、生成改动并在终端里展示 diff 让你确认。第一次跑建议选个小项目或者空目录指令也别太复杂先确认「读文件—改文件」这条链路顺畅。确认没问题后再上真实项目。如果你打算长期用 opencode 做编码和 Agent 任务可以看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它针对高频编码场景做了额度安排比按次调用更划算。5. 常见报错排查401、local proxy failed 与模型不存在这一节把新手最容易撞的几类错误列出来对照着查。401 UnauthorizedKey 不对或没带上。检查opencode.json里apiKey有没有写全curl 里Authorization: Bearer后面有没有空格漏掉。还有一种情况是 Key 复制时带了换行或空格肉眼看不出来重新复制一遍。local proxy failed / connection refused这类报错通常出现在你配了本地 provider比如指向http://192.168.1.200/v1的 lmstudio但本地服务没起来。如果你只用 TaoToken检查配置里有没有残留的本地 provider 被选中。opencode 的/connect会记住上次选择选错了 provider 就会去连本地地址。解决办法是在/connect里重新选taotoken或者在配置里把不用的 provider 加进disabled_providers。reading choices of undefined这个报错说明返回体里没有choices字段通常是接口返回了错误 JSON 或 HTML。原因一般是baseURL写错——比如写成了https://taotoken.net/api而漏了/v1或者模型 ID 不存在导致服务端返回错误结构。先用第 4 节的 curl 单独验证能快速定位。OAuth / 登录相关报错opencode 某些 provider 走 OAuth 流程如果你在配置里混用了 OAuth 类 provider 和 API Key 类 provider可能会在启动时提示授权失败。纯 API Key 接入TaoToken 就是这种不涉及 OAuth遇到这类提示检查是不是选错了 provider。模型不存在 / model not foundmodels里的键名必须和 TaoToken 侧的真实模型 ID 完全一致大小写、连字符都不能差。去模型对话页面确认一下准确 ID 再填。排查顺序建议固定成先 curl 验证通道 → 再检查 opencode.json 的 provider 选择 → 最后看模型 ID。这样能把问题范围一层层缩小比盲目改配置高效得多。需要对照更多客户端接法的话接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有完整参数说明。6. 把 Key 管好让 opencode 长期可用跑通第一条请求只是开始真正影响体验的是后面怎么管这套配置。我的做法是把 Key 从配置文件里抽出来用环境变量注入opencode.json里只留baseURL和模型列表。这样换 Key 不用改配置也不怕误提交。opencode 支持在options里读环境变量具体写法参考官方 schema 的$schema提示。另一个实用技巧是给不同项目配不同模型轻量重构用快模型复杂推理用强模型在models里都列上用/connect或指令里指定即可。TaoToken 的统一 Key 好处就在这——一个 Key 覆盖多个模型不用为每个模型单独申请凭证。最后提醒一句opencode 会读写你当前目录的文件第一次在重要项目里用之前先确保代码有 Git 提交出问题能回滚。养成这个习惯AI 编码工具才能真正帮你提速而不是添乱。
