OpenCode 配置

OpenCode 支持自定义 OpenAI 兼容 provider。可以将 Modelink 配置为一个自定义提供商，然后在模型选择中使用 Modelink 模型。

自动配置

如果你的团队已使用 qiniu-coding-helper，优先通过配置向导完成已支持工具的配置；OpenCode 暂未列入自动写入目标时，可以按下面的步骤手动配置。

npx qiniu-coding-helper doctor

手动配置

OpenCode 官方"自定义提供商"流程要求先在 TUI 中通过 /connect 录入凭据，再修改 opencode.json。

第一步：通过 `/connect` 添加凭据

在 OpenCode TUI 中执行：

/connect

向下滚动选择 Other，然后：

输入提供商唯一 ID，例如 modelink（这个 ID 之后要写进配置文件）。
输入 Modelink API Key。

凭据会被保存到 ~/.local/share/opencode/auth.json。

第二步：编辑 `opencode.json`

在用户级 ~/.config/opencode/opencode.json 或项目根目录 opencode.json 中添加 provider 配置：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "modelink": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Modelink",
      "options": {
        "baseURL": "https://api.qnaigc.com/v1"
      },
      "models": {
        "<model-id>": {
          "name": "Modelink Model"
        }
      }
    }
  },
  "model": "modelink/<model-id>"
}

也可以不依赖 /connect，在 options 中通过环境变量注入 API Key：

{
  "options": {
    "baseURL": "https://api.qnaigc.com/v1",
    "apiKey": "{env:MODELINK_API_KEY}"
  }
}

第三步：选择模型

启动 OpenCode 后执行 /models，新加入的 Modelink 模型应该出现在列表中。

关于 `npm` 字段

OpenCode 自定义提供商基于 AI SDK，需要根据 Modelink 模型实际走的协议选择对应的包：

API 协议	`npm` 取值
OpenAI Chat Completions（`/v1/chat/completions`）	`@ai-sdk/openai-compatible`
OpenAI Responses（`/v1/responses`）	`@ai-sdk/openai`

如果同一个 provider 下同时配置 Chat Completions 和 Responses 模型，OpenCode 官方说明可以在单个模型上通过 provider.npm 覆盖默认包。例如：

{
  "provider": {
    "modelink": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Modelink",
      "options": {
        "baseURL": "https://api.qnaigc.com/v1"
      },
      "models": {
        "<chat-model-id>": {
          "name": "Modelink Chat Model"
        },
        "<responses-model-id>": {
          "name": "Modelink Responses Model",
          "provider": {
            "npm": "@ai-sdk/openai"
          }
        }
      }
    }
  }
}

配置位置

OpenCode 官方文档说明，配置按以下优先级合并加载（后者覆盖前者）：

位置	用途
`.well-known/opencode` 远程配置	组织默认配置
`~/.config/opencode/opencode.json`	用户全局默认配置
`OPENCODE_CONFIG` 指向的文件	自定义路径覆盖
项目根目录 `opencode.json`	项目级配置
`.opencode/` 目录	代理、命令、插件
`OPENCODE_CONFIG_CONTENT`	运行时内联覆盖

变量替换

OpenCode 配置支持两种变量替换语法：

{env:VAR}：替换为环境变量 VAR 的值。
{file:path/to/file}:读取文件内容。

注意事项

baseURL 填写 OpenAI 兼容端点：中国大陆 https://api.qnaigc.com/v1，海外 https://api.modelink.ai/v1。
models 中的 key 必须和实际接口返回的模型 ID 一致；执行 curl <baseURL>/models 可以列出可用模型。
配置文件支持 JSON 和 JSONC（带注释）。
修改配置后重启 OpenCode，并使用 /models 检查模型是否出现。
排查凭据问题可执行 opencode auth list。

参考

OpenCode Providers