OpenCode 配置中转站模型:接入 apimodels.app
OpenCode 是开源的编码智能体,终端、桌面和网页都能用。它内置的模型目录来自 models.dev,目前那里没有 apimodels.app(2026-11-18 查),所以按自定义 provider 接入:在 opencode.json 里加一个 OpenAI 兼容的 provider,地址 https://api.apimodels.app/v1,一把 key 用 GPT、Claude、DeepSeek 等模型。OpenCode 2.x 和 1.x 的配置写法不同,下面两套都给,另附 MCP 接入和常见报错。
需要的配置值
| 接口地址 | https://api.apimodels.app/v1 |
| 协议包(2.x) | @opencode/ai/providers/openai-compatible |
| 协议包(1.x) | @ai-sdk/openai-compatible |
| API key | apimodels 控制台创建的 sk_… key,放在环境变量 APIMODELS_API_KEY |
| 模型 ID | gpt-6.2-sol · claude-fable-5-2 · deepseek-v4.1-flash |
第 1 步:看 OpenCode 是 2.x 还是 1.x
运行 opencode --version。显示 opencode v2.x 的用 providers 写法;显示 1.x 的用 provider 写法。npm 包 opencode-ai 目前装的是 1.x(2026-11-18 为 1.19.6);@opencode/cli、opencode.ai/v2/install 安装脚本和 OpenCode Desktop 2.x 是 2.x。
第 2 步:把 API key 放进环境变量
# macOS / Linux (add it to ~/.zshrc or ~/.bashrc to keep it)
export APIMODELS_API_KEY="sk_…your_apimodels_key…"
# Windows (PowerShell or cmd), then open a new terminal
setx APIMODELS_API_KEY "sk_…your_apimodels_key…"没有 key 就到 控制台 → API Keys 创建。配置文件只引用变量名,key 不写进 opencode.json。环境变量要对启动 OpenCode 的那个进程可见:改完 shell 配置后重开终端再启动 OpenCode。
第 3 步:写 opencode.json
全局配置放在 ~/.config/opencode/opencode.json,只对某个项目生效就放项目根目录的 opencode.json。已有配置的话,把 providers(或 provider)这一段合并进去。
OpenCode 2.x
// ~/.config/opencode/opencode.json — OpenCode 2.x
{
"$schema": "https://opencode.ai/config.json",
"model": "apimodels/gpt-6.2-sol",
"providers": {
"apimodels": {
"name": "apimodels.app",
"env": ["APIMODELS_API_KEY"],
"package": "@opencode/ai/providers/openai-compatible",
"settings": {
"baseURL": "https://api.apimodels.app/v1"
},
"models": {
"gpt-6.2-sol": {
"name": "GPT-6.2 Sol",
"limit": { "context": 1050000, "output": 128000 }
},
"claude-fable-5-2": {
"name": "Claude Fable 5.2",
"limit": { "context": 1000000, "output": 128000 }
},
"deepseek-v4.1-flash": {
"name": "DeepSeek V4.1 Flash",
"limit": { "context": 1000000, "output": 128000 }
}
}
}
}
}OpenCode 1.x
// ~/.config/opencode/opencode.json — OpenCode 1.x
{
"$schema": "https://opencode.ai/config.json",
"model": "apimodels/gpt-6.2-sol",
"provider": {
"apimodels": {
"npm": "@ai-sdk/openai-compatible",
"name": "apimodels.app",
"options": {
"baseURL": "https://api.apimodels.app/v1",
"apiKey": "{env:APIMODELS_API_KEY}"
},
"models": {
"gpt-6.2-sol": {
"name": "GPT-6.2 Sol",
"limit": { "context": 1050000, "output": 128000 }
},
"claude-fable-5-2": {
"name": "Claude Fable 5.2",
"limit": { "context": 1000000, "output": 128000 }
},
"deepseek-v4.1-flash": {
"name": "DeepSeek V4.1 Flash",
"limit": { "context": 1000000, "output": 128000 }
}
}
}
}
}- models 下的键就是发给我们的模型 ID,要和模型页上的 ID 逐字一致;在 OpenCode 里引用时写成 apimodels/<模型 ID>。
- limit 告诉 OpenCode 上下文还剩多少;不写时 2.x 按 200K 上下文、32K 输出处理。
- 1.x 也可以不写 apiKey:在 OpenCode 里运行 /connect(或命令行 opencode auth login),拉到最下面选 Other,provider id 填 apimodels,再粘贴 key。id 必须和配置里的 provider 名一致。
- 2.x 也能读 1.x 的 provider 写法,但早期 2.x(如 2.1.4)读不到;新写的配置直接用 providers。
第 4 步:在 /models 里选模型
重启 OpenCode,运行 /models,选 apimodels 下的模型。编码智能体靠函数调用读写文件,下面三个都支持工具调用。要加别的模型,把它的 ID 加进 models;完整列表见 模型目录。价格以各模型页为准。
| GPT-6.2 Sol | gpt-6.2-sol | 日常写代码的默认选择;1.05M 上下文,支持函数调用;不接受 reasoning_effort: none。 |
| Claude Fable 5.2 | claude-fable-5-2 | 长流程、跨文件的大改动;1M 上下文,128K 输出,思考常开。 |
| DeepSeek V4.1 Flash | deepseek-v4.1-flash | 响应快,适合大量小改动和问答;1M 上下文,支持工具调用,按 DeepSeek 峰谷时段计价。 |
设置推理强度(reasoning effort)
自定义 provider 的模型不在 OpenCode 的内置目录里,所以没有现成的推理档位,要自己在模型下写:2.x 用 settings 和 variants 数组,1.x 用 options 和 variants 对象。GPT-6.2 Sol 可用 low、medium、high,不接受 none。
// 2.x: inside providers.apimodels.models
"gpt-6.2-sol": {
"name": "GPT-6.2 Sol",
"settings": { "reasoningEffort": "medium" },
"variants": [
{ "id": "low", "settings": { "reasoningEffort": "low" } },
{ "id": "high", "settings": { "reasoningEffort": "high" } }
]
}
// pick a variant per run: opencode run --model apimodels/gpt-6.2-sol#high "…"// 1.x: inside provider.apimodels.models
"gpt-6.2-sol": {
"name": "GPT-6.2 Sol",
"options": { "reasoningEffort": "medium" },
"variants": {
"low": { "reasoningEffort": "low" },
"high": { "reasoningEffort": "high" }
}
}接入 apimodels MCP:在 OpenCode 里生成图片和视频
上面的 provider 只管对话模型。图片、视频、语音模型通过我们的远程 MCP 服务器 https://api.apimodels.app/mcp 交给 OpenCode 调用(generate_image、generate_video、text_to_speech 等)。它支持 OAuth 登录:OpenCode 对远程服务器默认走 OAuth,浏览器里登录 apimodels.app 点「授权」即可。
# OpenCode 2.x: writes mcp.servers.apimodels into your global config
opencode mcp add apimodels --global --url https://api.apimodels.app/mcp
# then sign in once: run /mcps inside OpenCode and pick apimodels, or
opencode mcp auth apimodels// OpenCode 1.x: add to opencode.json, then run: opencode mcp auth apimodels
"mcp": {
"apimodels": {
"type": "remote",
"url": "https://api.apimodels.app/mcp",
"timeout": 120000
}
}1.x 里 timeout 设成 120000(毫秒):视频工具每次最多等 50 秒再交回任务号,留出余量。不想走浏览器授权,就关掉 OAuth、在请求头里带 key:
// No browser sign-in: send your key instead (2.x: under mcp.servers; 1.x: under mcp)
"apimodels": {
"type": "remote",
"url": "https://api.apimodels.app/mcp",
"oauth": false,
"headers": { "Authorization": "Bearer {env:APIMODELS_API_KEY}" }
}工具列表和计费见 /docs/mcp。生成按各模型页的价格扣费,失败不扣费。
用 CC Switch 一键导入
CC Switch 可以管理 OpenCode 的 provider。不想手写 opencode.json 的话,用它一键把 apimodels 加进 OpenCode,步骤见 CC Switch 接入指南。
常见报错
| 症状 | 原因 / 修法 |
|---|---|
| Custom providers are unavailable on this server | 来自 2.x 桌面版 / 网页版设置里的「添加自定义 provider」弹窗,它的保存功能在已发布的 2.x 里还没做完,和地址、key 无关(官方 issue anomalyco/opencode#50650,2026-11-18 仍未关闭)。直接把上面的 providers 配置写进 ~/.config/opencode/opencode.json 即可。 |
| /models 里看不到 apimodels | 版本和写法对不上(2.x 用 providers,1.x 用 provider)、JSON 有语法错误,或改完没重启(2.x 也可运行 opencode reload)。用 opencode models(1.x 可加 apimodels)检查是否列出 apimodels/…。 |
| Model unavailable: apimodels/… | 选的模型不在 models 里,或键名拼错。把模型 ID 原样加进 models。 |
| 401 / Invalid or missing API key | OpenCode 进程读不到 APIMODELS_API_KEY,或 key 已删除。重开终端再启动,或到控制台新建 key。 |
| 404 | baseURL 写错。必须是 https://api.apimodels.app/v1,不要自己加 /chat/completions。 |
| 400 / 模型名报错 | 模型 ID 拼错或不是对话模型。对照模型页的 ID,或 GET https://api.apimodels.app/v1/models 查完整列表。 |
依据(2026-11-18 核对):OpenCode 官方文档 Providers (2.x) · Providers (1.x) · MCP servers · Models · issue #50650。OpenCode 是 anomalyco 的开源项目,与 apimodels.app 没有隶属关系。
常见问题
OpenCode 怎么配置中转站模型(比如 GPT)?
把中转站加成 opencode.json 里的自定义 provider:接口地址填 https://api.apimodels.app/v1,key 用 apimodels 的 sk_… key,models 里写要用的模型 ID,比如 gpt-6.2-sol、claude-fable-5-2、deepseek-v4.1-flash。OpenCode 2.x 写在 providers 下,package 用 @opencode/ai/providers/openai-compatible,地址放 settings.baseURL;1.x 写在 provider 下,npm 用 @ai-sdk/openai-compatible,地址放 options.baseURL。重启后在 /models 里选 apimodels/gpt-6.2-sol。GPT、Claude、DeepSeek 都用同一个地址和同一把 key。
OpenCode 配置自己的模型,opencode.json 怎么写?1.x 和 2.x 一样吗?
不一样。OpenCode 2.x(官方当前文档对应的版本)用 providers,每个 provider 写 package、settings.baseURL、env 和 models;1.x 用 provider,写 npm、options.baseURL、options.apiKey 和 models。运行 opencode --version:显示 opencode v2.x 用 providers,显示 1.x 用 provider。2.x 也能读旧的 provider 写法,但 2.1.4 等早期 2.x 读不到,新配置建议直接用 providers。models 下的键就是发给接口的模型 ID,要逐字一致。本页两套配置都在 OpenCode 1.19.6 和 2.3.2 上加载通过。
OpenCode 自定义 provider 的 API key 放在哪?
推荐放环境变量,比如 export APIMODELS_API_KEY="sk_…"。2.x 在 provider 里写 "env": ["APIMODELS_API_KEY"];1.x 在 options 里写 "apiKey": "{env:APIMODELS_API_KEY}"。1.x 也可以运行 /connect(或 opencode auth login),选 Other,provider id 填 apimodels 再粘贴 key,key 存在 ~/.local/share/opencode/auth.json,id 要和配置里的 provider 名一致。环境变量必须对启动 OpenCode 的进程可见,设置后要重开终端。
OpenCode 提示 Custom providers are unavailable on this server 怎么办?
这条提示来自 OpenCode 2.x 桌面版和网页版设置里的「添加自定义 provider」弹窗:它的保存功能在已发布的 2.x 里还没做完,不管填什么地址和 key 都会报这句(官方仓库 issue #50650,2026-11-18 仍未关闭)。绕过方法是自己把 providers 配置写进 ~/.config/opencode/opencode.json,同一个服务器就能加载,模型会出现在 /models 里。
OpenCode 自定义 provider 或模型不显示怎么办?
按顺序查:配置写法和版本对得上(2.x 用 providers,1.x 用 provider);JSON 能解析,文件在 ~/.config/opencode/opencode.json 或项目根目录的 opencode.json;每个模型都按原样 ID 列在 models 里;改完重启了 OpenCode(2.x 也可以运行 opencode reload)。然后运行 opencode models(1.x 用 opencode models apimodels),看有没有 apimodels/… 。报 Model unavailable: apimodels/x,说明 x 不在 models 里。
OpenCode 自定义 provider 怎么设置推理强度(reasoning effort)?
自定义 provider 的模型不在 OpenCode 的内置目录里,没有现成的推理档位,要在模型下自己写。2.x 加 "settings": { "reasoningEffort": "high" },或在 variants 数组里定义 low、high 两档,用 apimodels/gpt-6.2-sol#high 选;1.x 加 "options": { "reasoningEffort": "high" },或写 variants 对象。GPT-6.2 Sol 可用 low、medium、high,不接受 none。
OpenCode 怎么配置 MCP?能接 apimodels 生成图片和视频吗?
可以。apimodels 的远程 MCP 地址是 https://api.apimodels.app/mcp,提供 generate_image、generate_video、text_to_speech 等工具。2.x 运行 opencode mcp add apimodels --global --url https://api.apimodels.app/mcp,再在 /mcps 里或用 opencode mcp auth apimodels 登录授权;1.x 在 opencode.json 的 mcp 下加 { "type": "remote", "url": "https://api.apimodels.app/mcp" },再运行 opencode mcp auth apimodels。不想走浏览器授权,就设 "oauth": false,并在 headers 里带 "Authorization": "Bearer {env:APIMODELS_API_KEY}"。生成按各模型页价格扣费,失败不扣费。