1. 装完 OpenCode CLI 之后卡在哪一步如果你刚在 Windows Terminal 里敲完npm i -g opencode-ai看到命令行提示安装成功然后输入opencode能进到交互界面——恭喜你只完成了「装好」还没到「跑通」。真正让新手卡住的是接下来这一步怎么把 OpenCode CLI 接到一个能用的模型通道上让它真的能回你话。OpenCode CLI 本身是一个终端里的编码助手外壳它负责读你的项目文件、维护对话上下文、执行你给的指令但模型推理这件事它自己不做得靠外部 API。默认配置下它会去找官方推荐的模型服务可对国内开发者来说注册、绑卡、拿 Key 这一串流程本身就够劝退。更现实的做法是用一个统一的 API 通道把 Key 和地址配好让 OpenCode 把请求发过去剩下的它自己处理。这篇就是写给刚装完 OpenCode CLI、准备做首次配置的人。我会带你在 Windows Terminal 里改settings.json、写AGENTS.md然后用一次最小对话请求验证 TaoToken 的统一 Key/API 通道到底通没通。目标很明确从「装好」推进到「跑通」中间不绕路。适合谁看Windows 上用 npm 装过 Node 工具、能看懂 JSON、但没配过 OpenCode 模型通道的开发者。如果你连 npm 都还没装先去把 Node.js LTS 装上再回来跟着做。2. 前置准备TaoToken 的 Key 和 API 地址在动 OpenCode 的配置文件之前先把两样东西拿到手一个 API Key一个 API Base URL。TaoToken 在这里扮演的角色是统一通道——你不需要为每个模型单独注册账号拿一个 Key 就能在多个模型之间切换OpenCode 那边只认这一个地址。拿 Key 的入口在控制台登录后进 API Keys 页面创建一个。创建时给它起个能认出来的名字比如opencode-win方便以后在多个工具之间区分。Key 只在创建时完整显示一次复制下来先存到临时地方等会儿要粘进配置文件。API 地址这块OpenCode 需要的是兼容 OpenAI 格式的 base URL。TaoToken 的 API 入口是https://taotoken.net/api注意这里不带任何查询参数配置里就写这个根地址具体路径由 OpenCode 自己拼。如果你之前配过其他工具可能会习惯在地址后面加/v1OpenCode 的配置方式不太一样后面我会在settings.json里写清楚。提示Key 不要直接写进会提交到 Git 的文件里。OpenCode 的全局配置放在用户目录下不在项目仓库里相对安全但如果你要把配置分享给别人记得先把 Key 换成占位符。另外建议顺手确认一下 npm 全局安装路径在 PATH 里。在 Windows Terminal 里跑npm config get prefix把输出的路径加到系统环境变量 PATH 中否则opencode命令可能提示找不到。这一步很多人装完就忘了结果以为是 OpenCode 的问题其实是 PATH 没配。3. 可复制配置settings.json 与 AGENTS.md 骨架OpenCode 的配置分两层一层是模型通道相关的settings.json一层是交互规则相关的AGENTS.md。前者决定请求发到哪、用哪个模型后者决定它怎么跟你说话。两个文件都放在用户目录下的.config/opencode/里Windows 上完整路径是C:\Users\你的用户名\.config\opencode\。如果这个目录不存在手动建一下。先看settings.json。这是最小可用的骨架把apiKey换成你刚拿到的 Key{ provider: { taotoken: { type: openai, baseURL: https://taotoken.net/api, apiKey: sk-你的Key粘这里, models: { default: { name: claude-sonnet-4-20250514, maxTokens: 8192 } } } }, defaultProvider: taotoken, defaultModel: default }几个参数说明一下。type写openai是因为 TaoToken 的接口兼容 OpenAI 的请求格式OpenCode 会按这个协议去发请求。baseURL就是上一步说的根地址不要加/v1。models下面可以挂多个模型这里先配一个默认的name填你想用的模型标识具体可用的模型名在 TaoToken 的文档页能查到。maxTokens控制单次回复上限8192 对日常编码够用遇到长文件分析可以调大。然后是AGENTS.md。这个文件是 OpenCode 的全局交互规则每次启动都会读。骨架如下# 全局交互规则 ## 核心要求 - 语言所有思考过程和回复使用中文 - 思考过程用中文描述推理步骤 - 回复语言用中文回答所有问题 ## 交互习惯 - 使用中文标点 - 解释技术概念时用通俗说法 - 代码注释可用英文 ## 输出格式 - 清晰的标题和分段 - 代码块使用语言标识 - 技术术语首次出现时给简短解释把这两个文件存好OpenCode 下次启动就会按这个配置走。如果你项目里还有自己的AGENTS.md项目级的会覆盖全局的同名规则这点在设计多项目工作流时挺有用。4. 验证请求一次最小对话跑通通道配置写完别急着开大项目先用一条最小请求验证通道。打开 Windows Terminal随便进一个空目录输入opencode回车。首次启动它会读配置、加载 AGENTS.md界面上应该能看到当前 provider 是taotoken、模型是你配的那个。然后发一条最简单的指令比如用一句话说明这个目录里有什么文件如果通道通了它会先列目录、再用中文回你一句话。整个过程你能看到它调用了工具、发了请求、拿到响应。这一步成功说明 Key、baseURL、模型名三样都对上了。想更直接地验证 API 层可以绕过 OpenCode用 curl 打一次 TaoToken 的接口curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复通道正常}] }返回 JSON 里choices[0].message.content有内容就说明 Key 和地址没问题。如果 curl 通了但 OpenCode 不通问题就在 OpenCode 的配置格式上回去检查settings.json的字段名有没有拼错。实测下来最容易出问题的是baseURL多写了/v1或者type写成了别的协议名。这两个地方对不上OpenCode 会直接报连接错误而不是给你一个友好的提示。5. 本篇常见错排查报错一command not found: opencodenpm 全局安装路径没进 PATH。跑npm config get prefix把结果加到系统环境变量重开 Windows Terminal。报错二401 UnauthorizedKey 错了或者没带上。检查settings.json里apiKey字段有没有多余空格Key 是不是完整复制。如果 Key 是在别的工具里用过的确认它还有效。报错三404 Not FoundbaseURL写错了。确认是https://taotoken.net/api后面不要加/v1或/chat/completionsOpenCode 会自己拼路径。报错四模型名无效models.default.name填的模型标识在 TaoToken 那边不存在。去文档页核对可用模型列表注意大小写和版本号后缀。报错五OpenCode 启动后不读 AGENTS.md文件路径不对。确认是C:\Users\你的用户名\.config\opencode\AGENTS.md不是项目目录下的。Windows 上.config是隐藏文件夹资源管理器里要开「显示隐藏项目」才能看到。报错六请求超时网络层的问题不是配置问题。先确认 curl 那条命令能不能通能通就是 OpenCode 版本太旧npm update -g opencode-ai升一下。6. 跑通之后把通道用起来通道验证通过之后OpenCode CLI 就算真正可用了。接下来你可以做几件事让它更顺手。一是把常用的模型都配进settings.json的models里用的时候在 OpenCode 界面里切换不用每次改配置。二是把AGENTS.md按自己的习惯调比如加上「回复尽量简短」「代码示例优先用 TypeScript」这类偏好它会一直遵守。如果你打算长期在终端里做编码和 Agent 任务可以了解一下 Coding Plan 这类按周期计费的方案比按量付费更适合高频使用。入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 配置方式和单 Key 一样只是计费模型不同。日常想快速验证某个模型回得对不对不用开 OpenCode直接去模型对话页面发一条就行https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。要管理多个 Key 或者看用量在控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。Key 的创建和轮换在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。配置字段有疑问就翻接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。最后说个我踩过的坑改完settings.json之后OpenCode 不会自动重载得退出重进才生效。有次我改完模型名直接发指令一直报模型无效折腾了十分钟才想起来没重启。你改配置之后记得先退出再进能省不少排查时间。
