OpenCode 自定义模型配置与使用技巧

参考：OpenCode Config、Providers

OpenCode 走 OpenAI Chat Completions API。接自定义网关时，在 opencode.jsonc 的 provider 块声明 endpoint 和模型列表。

1. 安装与配置文件

1
npm install -g opencode-ai

用户配置默认在 ~/.config/opencode/opencode.jsonc（也可用 opencode.json）。

配置优先级（高 → 低）：

macOS Managed 配置（企业下发，不可覆盖）
内联配置 OPENCODE_CONFIG_CONTENT
项目配置 opencode.json / opencode.jsonc
自定义路径 OPENCODE_CONFIG
全局配置 ~/.config/opencode/opencode.jsonc

Provider 和 Key 建议放全局，避免提交到 git。

2. 接入网关

字段	作用
`provider.<id>.options.baseURL`	网关地址
`provider.<id>.options.apiKey`	API Key
`provider.<id>.models`	可用模型列表
`model`	默认模型，格式 `provider/模型`

接 OpenAI 兼容网关时，npm 固定用 @ai-sdk/openai-compatible。

2.1 最小配置

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "llmapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llmapi",
      "options": {
        "baseURL": "https://api.xxx.com/v1",
        "apiKey": "your-token"
      },
      "models": {
        "glm-5.2": { "name": "GLM 5.2" }
      }
    }
  },
  "model": "llmapi/glm-5.2"
}

重启 OpenCode，TUI 里用 /models 确认模型是否加载。

2.2 密钥放哪

apiKey 直接写在配置文件里会明文落盘。博文示例中的 api.xxx.com、your-token 均为占位符，请替换为自己的值，切勿将真实 Key 提交到公开仓库。

更稳妥的做法：

"apiKey": "{env:LLMAPI_KEY}"

1
export LLMAPI_KEY=your-token

也支持 "apiKey": "{file:~/.config/opencode/llmapi.key}"。

2.3 网关注意事项

网关需兼容 OpenAI Chat Completions（/v1/chat/completions）
models 的 key 必须与网关 API 接受的 model 字段一致
若 endpoint 走 /v1/responses，改用 @ai-sdk/openai 作为 npm 包
模型 ID 以网关文档为准

3. 多模型配置

在 provider.<id>.models 里声明全部模型，用 model 和 small_model 分工：

{
  "provider": {
    "llmapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llmapi",
      "options": {
        "baseURL": "https://api.xxx.com/v1",
        "apiKey": "{env:LLMAPI_KEY}"
      },
      "models": {
        "glm-5.2": { "name": "GLM 5.2" },
        "deepseek-v4-pro": { "name": "DeepSeek V4 Pro" },
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" }
      }
    }
  },
  "model": "llmapi/glm-5.2",
  "small_model": "llmapi/deepseek-v4-flash"
}

字段	模型	用途
`model`	GLM 5.2	日常主模型
`small_model`	DeepSeek V4 Flash	标题生成等轻量任务
`/models` 切换	DeepSeek V4 Pro	重度编码时手动切

3.1 会话内切换

1
2
/models      # 选择模型
/provider    # 切换 Provider

4. 使用技巧

4.1 日常开发

日常默认 GLM 5.2，编码吃力时在 /models 切 Pro
Flash 配在 small_model，轻量任务自动走，不必手动切换

4.2 排错 checklist

现象	常见原因
模型列表为空	`models` 未声明或 Provider ID 写错
401 / 403	`apiKey` 未设置或 `{env:...}` 变量未 export
404	`baseURL` 不对，或网关不兼容 OpenAI API
模型 ID 无效	`models` 的 key 与网关侧名称不一致
改配置不生效	未重启 OpenCode

5. 完整示例

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "llmapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llmapi",
      "options": {
        "baseURL": "https://api.xxx.com/v1",
        "apiKey": "{env:LLMAPI_KEY}"
      },
      "models": {
        "glm-5.2": { "name": "GLM 5.2" },
        "deepseek-v4-pro": { "name": "DeepSeek V4 Pro" },
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" }
      }
    }
  },
  "model": "llmapi/glm-5.2",
  "small_model": "llmapi/deepseek-v4-flash"
}

1
2
3
export LLMAPI_KEY=your-token
opencode
# TUI：/models 切换 GLM / Pro / Flash