🚀 OpenCode 自定义模型终极指南：一份配置文件搞定 GPT / Claude / Gemini
很多人 OpenCode 用不好，不是工具不行，而是模型没配对。
本文将带你从 0 到 1，彻底搞懂 OpenCode 如何接入自定义大模型，并给出 实测可用的完整配置方案。
适合人群：
想在 OpenCode 中接入 自建 / 代理 / 中转模型服务
需要同时使用 GPT、Claude、Gemini 的开发者
希望打造 多模型统一调用入口 的工程师
一、为什么你配的 OpenCode 模型“用不了”？
在社区里，关于 OpenCode 的常见问题基本集中在三点：
模型配置了，但 列表里不显示
调用时报错，但 不知道错在哪
API Key / baseURL 明明没错，却始终请求失败
👉 根本原因只有一个：没搞清楚 provider 机制。
二、OpenCode 的核心设计：Provider 才是灵魂
在 OpenCode 中：
Model ≠ API
Model ≠ SDK
Model = Provider + SDK + 配置
也就是说：
OpenCode 并不是“直接支持某个模型”，
而是通过 provider（模型提供方） 来桥接各种 SDK。
三、配置文件在哪？99% 的人第一步就找错了
默认配置路径：
~/.config/opencode/opencode.json
也可以通过环境变量 自定义：
export OPENCODE_CONFIG_DIR=~/.opencode
export OPENCODE_CONFIG=~/.opencode/opencode.json
四、实测可用的完整配置示例（建议直接收藏）
支持 GPT / Claude / Gemini 3.5，Token173中转服务通用：
{
"$schema": "https://opencode.ai/config.json",
"theme": "opencode",
"autoupdate": true,
"tools": {
"write": true,
"bash": true,
"read": true,
"edit": true,
"glob": true,
"grep": true
},
"permission": {
"webfetch": "allow",
"bash": "ask",
"edit": "ask",
"skill": "allow"
},
"provider": {
"token173-openai": {
"npm": "@ai-sdk/openai-compatible",
"name": "Token173 OpenAI",
"options": {
"baseURL": "https://token173.com/v1",
"apiKey": "{env:TOKEN173_API_KEY}"
},
"models": {
"gpt-5": { "id": "gpt-5", "name": "GPT-5" },
"gpt-5.1": { "id": "gpt-5.1", "name": "GPT-5.1" }
}
},
"token173-anthropic": {
"npm": "@ai-sdk/anthropic",
"name": "Token173 Claude",
"options": {
"baseURL": "https://token173.com/anthropic/v1",
"apiKey": "{env:TOKEN173_API_KEY}"
},
"models": {
"claude-sonnet-4.5": {
"id": "claude-sonnet-4.5",
"name": "Claude Sonnet 4.5"
}
}
},
"token173-gemini": {
"npm": "@ai-sdk/google",
"name": "Token173 Gemini",
"options": {
"baseURL": "https://token173.com/gemini/v1beta",
"apiKey": "{env:TOKEN173_API_KEY}"
},
"models": {
"gemini-3.5-flash": {
"id": "gemini-3.5-flash",
"name": "Gemini 3.5 Flash"
}
}
}
}
}
五、provider 字段最容易配错的 3 个点
1️⃣ npm ：决定你“用哪套协议”
"npm": "@ai-sdk/openai-compatible"
含义：
接口 兼容 OpenAI
不要求官方 OpenAI
2️⃣ options：90% 的报错来源
"options": {
"baseURL": "https://token173.com/v1",
"apiKey": "{env:TOKEN173_API_KEY}"
}
常见错误：
忘记 /v1
HTTPS 证书问题
API Key 写死在配置中
3️⃣ models ：ID 必须和真实模型一致
"models": {
"gpt-5": {
"id": "gpt-5",
"name": "GPT-5"
}
}
id：真实请求模型名
name：UI 显示名
六、API Key 的正确管理方式
export TOKEN173_API_KEY="your_api_key_here"
配置中引用：
"apiKey": "{env:TOKEN173_API_KEY}"
优势：
安全
可多环境切换
适合版本控制
七、常见问题速查表
模型不显示
JSON 格式错误
provider 名重复
models 未定义
请求失败
baseURL 不通
API Key 未生效
SDK 与接口不兼容
Claude / Gemini 404
baseURL 路径错误（非对应路由地址）
八、总结
OpenCode 真正强的不是支持某个模型，
而是支持 无限模型的统一接入。
一次配置，多模型共存
非常适合中转 / 私有化 / 企业内部部署
