为什么要研究 OpenCode 的模型配置？

最近，我想把日常开发和文档工作放到 OpenCode + 多模型组合 上。我希望能在同一个工具里，根据任务切换 GPT、Claude、Gemini，而不用反复切账号或切工具。

一开始，我遇到很多问题

模型配置完成却不显示，API 明明可用却请求失败，Claude 和 Gemini 经常 404。我以为是 OpenCode 本身的问题。

我仔细研究了 provider 机制，发现问题在于没有搞懂OpenCode模型配置。

这篇文章是我的实测经验，从原理到配置，让你一次搞定 OpenCode 自定义模型配置，如何统一接入 GPT / Claude / Gemini / GLM 等多个模型。

一、发现问题

在社区里，我看到的高频问题有：

• 模型已经写进配置文件，但在模型列表中不显示

• 调用时报错，但日志信息难以定位原因

• API Key 和 baseURL 测试没问题，但在 OpenCode 中请求失败

这些问题的原因是：

没有理解 OpenCode 是如何通过 provider 接入模型的。

二、理解问题

OpenCode 的模型是怎么被识别的，在 OpenCode 里，你需要明白：

Model ≠ API
Model ≠ SDK
Model = Provider + SDK + 配置

意思是：

• OpenCode 不会直接支持某个模型

• 它通过 provider 来适配不同模型的 SDK 和接口

• 协议匹配后，模型来源可以是官方、自建、中转或代理

这也是 OpenCode 能支持多模型同时使用的重要原因。

三、解决问题

OpenCode 有一个默认的配置文件：

~/.config/opencode/opencode.json

你也可以用环境变量修改：

export OPENCODE_CONFIG_DIR=~/.opencode
export OPENCODE_CONFIG=~/.opencode/opencode.json

建议在排查问题前，先确认 当前生效的配置文件路径。如果你不是手动配置的，大概是这样的：

下面这份配置，我在 OpenCode + Oh My OpenCode 环境中实测可用的完整配置，适合：

• 自建或中转模型服务

• OpenAI 兼容接口

• Anthropic / Gemini 私有部署或代理

{
  "$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": {
    "axonhub-openai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AxonHub OpenAI",
      "options": {
        "baseURL": "http://address:port/v1",
        "apiKey": "{env:AXONHUB_API_KEY}"
      },
      "models": {
        "gpt-5": { "id": "gpt-5", "name": "GPT-5" },
        "gpt-5.1": { "id": "gpt-5.1", "name": "GPT-5.1" }
      }
    },
    "axonhub-anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "AxonHub Claude",
      "options": {
        "baseURL": "http://address:port/anthropic/v1",
        "apiKey": "{env:AXONHUB_API_KEY}"
      },
      "models": {
        "claude-sonnet-4.5": {
          "id": "claude-sonnet-4.5",
          "name": "Claude Sonnet 4.5"
        }
      }
    },
    "axonhub-gemini": {
      "npm": "@ai-sdk/google",
      "name": "AxonHub Gemini",
      "options": {
        "baseURL": "http://address:port/gemini/v1beta",
        "apiKey": "{env:AXONHUB_API_KEY}"
      },
      "models": {
        "gemini-2.5-flash": {
          "id": "gemini-2.5-flash",
          "name": "Gemini 2.5 Flash"
        }
      }
    }
  }
}

四、provider 字段配置

npm：接口协议

"npm": "@ai-sdk/openai-compatible"

意思是：

• 接口格式遵循 OpenAI 规范

• 不要求官方 OpenAI

• 适合中转或私有化部署

options：请求常见错误

"options": {
  "baseURL": "http://address:port/v1",
  "apiKey": "{env:AXONHUB_API_KEY}"
}

常见问题：

• baseURL 忘记加 /v1

• HTTPS 证书不正确

• API Key 写死在配置中

models：ID 必须一致

"models": {
  "gpt-5": {
    "id": "gpt-5",
    "name": "GPT-5"
  }
}

• id：实际请求的模型名

• name：UI 显示名

五、API Key 管理调用方式

推荐使用下面这种方式调用，

export AXONHUB_API_KEY="your_api_key_here"

在配置中引用：

"apiKey": "{env:AXONHUB_API_KEY}"

优点：

安全，不进入版本控制

多环境切换方便

配置文件可复用

六、常见问题

七、进阶用法

1. 内置 Agent 分工

• Sisyphus：任务拆解与调度

• Oracle：架构分析和问题定位

• Explore：代码结构探索

• Librarian：文档和最佳实践查询

• Document-Writer：文档输出

调用方法：

@oracle
@document-writer

2. 用 @ 引用文件和目录

请修改 @src/components/Header.tsx，添加搜索框

AI 会基于指定文件修改。

3. Plan / Build 模式

• 用 Plan 模式先规划任务

• 确认无误再切 Build 模式执行

• 观察改动，及时发现问题

4. 后台并发和 Skills

• 配置 defaultConcurrency

• 多 Agent 并行执行

• 自定义 Skills 自动执行固定流程

总结

最近OpenCode用下来，我感觉不是工具有多丝滑，也不是支持了多少模型，其真正有价值的点而是，用 provider 机制 把不同模型配置组合起来，允许你根据场景自由组合模型能力、

如果打算构建的是一个长期可维护、多模型并存的 AI 工作环境，那花时间把多模型配置，是非常有必要的。

搞清楚了多模型配置接入，下期我们分享Oh-My-OpenCode是如何让OpenCode 实现 Agent + 多模型的能力

我建了一个AI开发交流群，欢迎一起讨论创意和AI开发