接入指南
OpenCode
终端里的 AI 编码代理，支持任意 OpenAI 兼容服务；配置和密钥分两个文件存，密钥不会误进版本库。
- 01
安装并验证
用官方脚本或 npm 全局安装，装完运行版本号确认。Windows 上 OpenCode 更适合在 WSL 里跑，那样配置也走 WSL 内的 Linux 路径。
# 官方脚本（macOS / Linux / WSL） curl -fsSL https://opencode.ai/install | bash # 或用 npm（全平台） npm install -g opencode-ai # 验证 opencode --version - 02
找到配置文件
OpenCode 把「服务商定义」和「密钥」分开放：opencode.json 存 provider 定义（支持 .jsonc、可写注释），密钥单独放在 auth.json。下面是 opencode.json 的位置，也可以在项目根目录放一份只对该项目生效。
- Windows
%USERPROFILE%\.config\opencode\opencode.json- macOS / Linux
~/.config/opencode/opencode.json- 项目级
项目根目录/opencode.json
- 03
定义服务商
在 opencode.json 里加一个 provider（注意是单数 provider，不是 providers）。用 @ai-sdk/openai-compatible 适配器，baseURL 走 OpenAI 兼容格式、要带 /v1；models 里列出要用的模型 id。密钥不要写在这里。
{ "$schema": "https://opencode.ai/config.json", "provider": { "xylemnode": { "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "https://api.xylemnode.com/v1" }, "models": { "gpt-5.6-sol": {} } } } } - 04
填入密钥
密钥放进独立的 auth.json，键名要和上面的 provider 名一致。最省事的是运行 opencode auth login 让它自动写入；也可以手动编辑（macOS/Linux 在 ~/.local/share/opencode/auth.json）。
{ "xylemnode": { "type": "api", "key": "sk-你的密钥" } } - 05
选模型并测试
重启 OpenCode，用 /models 看可用模型，再用 /model 切到 XylemNode 的模型，发一条消息确认通路。
/models /model xylemnode/gpt-5.6-sol
几个易错点
① 键名用 provider（单数），写成 providers 会报错。 ② baseURL 必须以 /v1 结尾。 ③ 模型不在 /models 里，多半是 models 的 id 和服务端对不上，或改完没重启。 ④ 提示 npm 包找不到时，在 ~/.config/opencode/ 目录里跑一次 npm install。
常见问题
OpenCode 里 provider 配好了，模型却不出现，或报 ProviderModelNotFoundError？
最常见的原因是 provider 块里只写了 npm、没写 models。仓库里有一条已确认的行为：provider 级的 npm 字段在没有同时配置 models 时会被静默忽略——不会报错，只是这个服务商等于没生效。所以 models 里必须显式列出你要用的模型 id。另外记得两个文件都要到位：provider 定义在 opencode.json，密钥单独在 auth.json，只配一个不行。