最近我在整理 AI 编程工具的模型接入方式，发现 OpenCode 有个地方很容易把人绕进去：它虽然支持大量模型提供商，但“填进 API Key”和“把模型配置出来”其实是两件事。
不少人执行完 /connect，以为模型就算接好了，结果打开 /models 什么也没有；还有人照着 OpenAI 的配置抄了一遍，接口一直报 404。
问题通常不在 Key，而在提供商 ID、API 协议和模型 ID 没对齐。
这篇不展开讲 OpenCode 怎么安装，只说第三方模型怎么接。以下配置依据 OpenCode 官方文档截至 2026 年 9 月的版本整理。
先判断你的模型属于哪一种
OpenCode 接入第三方模型，基本分为两类。
第一类是它已经内置的提供商，比如 OpenAI、Anthropic、DeepSeek、OpenRouter、Moonshot AI、MiniMax、Groq、Ollama 等。
这类最省事，通常只要在 OpenCode 的 TUI 中执行：
/connect
选择对应提供商，填入 API Key，再执行：
/models
选中模型即可。
第二类是 OpenCode 列表里没有，但提供 OpenAI 兼容接口的服务。比如公司内部部署的模型网关、自建推理服务，或者某个只给了 baseURL、API Key 和模型 ID 的聚合平台。
这种情况除了保存凭据，还需要手动配置 opencode.json。
我一般先问接口方三个问题：
- 请求走的是
/v1/chat/completions，还是/v1/responses； - 实际模型 ID 是什么；
- 是否完整支持流式输出和 tool calling。
这三个问题没确认，后面很容易出现“能聊天，但不能改代码”的半接通状态。
内置提供商这样接
先启动 OpenCode：
opencode
进入界面后输入：
/connect
找到对应提供商，按提示完成登录或填写 API Key。随后输入：
/models
选择要使用的模型。
如果希望每次进入项目都默认使用它，可以在项目根目录创建 opencode.json：
{
"$schema": "https://opencode.ai/config.json",
"model": "deepseek/deepseek-chat"
}
这里的模型名称只是格式示例，实际值要以 /models 中显示的 ID 为准。
OpenCode 使用的完整模型 ID 格式是：
provider_id/model_id
前半段是提供商 ID，后半段才是接口真正使用的模型 ID。两者不要混在一起猜。
未收录的第三方平台这样接
假设我拿到了一组信息：
Base URL：https://api.example.com/v1
API Key：sk-xxxxxxxx
模型 ID：example-coder
先在 OpenCode 中执行：
/connect
向下找到 Other，然后输入一个自定义提供商 ID，比如：
example
接着填入 API Key。
这里有个细节：/connect 只负责保存凭据，并不会自动知道这个平台有哪些模型、接口地址是什么。因此还要在项目根目录创建 opencode.json：
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"example": {
"npm": "@ai-sdk/openai-compatible",
"name": "Example AI",
"options": {
"baseURL": "https://api.example.com/v1"
},
"models": {
"example-coder": {
"name": "Example Coder"
}
}
}
},
"model": "example/example-coder"
}
配置中的几个名字分别代表：
example：自定义提供商 ID，必须与/connect时填写的一致；npm：OpenCode 调用该接口使用的 AI SDK 包；baseURL：模型服务的 API 地址；example-coder：服务端认可的真实模型 ID；name：OpenCode 界面里的显示名称，可以自定义；model：启动时默认使用的完整模型 ID。
保存后重新进入 OpenCode，再执行 /models，正常情况下就能看到刚才添加的模型。
npm 这一行不要随便抄
这是我认为最容易配错的地方。
如果第三方平台使用传统的 OpenAI 兼容接口：
POST /v1/chat/completions
配置一般写：
"npm": "@ai-sdk/openai-compatible"
如果平台明确使用 OpenAI Responses API：
POST /v1/responses
则应使用：
"npm": "@ai-sdk/openai"
接口协议选错后，常见表现是 Base URL 和 Key 看着都对，但请求仍然报 404、参数不兼容，或者流式输出异常。
所以我现在接新平台时，不会只问一句“是不是 OpenAI 兼容”。我会直接确认它兼容的是哪个端点。这个细节能省掉不少排查时间。
API Key 不要直接写进项目配置
OpenCode 允许在 options 中直接配置 apiKey，但如果 opencode.json 会提交到 Git，我不建议把明文密钥放进去。
可以改成环境变量：
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"example": {
"npm": "@ai-sdk/openai-compatible",
"name": "Example AI",
"options": {
"baseURL": "https://api.example.com/v1",
"apiKey": "{env:EXAMPLE_API_KEY}"
},
"models": {
"example-coder": {
"name": "Example Coder"
}
}
}
},
"model": "example/example-coder"
}
启动前设置环境变量：
export EXAMPLE_API_KEY="sk-xxxxxxxx"
opencode
如果通过 /connect 保存凭据，OpenCode 会把认证信息放在：
~/.local/share/opencode/auth.json
项目配置里只保留提供商、接口地址和模型信息即可。
本地模型也是同一套逻辑
LM Studio、Ollama、llama.cpp 这类本地推理服务，只要暴露了 OpenAI 兼容接口，也可以按相同方式接入。
以 Ollama 为例：
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama Local",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"qwen3-coder": {
"name": "Qwen3 Coder"
}
}
}
},
"model": "ollama/qwen3-coder"
}
这里最重要的不是显示名称，而是 models 下面的键必须和本地服务返回的模型 ID 对得上。
如果不确定，可以先检查模型列表接口：
curl http://localhost:11434/v1/models
服务端返回什么 ID，配置里就写什么，不要凭模型的商品名猜。
需要自定义请求头时怎么写
有些企业网关除了 API Key，还要求额外的租户 ID、项目 ID或自定义鉴权头，可以放在 options.headers 中：
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"company-gateway": {
"npm": "@ai-sdk/openai-compatible",
"name": "Company Gateway",
"options": {
"baseURL": "https://gateway.example.com/v1",
"apiKey": "{env:COMPANY_API_KEY}",
"headers": {
"X-Project-ID": "{env:COMPANY_PROJECT_ID}"
}
},
"models": {
"coder-model": {
"name": "Company Coder"
}
}
}
}
}
如果网关要求的不是标准 Bearer 鉴权，也可以按平台文档配置对应请求头。不过鉴权信息仍建议走环境变量，不要直接写死。
配完以后，我会做三步验证
第一步，检查 OpenCode 是否识别到了凭据：
opencode auth list
第二步，进入 OpenCode 执行：
/models
确认自定义提供商和模型是否出现。
第三步，不要只问一句“你是谁”。我通常会让模型执行一个很小的代码任务，比如：
读取当前目录结构，找到 package.json，并告诉我项目使用了哪个前端框架。先不要修改文件。
这一步能同时检查：
- 模型是否能正常返回；
- 上下文是否传递完整；
- tool calling 是否可用；
- 模型能否正确处理工具结果。
有些模型普通对话完全正常，一到读文件、调用终端或者提交修改就失败。这种情况通常不是 OpenCode 没接通，而是模型本身或中转平台没有完整支持工具调用。
常见报错从哪里查
/models 中看不到自定义模型
先检查三个 ID：
/connect时填写的提供商 ID；provider下的键名；- 默认模型中
/前面的提供商 ID。
这三个必须一致。
请求返回 401
优先检查 API Key 是否有效，以及凭据是否保存到了正确的提供商 ID。不要只反复重新粘贴 Key，先用：
opencode auth list
确认 OpenCode 实际识别到的认证项。
请求返回 404
大多是 baseURL 或接口协议不对。
重点看这两项：
- Base URL 是否需要包含
/v1； - 服务走的是
/chat/completions还是/responses。
如果协议不同，只改 URL 往往不够，npm 对应的 SDK 包也要一起改。
可以聊天，但不会调用工具
这种情况优先怀疑模型能力和中转兼容性。
OpenCode 是编码 Agent，不是普通聊天窗口。模型至少要稳定支持结构化 tool calling，才能完成读取文件、执行命令、修改代码等操作。
如果平台只兼容文本对话，或者在中转过程中丢失了工具调用字段，那么接入成功也只能算“能说话”，不能算真正可用。
长任务做到一半突然丢上下文
自定义模型可以补充上下文和输出限制：
"models": {
"example-coder": {
"name": "Example Coder",
"limit": {
"context": 128000,
"output": 32000
}
}
}
这两个数字必须来自模型或服务商的真实说明，不能为了显示更大的上下文随便填写。它们会影响 OpenCode 对剩余上下文空间的判断。
写在最后
OpenCode 接第三方模型，表面上是在填一个 API 地址，实际要对齐四层东西：
凭据
→ 提供商 ID
→ API 协议
→ 模型 ID
我自己的排查顺序也是按这四层走。
先确认 Key 是否被识别，再确认 /connect 和配置里的提供商 ID 是否一致，然后核对 /chat/completions 与 /responses，最后才看模型 ID和工具调用能力。
只要这四层能一一对上，大多数 OpenAI 兼容模型都能接入。反过来，如果上来就反复改 JSON，通常只会把问题越改越乱。
还有一点容易被忽略：能返回文字，不等于适合放进 OpenCode。真正决定使用体验的，是模型能不能稳定理解代码上下文、调用工具，并在多轮任务里保持指令一致。
接口接通只是第一步，能把活干完才算接好了。
