OpenCode 模型配置教程：接入第三方 API 与本地模型

最近我在整理 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。真正决定使用体验的，是模型能不能稳定理解代码上下文、调用工具，并在多轮任务里保持指令一致。

接口接通只是第一步，能把活干完才算接好了。