OpenCode OpenAI 兼容提供商设置：通过 Flatkey 路由编码代理模型

当您希望 OpenCode 与行为类似于 OpenAI 聊天补全 API 的模型路由进行通信，同时您的团队将密钥所有权、模型路由和使用情况审查保留在一个网关中时，**OpenCode OpenAI 兼容提供商**设置非常有用。

重要的是，OpenCode 有一个记录在案的自定义提供商路径。在 2026 年 7 月 8 日查阅的 OpenCode 提供商文档中，流程是：使用 /connect 添加凭据，为尚未列出的提供商选择**其他**，为该提供商指定一个易于记忆的 ID，在 opencode.json 中配置提供商，然后运行 /models 从已配置的模型中进行选择。

Flatkey 作为提供商背后的网关，符合该模式。您可以保留 OpenCode 作为编码代理，将提供商指向 Flatkey OpenAI 兼容的 API 基础 URL，并在将其设为默认路由之前，验证 OpenCode 模型流量是否出现在 Flatkey 的使用情况或请求日志中。

OpenCode OpenAI 兼容提供商设置快速解答

当模型端点与聊天补全兼容时，请使用此设置形式。

本 **OpenCode OpenAI 兼容提供商**指南使用模板。在路由生产编码代理工作之前，请根据您的 Flatkey 帐户验证确切的模型别名和端点系列。

OpenCode 的要求

对于自定义提供商，OpenCode 有两个独立的状态部分。

OpenCode 配置可以是 JSON 或 JSONC 格式。您可以将其全局放置在 ~/.config/opencode/opencode.json，或作为 opencode.json 放在项目根目录中。项目配置具有更高的标准优先级，因此当您希望一个存储库测试 Flatkey 而不更改每个 OpenCode 工作区时，请使用项目文件。

第 1 步：为 OpenCode 创建一个 Flatkey 密钥

为此工作负载创建一个 Flatkey 密钥，并在源代码控制之外记录三个值。

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_MODEL=your-current-flatkey-model-alias

将 API 根目录与端点路径分开。OpenCode 提供商配置应使用 https://router.flatkey.ai/v1 作为 options.baseURL；直接的 HTTP 冒烟测试会添加 /chat/completions。

在连接 OpenCode 之前，请使用相同的 Flatkey 密钥和模型别名运行直接测试。

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      { "role": "user", "content": "Reply with exactly: flatkey route ok" }
    ]
  }'

如果此直接请求失败，请在调试 OpenCode 之前修复 Flatkey 密钥、模型别名、端点系列或帐户路由。**OpenCode OpenAI 兼容提供商**无法补偿网关帐户无法调用的模型别名。

第 2 步：在 OpenCode 中添加 Flatkey 凭据

OpenCode 通过 /connect 存储提供商凭据。在 OpenCode TUI 中：

/connect

选择**其他**，输入提供商 ID（例如 flatkey），然后粘贴 Flatkey API 密钥。不要在凭据提示中粘贴基础 URL。密钥用于证明身份；基础 URL 属于 opencode.json。

使用一个简单的提供商 ID。flatkey 比 flatkey-prod-openai-compatible-gateway-v2 更好，因为您会在模型 ID 和回滚说明中输入它。

第 3 步：添加 OpenCode 提供商配置

在您要测试的项目根目录中创建或更新 opencode.json。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Flatkey",
      "options": {
        "baseURL": "https://router.flatkey.ai/v1"
      },
      "models": {
        "your-current-flatkey-model-alias": {
          "name": "Flatkey primary model"
        }
      }
    }
  },
  "model": "flatkey/your-current-flatkey-model-alias"
}

这是最小的 OpenCode OpenAI 兼容提供商配置。它为 OpenCode 提供了一个名为 flatkey 的提供商，告诉 OpenCode 使用 OpenAI 兼容的 AI SDK 包，并在模型选择器中公开一个模型别名。

如果您希望 OpenCode 使用较小的路由来处理轻量级工作，请仅在主路由正常工作后添加 small_model。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Flatkey",
      "options": {
        "baseURL": "https://router.flatkey.ai/v1"
      },
      "models": {
        "primary-flatkey-model-alias": {
          "name": "Flatkey primary"
        },
        "lighter-flatkey-model-alias": {
          "name": "Flatkey lightweight"
        }
      }
    }
  },
  "model": "flatkey/primary-flatkey-model-alias",
  "small_model": "flatkey/lighter-flatkey-model-alias"
}

使用您的 Flatkey 密钥实际可以调用的模型别名。如果您的帐户公开了经过身份验证的 /v1/models 路由，请将配置的模型 ID 与该响应进行比较。否则，请从当前的 Flatkey 仪表板或模型目录中复制别名，并使用真实请求进行验证。

第 4 步：在 OpenCode 中选择并测试模型

保存配置后，打开模型选择器。

/models

选择 Flatkey 提供商模型。然后在 OpenCode 中运行一个微小的提示：

Reply with exactly: opencode flatkey route ok

暂时不要移动整个编码工作流。首先保存一个紧凑的验证包。

这将 OpenCode OpenAI 兼容提供商的迁移转变为一个小的操作性变更，而不是盲目地更换提供商。

第 5 步：将聊天补全和响应分开

OpenCode 的自定义提供商文档指出了一个包边界：对于使用 /v1/chat/completions 的 OpenAI 兼容提供商，请使用 @ai-sdk/openai-compatible；如果提供商或模型使用 /v1/responses，请使用 @ai-sdk/openai。

这意味着第一个 Flatkey 路由应该是一个聊天补全（Chat Completions）风格的模型，除非您有当前证据表明您选择的模型和客户端路径使用了不同的端点系列。

在添加更多模型之前，请使用此决策表。

对于大多数设置工作，请从一个聊天补全（Chat Completions）路由开始。在 Flatkey 中可以看到第一个 OpenCode OpenAI 兼容提供商冒烟测试通过后，再添加流式传输、工具调用和辅助模型别名。

第 6 步：在路由正常工作后添加团队控制

一旦 OpenCode 可以调用 Flatkey，就使该路由可观察。

这就是 Flatkey 不仅仅是一个基本 URL 的原因。一个可用的 OpenCode OpenAI 兼容提供商还应该为平台、财务和运营团队提供一个审查模型用量和更改路由的地方，而无需让每个开发人员管理单独的提供商帐户。

对于更广泛的迁移规划，请将本指南与 Flatkey OpenAI 兼容 API 迁移指南结合使用。如果您正在比较相邻的编码工具，请参阅 Continue.dev OpenAI 兼容提供商指南和 Roo Code OpenAI 兼容设置指南。

排查 OpenCode OpenAI 兼容提供商问题

如果第一个请求失败，请不要立即更改提示、代理、权限或存储库代码。保持 OpenCode OpenAI 兼容提供商的调试范围小：凭据、提供商 ID、基本 URL、包、模型别名和一个纯文本聊天请求。

最终核对清单

在使用 Flatkey 作为默认 OpenCode 路由之前，请确认：

1. /connect 在 opencode.json 中使用的相同提供商 ID 下具有 Flatkey 凭据。
2. 对于聊天补全路由，provider.flatkey.npm 是 @ai-sdk/openai-compatible。
3. provider.flatkey.options.baseURL 是 https://router.flatkey.ai/v1。
4. model 指向一个已配置的 flatkey/<model-alias> 值。
5. /models 显示已配置的 Flatkey 模型。
6. 单行 OpenCode 提示成功返回。
7. Flatkey 用量或请求日志显示 OpenCode 测试请求。
8. 已记录先前的提供商/模型路由以备回滚。

当提供商已配置、可选择、在 Flatkey 日志中得到验证且可逆时，OpenCode OpenAI 兼容提供商的设置就完成了。当您准备好通过一个密钥路由编码代理模型流量时，获取一个 Flatkey 密钥并从一个低风险的 OpenCode 提示开始。