OpenCode配置

1. OpenCode 是什么，以及你需要准备什么

OpenCode 是一个开源的 AI 编码代理，可以在终端里阅读仓库、修改代码、执行命令，也可以和桌面端、Web 界面、IDE 扩展配合使用。

在通过 RouteAPI 接入 OpenCode 之前，建议先准备好：

一个可正常使用的终端环境
你的 RouteAPI 密钥
RouteAPI 控制台中可用、并且适合编码任务的模型
优先选择支持 OpenAI-compatible 协议和工具调用的模型

2. 安装 OpenCode

安装 CLI

如果你使用的是 macOS / Linux / WSL，官方推荐的安装方式是：

curl -fsSL https://opencode.ai/install | bash

如果你更习惯通过 Node.js 全局安装，也可以使用：

npm install -g opencode-ai

如果你使用的是 Windows PowerShell 原生环境，可以直接运行：

npm install -g opencode-ai

验证安装

opencode --version

如果输出了版本号，说明 OpenCode CLI 已经安装成功。

3. 推荐方式：先保存密钥，再写项目配置

OpenCode 官方文档建议先通过 /connect 保存凭证，再在配置文件里声明 provider 和 model。对于 RouteAPI 这种不在内置列表中的网关，选择 Other 即可。

在 OpenCode 里保存 RouteAPI 密钥

先启动 OpenCode：

opencode

然后在会话里运行：

/connect

接着按顺序完成：

选择 Other
将 provider ID 填成 routeapi
粘贴你的 RouteAPI 密钥

凭证会由 OpenCode 自动写入本地 ~/.local/share/opencode/auth.json，通常不需要手动编辑。

在项目根目录创建 `opencode.json`

OpenCode 官方文档同时支持全局配置 ~/.config/opencode/opencode.json 和项目根目录下的 opencode.json。对于团队协作，通常更推荐把非敏感配置写在项目根目录。

{
      "$schema": "https://opencode.ai/config.json",
      "provider": {
        "routeapi": {
          "npm": "@ai-sdk/openai-compatible",
          "name": "RouteAPI",
          "options": {
            "baseURL": "https://www.routeapi.ai/v1"
          },
          "models": {
            "your-routeapi-model-id": {
              "name": "RouteAPI Model"
            }
          }
        }
      },
      "model": "routeapi/your-routeapi-model-id"
}

上面这段配置里：

routeapi：自定义 provider 的唯一 ID，必须与 /connect 时填写的 provider ID 完全一致
npm：/v1/chat/completions 使用 @ai-sdk/openai-compatible；/v1/responses 使用 @ai-sdk/openai
options.baseURL：https://www.routeapi.ai/v1
models：键名填写 RouteAPI 控制台里真实可用的模型 ID，不要填展示名称
model：默认模型格式是 provider_id/model_id，这里就是 routeapi/your-routeapi-model-id

4. 不想用 `/connect` 时：改用环境变量

如果你更习惯让密钥来自环境变量，也可以直接在 opencode.json 里填写 options.apiKey。这是 OpenCode 官方文档支持的变量写法。

4.1 设置环境变量

如果你使用的是 macOS / Linux / WSL 中的 bash、zsh 或 sh：

export ROUTEAPI_KEY="你的 RouteAPI 密钥"

如果你使用的是 Windows PowerShell：

$env:ROUTEAPI_KEY="你的 RouteAPI 密钥"

4.2 在 `opencode.json` 中引用环境变量

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
"routeapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "RouteAPI",
      "options": {
        "baseURL": "https://www.routeapi.ai/v1",
        "apiKey": "{env:ROUTEAPI_KEY}"
      },
      "models": {
        "your-routeapi-model-id": {
          "name": "RouteAPI Model"
        }
      }
}
  },
  "model": "routeapi/your-routeapi-model-id"
}

5. 选择模型并启动 OpenCode

完成配置后，可以这样选择模型并启动：

启动 OpenCode：

opencode

在会话中运行：

/models

选择 routeapi 下的模型；如果你已经在 opencode.json 里设置了 model，OpenCode 会默认使用它

如果你只想临时切换当前会话的模型，也可以直接使用命令行参数：

opencode -m routeapi/your-routeapi-model-id

如果你想给标题生成等轻量任务单独指定一个更便宜的模型，还可以在配置里补充：

{
  "small_model": "routeapi/your-small-model-id"
}

6. 常见排查

运行 opencode auth list，确认本地已经保存了 routeapi 的凭证
如果 /models 里看不到你的自定义 provider，先检查 /connect 时填写的 provider ID 是否和 opencode.json 里的 routeapi 完全一致
如果模型能列出来但请求报协议错误，优先检查 npm 包是否选对了：/v1/chat/completions 用 @ai-sdk/openai-compatible，/v1/responses 用 @ai-sdk/openai
如果你在 Windows 上遇到文件访问慢、终端行为异常或路径不一致，优先改到 WSL 中运行 OpenCode
如果你还想对比其他 RouteAPI 客户端接入方式，可以继续阅读 Codex 配置指南、Cursor 配置指南和 Claude Code 配置指南