OpenCode 配置教程

OpenCode 支持接入第三方 AI 服务。如果你想在 OpenCode 里使用 Ai Go Code 平台提供的 Claude、GPT 或 Gemini 模型，可以直接通过配置文件完成接入，整个过程非常快。

这篇文档会带你完成 API Key 获取、配置文件编写和最终验证，适合希望一次性配好的用户。

重要说明#

不同模型族使用的 API 端点后缀不同，请先确认：

• Anthropic（Claude 系列）：https://api.aigocode.com/v1
• OpenAI（GPT 系列）：https://api.aigocode.com/v1
• Google（Gemini 系列）：https://api.aigocode.com/v1beta

必须使用原生 SDK：Anthropic 使用 @ai-sdk/anthropic，OpenAI 使用 OpenCode 内置 OpenAI provider，Gemini 使用 @ai-sdk/google。

准备工作#

开始之前，请先准备好以下内容：

1. 一个 Ai Go Code 账号。
2. 已创建好的 API Key。
3. 已安装并可正常启动的 OpenCode。

获取 API Key#

如果你还没有 API Key，可以按下面步骤创建（⚠️注意选择支持第三方的分组）：

1. 访问 Ai Go Code 并注册账号。
2. 登录后进入控制台。
3. 在“API 密钥”页面创建新的 API Key。
4. 复制并妥善保存生成的 Key（格式通常为 sk-xxxxxx...）。

通过配置文件接入#

这是最推荐的方式。你可以手动修改文件，也可以把下面的配置示例发给能帮你改文件的 AI 工具（如 Codex、Claude Code、Cursor 等），让它直接替你写入。

第一步：找到配置文件#

OpenCode 主要会用到下面两个文件：

• 模型配置：~/.config/opencode/opencode.jsonc
• 认证配置：~/.local/share/opencode/auth.json

第二步：配置模型提供商#

编辑 ~/.config/opencode/opencode.jsonc，将 provider 配置指向 Ai Go Code：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.aigocode.com/v1",
        "apiKey": "sk-your-api-key-here"
      },
      "npm": "@ai-sdk/anthropic"
    },
    "openai": {
      "options": {
        "baseURL": "https://api.aigocode.com/v1",
        "apiKey": "sk-your-api-key-here"
      },
      "models": {
        "gpt-5.3-codex": {
          "name": "GPT-5.3 Codex",
          "limit": { "context": 400000, "output": 128000 },
          "options": { "store": false },
          "variants": { "low": {}, "medium": {}, "high": {}, "xhigh": {} }
        }
      }
    },
    "gemini": {
      "options": {
        "baseURL": "https://api.aigocode.com/v1beta",
        "apiKey": "sk-your-api-key-here"
      },
      "npm": "@ai-sdk/google",
      "models": {
        "gemini-3-flash-preview": {
          "name": "Gemini 3 Flash Preview",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "gemini-3.1-pro-preview": {
          "name": "Gemini 3.1 Pro Preview",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
          "options": { "thinking": { "budgetTokens": 24576, "type": "enabled" } }
        }
      }
    }
  },
  "agent": {
    "build": { "options": { "store": false } },
    "plan": { "options": { "store": false } }
  }
}

第三步：确认关键配置#

上面这份配置里，最容易出错的是下面几项：

• 必须使用原生 SDK，不能随便替换成其他兼容层。
• Claude 和 GPT 系列使用 /v1。
• Gemini 系列使用 /v1beta。
• 模型名称必须与 Ai Go Code 支持的模型 ID 完全一致。
• apiKey 需要替换成你自己的真实 API Key。

第四步：处理 auth.json#

如果你已经把 API Key 写进了 opencode.jsonc 的 options.apiKey，那么 auth.json 可以保持空对象：

{}

OpenCode 支持两种 API Key 配置方式：一是写在 opencode.jsonc 的 options.apiKey 中，二是写在 auth.json 中。两者任选其一即可，不需要重复配置。为了维护更简单，推荐直接写在 opencode.jsonc 中。

验证配置是否成功#

完成配置后，重新打开 OpenCode，确认是否能看到你刚刚配置的模型。

建议按下面顺序检查：

1. 模型列表中是否出现 Claude、GPT 或 Gemini 模型。
2. 选择任意一个模型发送测试消息。
3. 确认请求能正常返回结果，没有鉴权或 endpoint 报错。

常见问题#

为什么 Gemini 不能用 /v1？#

因为 Gemini 需要使用 Google 对应的接口路径，所以在 Ai Go Code 平台接入 Gemini 时也要使用 https://api.aigocode.com/v1beta。

为什么我已经配置了 auth.json，还要写 apiKey？#

不需要同时写。auth.json 和 opencode.jsonc 二选一即可，只保留一种方式最稳妥。

看不到模型怎么办？#

优先检查以下几项：

• 配置文件路径是否正确。
• JSON / JSONC 格式是否有语法错误。
• 模型 ID 是否与平台支持的名称完全一致。
• baseURL 是否填成了对应模型族需要的地址。
• API Key 是否有效。