OpenCode 接入¶

本页以 OpenCode 1 的终端客户端 opencode 为主，分别配置 RouteFast 的 GPT 与 Claude 路由。OpenCode 2 当前另用 opencode2 命令，原生配置见文末的可选说明。

OpenCode 1 配置以 v1.18.30 为例。先确认密钥分组及模型，再完成一次短文本请求。

1. 安装与确认版本¶

已安装 OpenCode 1 的用户先检查版本，无需为了本教程升级到 beta：

opencode --version

需要安装时，可在已安装 Node.js/npm 的终端执行：

npm install -g opencode-ai
opencode --version

该方式也见于官方 Windows 安装说明；Windows 用户可选用 WSL，并在 WSL 内完成安装、配置和启动。其他安装方式与系统要求见 OpenCode 1 安装文档。

如果你实际运行的是 opencode2，先看文末的版本差异。桌面应用、IDE 插件及独立后台服务可能使用不同的运行环境，本页命令针对终端客户端。

2. 准备密钥与模型¶

调用方向	RouteFast 密钥分组	示例模型 ID	本页协议
GPT	`OpenAI-ChatGPT`	`gpt-5.6-terra`	OpenAI Responses
Claude	`Anthropic-Claude`	`claude-sonnet-5`	Anthropic Messages

先在密钥管理和当前密钥的模型目录中确认精确 ID。两类密钥分别设置，只配置你要用的一类即可。

macOS / Linux / WSL：

export ROUTEFAST_GPT_API_KEY="sk-routefast-..."
export ROUTEFAST_CLAUDE_API_KEY="sk-routefast-..."

Windows PowerShell：

$env:ROUTEFAST_GPT_API_KEY="sk-routefast-..."
$env:ROUTEFAST_CLAUDE_API_KEY="sk-routefast-..."

将占位值替换为对应分组的密钥，不要在值前添加 Bearer。这些变量只对当前终端及随后启动的进程有效；在同一终端运行客户端。长期使用可由系统凭证工具或密码管理器注入，避免把真实密钥写入仓库或共享配置。

3. 配置 OpenCode 1¶

本页使用用户级 ~/.config/opencode/opencode.json；Windows 对应用户目录下的 .config\opencode\opencode.json。使用 WSL 时，这是 WSL 用户的文件。JSONC 文件 opencode.jsonc 也受支持；已有配置用哪一种，就编辑哪一种，不要再创建另一份同名用途文件。官方配置位置

先复制已有文件，保留例如 opencode.json.before-routefast-20260911 的备份，名称已存在时另取新名称。下面是完整的最小文件示例；已有文件应合并顶层 model 和 provider 中的相应条目，保留其他设置，避免重复 JSON 键。

GPT：Responses API¶

{
  "$schema": "https://opencode.ai/config.json",
  "model": "routefast-gpt/gpt-5.6-terra",
  "provider": {
    "routefast-gpt": {
      "npm": "@ai-sdk/openai",
      "name": "RouteFast GPT",
      "options": {
        "baseURL": "https://api.routefast.ai/v1",
        "apiKey": "{env:ROUTEFAST_GPT_API_KEY}"
      },
      "models": {
        "gpt-5.6-terra": {
          "name": "RouteFast GPT 示例"
        }
      }
    }
  }
}

@ai-sdk/openai 是本例 Responses 的适配器；Base URL 包含 /v1，不要再附加 /responses。如果特定既有工作流需要 Chat Completions，应在单独的 provider 中使用 @ai-sdk/openai-compatible，同样填 https://api.routefast.ai/v1，并重新验证对应模型。只改显示名称不会切换协议。官方自定义 Provider

旧客户端的适配器行为可能不同；如遇协议错误，先确认 OpenCode 版本及其支持的配置格式。

Claude：Messages API¶

使用 Claude 时可用下面的完整文件，或把其中 routefast-claude 条目合并到已有 provider 对象，再修改顶层 model：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "routefast-claude/claude-sonnet-5",
  "provider": {
    "routefast-claude": {
      "npm": "@ai-sdk/anthropic",
      "name": "RouteFast Claude",
      "options": {
        "baseURL": "https://api.routefast.ai/v1",
        "apiKey": "{env:ROUTEFAST_CLAUDE_API_KEY}"
      },
      "models": {
        "claude-sonnet-5": {
          "name": "RouteFast Claude 示例"
        }
      }
    }
  }
}

RouteFast 的 Anthropic 网关根地址是 https://api.routefast.ai，但 本例 AI SDK 的 baseURL 要填 https://api.routefast.ai/v1：适配器会再拼接 /messages，最终请求应到 /v1/messages。这与 Claude Code 的 ANTHROPIC_BASE_URL 规则不同。apiKey 由 Anthropic 适配器放入鉴权头，按本例配置无需额外手写 Authorization。

配置名称如何对应¶

routefast-gpt/gpt-5.6-terra 中，斜杠左边是本地 provider ID，右边是 models 下的模型键。这里让模型键与 RouteFast 精确模型 ID 相同。name 仅改变显示文字，不会把一个不可用模型变成可用模型。

本页通过 options.apiKey 引用环境变量，因此不必再运行 /connect 保存同一密钥。如果你选择官方 /connect → Other 方式，填写的 provider ID 必须与配置一致，并移除该 provider 的 options.apiKey 环境变量引用，保持一种明确的凭证来源。/connect 只保存凭证，并不自动替你完成网关地址、协议和模型定义。

/connect 会把凭证写入本机 ~/.local/share/opencode/auth.json。API Key 以 JSON 字符串保存，文件权限保护不等于内容加密；不要把该文件或备份发给他人。本页环境变量方式无需将真实密钥写入 opencode.json。

示例省略未知的 limit、cost、推理档位和多模态能力。对于自定义 provider，客户端内置目录未必能补全这些元数据。短请求成功后，正式长会话前应向 RouteFast 确认实际上下文和输出上限，再按对应版本字段配置；客户端估算价格不能代替 RouteFast 用量记录。模型配置说明

4. 启动并验证¶

在不含敏感文件的测试目录中启动：

cd /path/to/your/test-project
opencode

在会话内运行：

/models

选择 RouteFast GPT 或 RouteFast Claude 下的目标模型，并按顺序验证：

发送“只回复：连接测试成功，不调用工具”。等待完整回答结束，到 RouteFast 用量记录核对调用时间和模型。
再发送“用一句话解释刚才的回答”，确认当前会话能继续返回文本。
文本通过后，放入一个无敏感内容的测试文件，请它读取并说明该文件。核对实际工具执行与输出；需要测试编辑时，只允许修改测试文件，再人工检查差异。

请求可能产生费用。提示词不是权限隔离措施；测试时保留工具审批，按 OpenCode 1 权限说明管理文件与命令权限。无需先运行 /init 扫描整个项目，也无需启用 MCP 或外部工具，才能验证模型连接。

模型出现在 /models 中只说明配置已加载；完整文本、工具参数传递和工具结果回传需要分别验证。流式开始后仍可能报错，应等待完整回答结束后再判断请求是否成功。

常见问题¶

现象	优先检查
提示未知 `provider`、`providers`、`npm` 或 `package`	核对启动命令与版本；逐条检查文末的 v1/v2 字段，不要在同一个 provider 内混用
RouteFast 模型没出现	JSON 是否有效、provider 是否被禁用、环境变量是否注入、模型键与默认 `model` 是否一致
启动后用了原来的模型	在 `/models` 重新选择；检查项目 `opencode.json(c)`、`.opencode` 配置、启动参数与 `OPENCODE_CONFIG` / `OPENCODE_CONFIG_CONTENT`
`401` / `403`	当前进程是否能读取正确变量，密钥是否属于对应分组，是否仍有旧凭证来源；不要输出真实密钥排查
`404` 或 HTML 页面	API 域名应为 `api.routefast.ai`；检查最终路径，排除缺少 `/v1`、重复 `/v1` 或重复 `/responses` / `/messages`
`model_not_found` / 无权限	用当前密钥查询目录，核对精确 ID；显示名称和其他提供商的模型列表都不是授权依据
文本正常，工具请求报错	保存脱敏错误、版本、模型和协议，检查工具 schema 与结果回传，按出错参数逐项排查
`429` / 长时间重试	按错误体区分 Key 金额额度、费用窗口、请求速率与并发；减少并行会话不一定解决金额限额，参见限流与额度，不要持续自动重试
长会话溢出或输出截断	检查模型实际限制与客户端上下文配置，缩短历史；不要凭其他平台教程填写超大窗口

更完整的错误处理见故障排查。报障时提供客户端版本、操作系统、provider ID、协议、模型、时间、脱敏错误和请求 ID（如有），不要上传带密钥的配置或未经检查的完整日志。

可选：OpenCode 2 的差异¶

本节供已经选择 OpenCode 2 的用户使用。截至 2026-09-11，官方安装包为 @opencode/cli@beta，命令为 opencode2，不替换 OpenCode 1。安装入口见 OpenCode 2 文档；不要把 v1 的 npm 安装命令或 Windows 包管理器说明当作 v2 安装步骤。

opencode2 --version

配置项	本页 v1 写法	v2 原生写法
提供商集合	`provider`	`providers`
适配器	`npm`	`package`
SDK 参数	`options`	`settings`
API 模型名覆盖	`id`	`modelID`
GPT Responses 适配器	`@ai-sdk/openai`	`@opencode/ai/providers/openai-compatible/responses`
Claude Messages 适配器	`@ai-sdk/anthropic`	`@opencode/ai/providers/anthropic`

例如，v2 原生 GPT 最小配置可以写为：

{
  "model": "routefast-gpt/gpt-5.6-terra",
  "providers": {
    "routefast-gpt": {
      "name": "RouteFast GPT",
      "env": ["ROUTEFAST_GPT_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible/responses",
      "settings": {
        "baseURL": "https://api.routefast.ai/v1"
      },
      "websocket": false,
      "models": {
        "gpt-5.6-terra": {
          "name": "RouteFast GPT 示例"
        }
      }
    }
  }
}

env 是环境变量名列表，真正的密钥仍由启动环境提供。此例使用 HTTP 流式请求，保持 websocket: false 即可。具体字段与原生适配器以 v2 Providers 为准。

v1 与 v2 会读取同一全局及项目配置位置。 v2 官方说明支持在内存中转换受支持的完整 v1 配置，因此试用 v2 并不要求先改文件；反过来，不应让 v1 读取已改成 v2 原生格式的文件。在同一个 provider 或模型条目里拼接两套嵌套字段不会自动得到正确配置。两版并用时，保留 v1 写法通常更便于回退；要迁移则先备份完整配置，遵照官方迁移说明。

不要将 v1 的配置 Schema 用于检查 v2 原生字段。编辑器提示应结合客户端版本与 v2 官方文档判断。

v2 使用同一环境变量设置后启动 opencode2，再用 /models 和前文相同步骤验证。如果连接了已经运行的后台服务，新终端变量不一定进入该服务；按其官方启动说明重启实际处理请求的服务后再检查。

恢复原配置¶

退出客户端，对照备份恢复原来的默认 model，然后按需移除本次新增的 provider。期间修改过其他设置时，应按字段合并恢复。不要只删 provider，却让默认模型继续指向它。

环境变量从当前 shell 清除：

unset ROUTEFAST_GPT_API_KEY ROUTEFAST_CLAUDE_API_KEY