OpenCode 配置

在 OpenCode 中添加自定义 Flatrouter Provider，通过 OpenAI 兼容协议调用模型。

OpenCode 是开源的 AI 编程智能体，支持为模型供应商配置自定义 Provider。Flatrouter 可通过 OpenAI 兼容协议接入；这是 OpenCode 官方文档中适用于自定义兼容服务的配置方式。关于 Provider 配置字段与 /connect 交互流程，请以 OpenCode 官方 Provider 文档为准。

前提条件

已安装并能启动 OpenCode
已注册 Flatrouter 账号并获取 API Key（前往获取）
已在 Flatrouter 模型广场确认要使用的完整模型 ID

配置方式

推荐通过 OpenAI 兼容协议配置自定义 flatrouter Provider。这样可以明确指定端点、API Key 和需要在 OpenCode 中显示的模型。

协议	Base URL	适用场景
OpenAI 兼容（推荐）	`https://api.flatrouter.com/v1`	在 OpenCode 中添加自定义 Provider 和模型
Anthropic 原生	`https://api.flatrouter.com/anthropic`	仅在使用 Anthropic 原生 Provider 时填写

协议要匹配

本文的完整示例使用 OpenAI 兼容协议，因此配置包为 @ai-sdk/openai-compatible，Base URL 必须是 https://api.flatrouter.com/v1。不要在这份配置中改填 Anthropic 端点。

配置步骤

第 1 步：准备 API Key 环境变量

将 Flatrouter API Key 保存为环境变量，避免将密钥明文提交到配置文件或代码仓库：

export FLATROUTER_API_KEY="你的 Flatrouter API Key"

OpenCode 的配置支持通过 {env:变量名} 读取环境变量。重新打开终端或启动 OpenCode 前，确认该变量已在当前会话中生效。

第 2 步：通过 `/connect` 添加凭据（可选）

在 OpenCode 中输入 /connect，在供应商列表选择 Other，然后输入唯一的 Provider ID，例如 flatrouter，再按提示填写 API Key。

这是 OpenCode 官方文档提供的交互式添加自定义兼容 Provider 的方式。若希望明确管理 Provider 的模型列表、端点和默认模型，仍建议完成下一步的 opencode.json 配置。

第 3 步：配置自定义 Provider

在 OpenCode 使用的 opencode.json 中加入以下配置；若已有配置，请将 provider 中的 flatrouter 合并进去，不要覆盖其他 Provider。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "flatrouter",
      "options": {
        "baseURL": "https://api.flatrouter.com/v1",
        "apiKey": "{env:FLATROUTER_API_KEY}"
      },
      "models": {
        "<完整模型 ID>": {
          "name": "Flatrouter 模型"
        }
      }
    }
  }
}

将 <完整模型 ID> 替换为从 Flatrouter 模型广场复制的完整模型 ID。不要手动缩写、改写或猜测模型 ID。需要添加多个模型时，在 models 内继续增加模型 ID 条目即可。

第 4 步：设置默认模型（可选）

OpenCode 的模型引用格式为 provider/model-id。如需让 Flatrouter 中的某个已配置模型作为默认模型，在同一份配置的顶层增加 model：

{
  "model": "flatrouter/<完整模型 ID>"
}

这里的 <完整模型 ID> 必须与上一步 models 对象中的键完全一致。若不设置默认模型，也可以在 OpenCode 的模型选择界面中选择已添加的 flatrouter 模型。

第 5 步：验证配置

启动或重启 OpenCode，确认模型列表中出现 flatrouter Provider 及已添加模型。选择该模型后，发送一段简单文本，例如「你好，请回复已连接」。能收到正常回复通常表示 API Key、端点和模型 ID 已正确配置。

添加模型与选择建议

模型 ID、工具调用能力、上下文长度、价格和可用性会随模型而变化。请在 Flatrouter 模型广场查看实时信息，并将完整模型 ID 原样填入配置。

如果需要多个模型，可以按以下结构扩展：

{
  "provider": {
    "flatrouter": {
      "models": {
        "<第一个完整模型 ID>": {
          "name": "模型一"
        },
        "<第二个完整模型 ID>": {
          "name": "模型二"
        }
      }
    }
  }
}

模型限制

OpenCode 官方配置允许在模型条目中补充 limit.context 和 limit.output。只有在你能从模型广场或模型提供方确认准确限制时再填写；不确定时不要猜测数值。

常见问题

Q: OpenCode 中找不到 flatrouter Provider 或模型

检查 opencode.json 是否为有效 JSON，Provider ID 是否为 flatrouter，并确认模型 ID 已作为 models 中的键写入。修改配置后重启 OpenCode，再重新打开模型选择器。

Q: 提示 API Key 无效或认证失败

确认当前启动 OpenCode 的终端会话中存在 FLATROUTER_API_KEY，并检查 {env:FLATROUTER_API_KEY} 的拼写。API Key 请从 Flatrouter 控制台重新复制，避免包含额外空格或换行。

Q: 请求发送到了错误的端点或出现协议错误

OpenAI 兼容配置必须同时使用 @ai-sdk/openai-compatible 与 https://api.flatrouter.com/v1。若改用 Anthropic 原生 Provider，端点才应使用 https://api.flatrouter.com/anthropic；不要混用两套协议配置。

Q: 模型 ID 已填写，但模型无法调用

确认模型 ID 来自 Flatrouter 模型广场且复制完整；同时检查该模型当前是否对账号可用，以及是否受到额度、权限或临时可用性影响。

Q: API Key 会被写入 opencode.json 吗？

本文配置使用 {env:FLATROUTER_API_KEY} 引用环境变量，不将 Key 直接写入 JSON。请勿把包含真实 API Key 的配置提交到 Git 仓库。

Q: /connect 与 opencode.json 应该选哪个？

/connect 适合按 OpenCode 的交互式流程快速添加凭据；opencode.json 适合精确维护自定义 Provider 的端点和模型列表。两者同时使用时，应保证 Provider ID、API Key 和模型配置保持一致。

本页目录