本文面向第一次使用 Terminal、第一次配置 OpenCode，或者需要把 OpenCode 接入第三方 AI Gateway 的用户。

完成本文后，你将能够：

• 安装并确认 OpenCode；
• 安全输入 AI Gateway 的 Base URL 和 API Key；
• 查询自己的 API Key 可以看到的模型；
• 判断模型应使用 OpenAI Chat、OpenAI Responses 还是 Anthropic Messages；
• 把通过测试的模型写入正确的 OpenCode provider；
• 用一条真实消息确认 OpenCode 已经连接成功；
• 根据错误信息判断是网络、认证、模型路由、请求协议还是 OpenCode 配置问题。

本文以 macOS Terminal 为例，示例 AI Gateway Base URL 为：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1>

如果你的 AI Gateway 不同，只需要替换 Base URL、API Key 和模型 ID。本文中的模型名称仅用于演示协议和配置写法，实际模型范围以你的 API Key 和中转站返回结果为准。不要把真实 API Key 发到聊天、工单、截图、Git 仓库或公开网页。

本文配置示例按 OpenCode

1.18.18

opencode --version

先看结论：模型厂商和请求协议是两件事

OpenCode 不会根据模型名称自动选择请求协议。真正决定请求格式的是 provider 使用的 AI SDK runtime。

本文使用三个容易识别的 provider 名称：

my-relay

@ai-sdk/openai-compatible

/chat/completions

my-relay-responses

@ai-sdk/openai

/responses

my-relay-anthropic

@ai-sdk/anthropic

/messages

如果你已经有其他 provider 名称，不需要为了匹配本文示例而重命名。继续沿用原名称，并把本文命令中的 provider ID 替换为你的实际名称。provider 名称是本机配置名称，不是模型厂商名称。

按模型厂商选择第一条测试路径

下面的表格用于选择起始路径，不代表某个厂商的所有模型都开放相同协议。具体模型必须以自己的

/models

my-relay-anthropic

my-relay

my-relay-responses

最重要的规则是：

模型厂商 ≠ 请求协议 模型出现在目录中 ≠ 模型已经可以调用 标准 curl 成功 ≠ OpenCode 已经配置完成

只需要为准备使用的协议配置 provider。只用 Claude 时可以只配置 Anthropic provider；只用 OpenAI Chat 时可以只配置 OpenAI Compatible provider；只有在

/responses

0. 完整操作路线

第一次配置时，请按以下顺序操作：

1. 安装或确认 OpenCode 2. 准备 Base URL 和 API Key 3. 查询自己的模型目录 4. 选择模型和目标协议 5. 用对应协议的 curl 得到最终文字 6. 把成功模型写入 OpenCode 7. 校验配置并查看 provider 8. 用 OpenCode 发送第一条消息 9. 需要时再添加其他模型或协议

真正成功必须同时满足：

1. 当前协议的模型目录能看到模型；
2. 标准 curl 返回 HTTP 200；
3. 响应中有实际模型文本；
4. OpenCode 通过正确的 provider 返回实际模型文本。

只看到模型名称，不能直接说明模型可用。模型目录、协议路由和客户端实际调用必须分别验证。

0.1 如何阅读模型信息

本文中的模型信息分成三层，含义不同：

/models

因此，请按以下优先级判断：

自己的 API Key 实时目录 ↓ 对应协议的标准 curl ↓ OpenCode 对应 provider 的实际调用 ↓ 才可以判断该模型在自己的环境中可用

本文中的“可以使用”默认指“最小文本请求返回了最终文本”。它不自动包含工具调用、流式、多模态、结构化输出、长上下文或模型专属参数。

你最终能否调用某个模型，取决于四个条件同时成立：

产品是否配置了该模型的上游路由 × API Key 是否拥有该模型权限 × OpenCode 是否使用了正确 provider 和协议 × 本次请求使用的功能是否经过验证 = 本次调用是否真正可用

因此，“中转站可以路由某模型”与“你的 API Key 当前可以调用某模型”是两个不同问题。后者还会受到租户、套餐、权限和实时上游状态影响。

0.2 配置完成后的预期效果

完成本文后，你应能做到：

• 在 OpenCode 中看到自己 API Key 可用的 provider 和模型；
• 用

  my-relay

  my-relay
  调用 OpenAI Compatible Chat 模型；
• 在模型的

  /responses

  /responses
  请求成功时，用

  my-relay-responses

  my-relay-responses
  调用该模型；
• 用

  my-relay-anthropic

  my-relay-anthropic
  调用 Anthropic Messages 模型，包括 Claude；
• 根据厂商和协议规则选择正确的 provider，不再把 Claude 放入 OpenAI provider；
• 用最小文本请求确认模型确实返回最终文本；
• 遇到认证、网络、协议、路由或客户端参数错误时，判断问题属于哪一层。

完成第 8 步后，你已经具备基础文本对话能力。工具调用、图片、文件、结构化输出和其他高级能力的适用范围见第 11.6 节和第 12 节。

如果只完成 JSON 编辑但没有完成 curl 和 OpenCode 实际调用，配置还没有完成验证。

1. 准备信息

开始前准备三项内容。

1.1 Base URL

Base URL 是 AI Gateway 接口地址。本示例使用：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1>

地址已经包含

/v1

/v1/v1

/chat/completions

/messages

1.2 API Key

请到 AI Gateway 后台创建 API Key，并确认：

• API Key 没有过期；
• API Key 有模型调用权限；
• 复制时没有多余空格或换行；
• API Key 与 Base URL 属于同一个环境；
• 如果中转站按协议区分权限，API Key 拥有你准备使用的 OpenAI、Responses 或 Anthropic 路由权限。

API Key 的权限可能比产品目录更窄。不同用户、不同套餐或不同租户看到的模型范围可能不同，所以请先查询自己的 OpenAI 和 Anthropic 两个认证视图，再把实际使用的模型加入配置。

1.3 是否需要 VPN

OpenCode 请求的是你配置的 AI Gateway，不是直接请求 Anthropic 或 OpenAI。只要本机能访问中转站，一般不需要 VPN。

先执行第 6 节的

/models

• 能建立 TLS 连接但返回

  401

  401
  、

  No upstream candidates

  No upstream candidates
  或

  502

  502
  ：通常是 API Key、模型 ID、协议或上游路由问题，不是 VPN 问题；
• 出现 DNS 失败、连接超时、TLS 握手失败：才优先检查网络、公司代理、防火墙或 VPN。

1.4 在哪里操作

所有命令都在 macOS Terminal 执行。按 Command + Space，输入 Terminal，按回车打开。

终端提示符可能类似：

a123@Mac ~ %

不要复制提示符本身，只复制代码框中的命令。

**下一步：**执行第 2 节，检查基础工具和 OpenCode。

2. 确认基础工具和 OpenCode

2.1 检查 curl、jq、Node.js

在 Terminal 执行：

command -v curl command -v jq node --version npm --version

看到

curl

jq

如果 jq 不存在：

command -v brew

如果 brew 存在：

brew install jq jq --version

如果 brew 也不存在，请先安装 Homebrew，再安装 jq。后面的模型目录和响应解析命令需要 jq。

**下一步：**确认 OpenCode 命令是否已经安装。

2.2 安装或确认 OpenCode

先执行：

command -v opencode opencode --version type -a opencode

如果已经返回路径和版本号，可以直接进入第 3 节。

type -a opencode

如果还没有安装，可以使用 npm：

npm install -g opencode-ai opencode --version

也可以使用 OpenCode 官方安装脚本：

curl -fsSL --proto '=https' --tlsv1.2 https://opencode.ai/install | bash opencode --version

正常返回版本号即可，例如：

1.18.18

如果显示

opencode: command not found

NPM_GLOBAL_BIN="$(npm prefix -g)/bin" printf 'npm global bin: %s\n' "$NPM_GLOBAL_BIN" test -x "$NPM_GLOBAL_BIN/opencode" && echo 'opencode 已安装但当前 PATH 未包含该目录' command -v opencode

如果命令已经安装但当前 Terminal 找不到，请把实际 npm 全局 bin 目录加入

~/.zshrc

opencode --version

**下一步：**确认 OpenCode 版本后，进入第 3 节保存 API Key。

3. 在当前 Terminal 安全输入 API Key

不要把 API Key 直接写在命令行参数中，因为它可能进入 Terminal history。在同一个 Terminal 执行：

export RELAY_BASE_URL='https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1' RELAY_BASE_URL="${RELAY_BASE_URL%/}" read -s "RELAY_API_KEY?请粘贴 AI Gateway API Key，然后按回车：" echo export CLICKZETTA_API_KEY="$RELAY_API_KEY"

粘贴 API Key 时屏幕不会显示字符，这是正常的。

export

检查变量是否存在时不要打印实际内容：

if [ -n "$CLICKZETTA_API_KEY" ]; then echo 'CLICKZETTA_API_KEY 已加载' else echo 'CLICKZETTA_API_KEY 未加载' fi

3.1 新 Terminal 为什么需要重新加载

上面的变量只在当前 Terminal 窗口有效。关闭窗口或重启电脑后，如果看到

API Key: missing

临时使用时，在每个新 Terminal 中重新执行本节的

read -s

3.2 长期使用：保存到 macOS Keychain（推荐）

完成前面的

read -s

security add-generic-password \ -U \ -a "$USER" \ -s 'opencode-clickzetta-api-key' \ -w "$CLICKZETTA_API_KEY"

以后打开新 Terminal，执行下面命令加载，不会在屏幕上打印 API Key：

export RELAY_BASE_URL='https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1' export CLICKZETTA_API_KEY="$(security find-generic-password \ -a "$USER" \ -s 'opencode-clickzetta-api-key' \ -w)" test -n "$CLICKZETTA_API_KEY" && echo 'API Key 已从 macOS Keychain 加载'

首次读取时 macOS 可能要求确认 Keychain 访问，这是正常现象。如果不再使用，可以删除该条目：

security delete-generic-password \ -a "$USER" \ -s 'opencode-clickzetta-api-key'

如果不是 macOS，请使用系统密码管理器或权限受限的本地密钥方案。不要把真实值写进本文、Git 仓库、截图、项目目录、公开的

opencode.json

**下一步：**先不要打开 OpenCode，按照协议分别查看模型目录。

4. OpenCode 配置文件在哪里

本节只确认配置文件位置并做好备份。先不要把未测试的模型全部写进去；模型目录和 curl 测试在第 6、7 节完成，真正写入配置在第 8 节。

macOS 默认配置文件为：

~/.config/opencode/opencode.json

也就是：

/Users/你的用户名/.config/opencode/opencode.json

先检查目录和文件：

mkdir -p "$HOME/.config/opencode" ls -la "$HOME/.config/opencode"

第一次修改已有配置前先备份：

if [ -f "$HOME/.config/opencode/opencode.json" ]; then cp -p "$HOME/.config/opencode/opencode.json" "$HOME/.config/opencode/opencode.json.bak" fi

4.1 重要：OpenCode 版本格式差异

本文基于 OpenCode

1.18.18

provider 单数 npm provider 使用的 AI SDK runtime options baseURL 等运行参数 models provider 下的模型字典

OpenCode 新版文档可能使用

providers

package

settings

opencode --version

如果你使用的版本不是

1.18.18

opencode debug config

如果报配置 schema 错误，先按该版本的配置格式迁移，不能简单地把

provider

providers

**下一步：**先理解第 5 节的 provider 与协议对应关系，再查询模型目录。

5. 先理解 OpenCode 的三个 provider

OpenCode 不会根据模型 ID 自动选择请求协议。协议由 provider 的 runtime package 决定。

本指南使用三个 provider：

my-relay → @ai-sdk/openai-compatible → POST /v1/chat/completions → Authorization: Bearer API_KEY my-relay-responses → @ai-sdk/openai → POST /v1/responses → Authorization: Bearer API_KEY my-relay-anthropic → @ai-sdk/anthropic → POST /v1/messages → x-api-key: API_KEY → anthropic-version: 2023-06-01

模型引用格式是：

<provider-id>/<model-id>

例如：

my-relay/openai/gpt-5.5 my-relay-anthropic/anthropic/claude-opus-5

这里的

my-relay-anthropic

anthropic/claude-opus-5

anthropic/

my-relay

以下写法协议不匹配：

my-relay/anthropic/claude-opus-5 my-relay-anthropic/openai/gpt-5.5

**下一步：**执行第 6 节，按认证方式分别查询模型目录。

6. 获取实时模型目录

模型目录必须按协议分别查询。不能只执行一次

/models

6.1 OpenAI 视图

OpenAI Compatible 使用 Bearer 认证：

curl -sS -o /tmp/opencode-gateway-models-openai.json \ --max-time 30 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/models" \ -H "Authorization: Bearer $CLICKZETTA_API_KEY" \ -H 'Accept: application/json'

HTTP 200 后执行：

jq -r ' if (.data | type) == "array" then .data[].id else .error.message // .message // "没有读取到模型目录" end ' /tmp/opencode-gateway-models-openai.json

返回含义：

/v1

/v1

模型出现在目录中，只表示当前 API Key 能看到该 ID；它不代表该模型在 Chat、Responses 和 Anthropic 三种协议下都可用。继续执行第 7 节的具体请求测试。

6.2 Anthropic 视图

Anthropic Messages 使用不同认证头：

curl -sS -o /tmp/opencode-gateway-models-anthropic.json \ --max-time 30 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/models" \ -H "x-api-key: $CLICKZETTA_API_KEY" \ -H 'anthropic-version: 2023-06-01' \ -H 'Accept: application/json'

HTTP 200 后执行：

jq -r ' if (.data | type) == "array" then .data[].id else .error.message // .message // "没有读取到 Anthropic 模型目录" end ' /tmp/opencode-gateway-models-anthropic.json

如果 OpenAI 视图和 Anthropic 视图不同，这是正常现象。请求头和协议上下文不同，AI Gateway 可以返回不同的模型目录。请使用自己的 API Key 重新查询两个视图，不要复制某一份静态清单。

6.3 OpenCode 自带模型目录的含义

直接执行：

opencode models

会看到 OpenCode 内置目录中的许多 provider，例如

amazon-bedrock/anthropic.claude-*

OpenCode 的内置目录与中转站目录是两套目录。只有写入

opencode.json

6.4 如何使用自己的模型目录

你不需要把本文示例中的模型全部复制到配置文件。推荐按下面规则处理：

1. 保存自己 API Key 的 OpenAI 和 Anthropic

   /models

   /models
   输出；
2. 只把自己目录中存在的模型 ID 放入对应 provider；
3. 对每个准备使用的模型执行第 7 节对应协议的最小文本请求；
4. 只有返回 HTTP 200 且包含最终文本的模型，才进入 OpenCode 实际调用；
5. 如果模型在目录中但请求返回

   No upstream candidates

   No upstream candidates
   或

   502

   502
   ，保留记录但不要标记为可用；
6. 如果自己的目录与预期不一致，先以实时目录为准，再联系中转站支持人员确认权限或路由。

模型目录是权限和路由的实时快照，不是需要手工维护的“模型总表”。能否使用某个模型，必须同时看模型 ID、协议、provider 和实际调用结果。

**下一步：**从对应目录复制一个完整模型 ID，执行第 7 节的协议请求。

7. 用标准 curl 验证协议和模型

7.1 OpenAI Chat Completions

请求端点：

POST /v1/chat/completions Authorization: Bearer API_KEY

从第 6.1 节的结果中复制一个完整模型 ID：

read "CHAT_MODEL_ID?请粘贴准备使用 Chat 协议的完整模型 ID："

执行：

curl -sS -o /tmp/opencode-test-chat.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/chat/completions" \ -H "Authorization: Bearer $CLICKZETTA_API_KEY" \ -H 'Content-Type: application/json' \ -d "$(jq -cn \ --arg model "$CHAT_MODEL_ID" \ '{ model: $model, max_tokens: 512, messages: [{role: "user", content: "请只回复：Chat连接成功"}] }')"

提取最终文字：

jq -r ' .choices[0].message.content // .error.message // .message // "HTTP 已返回，但没有找到最终文字" ' /tmp/opencode-test-chat.json

成功时应看到：

HTTP 200 Chat连接成功

如果成功，可以在第 8 节只配置

my-relay

7.2 OpenAI Responses

请求端点：

POST /v1/responses Authorization: Bearer API_KEY

从第 6.1 节的结果中复制一个完整模型 ID：

read "RESPONSES_MODEL_ID?请粘贴准备使用 Responses 协议的完整模型 ID："

执行。Responses 使用

input

max_output_tokens

messages

curl -sS -o /tmp/opencode-test-responses.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/responses" \ -H "Authorization: Bearer $CLICKZETTA_API_KEY" \ -H 'Content-Type: application/json' \ -d "$(jq -cn \ --arg model "$RESPONSES_MODEL_ID" \ '{ model: $model, input: "请只回复：Responses连接成功", max_output_tokens: 512 }')"

提取最终文字：

jq -r ' ([.output[]?.content[]? | select(.type == "output_text" or .type == "text") | .text] | join("\n")) as $text | if ($text | length) > 0 then $text else .error.message // .message // "HTTP 已返回，但没有找到最终文字" end ' /tmp/opencode-test-responses.json

不同网关或 SDK 的 Responses 响应结构可能不同，通常从

output[].content[].text

output_text

成功时应看到：

HTTP 200 Responses连接成功

Responses 结果不能由 Chat 结果推断：同一个模型在两个端点的上游路由可能不同。OpenCode 本指南的

my-relay

Responses 是可选接入路径。只有同一模型先通过本节的

/responses

my-relay-responses

opencode run

7.3 Anthropic Messages

请求端点：

POST /v1/messages x-api-key: API_KEY anthropic-version: 2023-06-01

从第 6.2 节的结果中复制一个完整模型 ID：

read "ANTHROPIC_MODEL_ID?请粘贴准备使用 Anthropic 协议的完整模型 ID："

对本文示例 AI Gateway，Claude 当前优先且已经验证的接入路径是 Anthropic Messages，因此使用下面的请求结构：

curl -sS -o /tmp/opencode-test-anthropic.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/messages" \ -H "x-api-key: $CLICKZETTA_API_KEY" \ -H 'anthropic-version: 2023-06-01' \ -H 'content-type: application/json' \ -d "$(jq -cn \ --arg model "$ANTHROPIC_MODEL_ID" \ '{ model: $model, max_tokens: 1024, messages: [{role: "user", content: "请只回复：Anthropic连接成功"}] }')"

提取最终文字：

jq -r ' ([.content[]? | select(.type == "text") | .text] | join("\n")) as $text | if ($text | length) > 0 then $text else .error.message // .message // "HTTP 已返回，但没有找到最终文字" end ' /tmp/opencode-test-anthropic.json

成功时应看到：

HTTP 200 Anthropic连接成功

测试时不要把

max_tokens

1024

下面是模型 ID 写法示例。实际使用时，只把模型 ID 换成自己的 Anthropic 目录中存在、并且请求验证成功的 ID：

anthropic/claude-haiku-4.5 anthropic/claude-opus-4.8 anthropic/claude-opus-5 anthropic/claude-sonnet-4.6 anthropic/claude-sonnet-5

如果成功，可以在第 8 节只配置

my-relay-anthropic

7.4 HTTP 200 但没有最终文字

部分推理模型可能先生成 thinking 或 reasoning 内容。输出预算太小时，请求可能返回 HTTP 200，但没有最终文字。

可以把对应请求中的：

max_tokens: 512 max_output_tokens: 512

先提高到

1024

4096

**下一步：**只把刚才 curl 成功的模型写入对应 OpenCode provider，执行第 8 节。

8. 写入 OpenCode 配置

下面是 OpenCode

1.18.18

my-relay

my-relay-anthropic

/responses

my-relay-responses

CLICKZETTA_API_KEY

8.1 复制配置前先区分“固定部分”和“可变部分”

provider

1.18.18

provider

@ai-sdk/openai-compatible

@ai-sdk/openai

/responses

@ai-sdk/anthropic

baseURL

/v1

CLICKZETTA_API_KEY

model

<provider>/<model-id>

models

/models

limit.context

limit.output

8.2 方案 A：用 Terminal 写入 OpenAI Chat provider

这是推荐方式。它只修改

my-relay

CHAT_MODEL_ID

如果你已有其他 provider 名称，可在执行前设置

OPENAI_PROVIDER_ID

my-relay

set -e OPENAI_PROVIDER_ID="${OPENAI_PROVIDER_ID:-my-relay}" test -n "$CHAT_MODEL_ID" || read "CHAT_MODEL_ID?请粘贴已测试成功的 Chat 模型 ID：" CONFIG_FILE="$HOME/.config/opencode/opencode.json" mkdir -p "$(dirname "$CONFIG_FILE")" if [ -f "$CONFIG_FILE" ]; then cp -p "$CONFIG_FILE" "$CONFIG_FILE.backup-$(date +%Y%m%d-%H%M%S)" else printf '%s\n' '{"$schema":"https://opencode.ai/config.json","provider":{}}' > "$CONFIG_FILE" fi CHAT_PROVIDER=$(jq -cn \ --arg base "$RELAY_BASE_URL" \ --arg model "$CHAT_MODEL_ID" \ '{ name: "AI Gateway (OpenAI Chat)", env: ["CLICKZETTA_API_KEY"], npm: "@ai-sdk/openai-compatible", options: {baseURL: $base}, models: {($model): {name: $model}} }') TMP_FILE=$(mktemp) jq \ --argjson provider "$CHAT_PROVIDER" \ --arg provider_id "$OPENAI_PROVIDER_ID" \ --arg model "$CHAT_MODEL_ID" \ '.provider = (.provider // {}) | .provider[$provider_id] as $existing | .provider[$provider_id] = (($existing // {}) * $provider) | .provider[$provider_id].models = (($existing.models? // {}) + $provider.models) | .model = ($provider_id + "/" + $model)' \ "$CONFIG_FILE" > "$TMP_FILE" && mv "$TMP_FILE" "$CONFIG_FILE" jq empty "$CONFIG_FILE" opencode debug config >/dev/null && echo 'OpenAI Chat provider 配置成功'

8.3 方案 B：用 Terminal 写入 Anthropic provider

这是 Claude 的推荐方式。必须先完成第 7.3 节，并且当前 Terminal 中仍然存在

ANTHROPIC_MODEL_ID

如果你已有其他 provider 名称，可在执行前设置

ANTHROPIC_PROVIDER_ID

my-relay-anthropic

set -e ANTHROPIC_PROVIDER_ID="${ANTHROPIC_PROVIDER_ID:-my-relay-anthropic}" test -n "$ANTHROPIC_MODEL_ID" || read "ANTHROPIC_MODEL_ID?请粘贴已测试成功的 Anthropic 模型 ID：" CONFIG_FILE="$HOME/.config/opencode/opencode.json" mkdir -p "$(dirname "$CONFIG_FILE")" if [ -f "$CONFIG_FILE" ]; then cp -p "$CONFIG_FILE" "$CONFIG_FILE.backup-$(date +%Y%m%d-%H%M%S)" else printf '%s\n' '{"$schema":"https://opencode.ai/config.json","provider":{}}' > "$CONFIG_FILE" fi ANTHROPIC_PROVIDER=$(jq -cn \ --arg base "$RELAY_BASE_URL" \ --arg model "$ANTHROPIC_MODEL_ID" \ '{ name: "AI Gateway (Anthropic Messages)", env: ["CLICKZETTA_API_KEY"], npm: "@ai-sdk/anthropic", options: {baseURL: $base}, models: {($model): {name: $model}} }') TMP_FILE=$(mktemp) jq \ --argjson provider "$ANTHROPIC_PROVIDER" \ --arg provider_id "$ANTHROPIC_PROVIDER_ID" \ --arg model "$ANTHROPIC_MODEL_ID" \ '.provider = (.provider // {}) | .provider[$provider_id] as $existing | .provider[$provider_id] = (($existing // {}) * $provider) | .provider[$provider_id].models = (($existing.models? // {}) + $provider.models) | .model = ($provider_id + "/" + $model)' \ "$CONFIG_FILE" > "$TMP_FILE" && mv "$TMP_FILE" "$CONFIG_FILE" jq empty "$CONFIG_FILE" opencode debug config >/dev/null && echo 'Anthropic provider 配置成功'

如果需要多个协议，分别执行已通过 curl 测试的方案。每段命令会写入独立 provider，不会把 Claude 放进 OpenAI provider，也不会把 Responses 模型误当成 Chat 模型；最后执行的方案会把对应模型设置为默认模型，之后仍可使用

--model

8.4 方案 C：用 Terminal 写入 OpenAI Responses provider（按需）

只有第 7.2 节返回 HTTP

200

openai

gpt

如果你已有其他 provider 名称，可在执行前设置

RESPONSES_PROVIDER_ID

my-relay-responses

set -e RESPONSES_PROVIDER_ID="${RESPONSES_PROVIDER_ID:-my-relay-responses}" test -n "$RESPONSES_MODEL_ID" || read "RESPONSES_MODEL_ID?请粘贴已测试成功的 Responses 模型 ID：" CONFIG_FILE="$HOME/.config/opencode/opencode.json" mkdir -p "$(dirname "$CONFIG_FILE")" if [ -f "$CONFIG_FILE" ]; then cp -p "$CONFIG_FILE" "$CONFIG_FILE.backup-$(date +%Y%m%d-%H%M%S)" else printf '%s\n' '{"$schema":"https://opencode.ai/config.json","provider":{}}' > "$CONFIG_FILE" fi RESPONSES_PROVIDER=$(jq -cn \ --arg base "$RELAY_BASE_URL" \ --arg model "$RESPONSES_MODEL_ID" \ '{ name: "AI Gateway (OpenAI Responses)", env: ["CLICKZETTA_API_KEY"], npm: "@ai-sdk/openai", options: {baseURL: $base}, models: {($model): {name: $model}} }') TMP_FILE=$(mktemp) jq \ --argjson provider "$RESPONSES_PROVIDER" \ --arg provider_id "$RESPONSES_PROVIDER_ID" \ --arg model "$RESPONSES_MODEL_ID" \ '.provider = (.provider // {}) | .provider[$provider_id] as $existing | .provider[$provider_id] = (($existing // {}) * $provider) | .provider[$provider_id].models = (($existing.models? // {}) + $provider.models) | .model = ($provider_id + "/" + $model)' \ "$CONFIG_FILE" > "$TMP_FILE" && mv "$TMP_FILE" "$CONFIG_FILE" jq empty "$CONFIG_FILE" opencode debug config >/dev/null && echo 'OpenAI Responses provider 配置成功'

@ai-sdk/openai

@ai-sdk/openai-compatible

8.5 手动编辑配置文件

如果你不希望使用 Terminal 写入命令，也可以用编辑器打开配置文件：

open -e "$HOME/.config/opencode/opencode.json"

下面 JSON 是最小手动编辑示例。保存前，将示例模型 ID 换成第 7 节已经测试成功的模型；不要把不存在于自己目录的模型直接复制进去。

{ "$schema": "https://opencode.ai/config.json", "model": "my-relay/openai/gpt-5.5", "provider": { "my-relay": { "name": "AI Gateway (OpenAI Chat)", "env": ["CLICKZETTA_API_KEY"], "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1" }, "models": { "openai/gpt-5.5": { "name": "OpenAI model example" } } }, "my-relay-anthropic": { "name": "AI Gateway (Anthropic Messages)", "env": ["CLICKZETTA_API_KEY"], "npm": "@ai-sdk/anthropic", "options": { "baseURL": "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1" }, "models": { "anthropic/claude-opus-5": { "name": "Anthropic model example" } } } } }

配置文件中不保存 API Key，OpenCode 会从环境变量

CLICKZETTA_API_KEY

如果需要手动加入 Responses provider，请以第 8.4 节的

my-relay-responses

provider

my-relay

npm

@ai-sdk/openai

8.6 目录中出现但请求失败的模型

有些模型会出现在

/models

No upstream candidates

model_not_found

502

遇到这种情况，不要为了让模型出现在 OpenCode 列表中而继续保留它。先记录模型 ID、请求协议、HTTP 状态码和脱敏错误，联系中转站确认路由；只有对应协议返回最终文本后，再加入配置。

8.7 按自己的目录调整模型

当自己的模型目录与本文示例配置不同，只调整

models

1. OpenAI 目录没有的模型，从

   my-relay.models

   my-relay.models
   删除；
2. Anthropic 目录没有的模型，从

   my-relay-anthropic.models

   my-relay-anthropic.models
   删除；
3. 同一个 Qwen 或 DeepSeek ID 如果多个协议都验证成功，可以分别放入对应 provider；
4. 对本文示例网关，Claude 放入

   my-relay-anthropic.models

   my-relay-anthropic.models
   ，不要因为 ID 中有

   anthropic/

   anthropic/
   就直接放进

   my-relay

   my-relay
   ；只有 Claude 同时出现在 OpenAI 认证视图，并且 Chat curl 与 OpenCode 调用都返回最终文本时，才可以额外配置 OpenAI Chat 路径；
5. 新增模型前必须先执行对应协议的 curl，并确认响应中有最终文本；
6. 不要为了让模型出现在 OpenCode 列表中而伪造模型 ID，列表显示不等于实际可用。

**下一步：**保存 JSON 后，先做语法和 OpenCode 配置校验。

9. 校验 OpenCode 配置

9.1 校验 JSON 语法

jq empty "$HOME/.config/opencode/opencode.json"

没有任何输出且退出码为 0，表示 JSON 语法正确。

9.2 校验 OpenCode schema

opencode debug config

正常情况下会输出解析后的配置，不能出现

Config validation failed

expected object

unknown key

如果出现：

Invalid input: expected object, received string

通常是把 provider 对象写成了字符串，或者把新版本

providers

provider

provider.my-relay

provider.my-relay-anthropic

9.3 查看已配置 provider 的模型

如果你在第 8 节使用了自定义 provider ID，请把下面命令中的名称替换为实际 ID。

opencode models my-relay opencode models my-relay-anthropic # 仅在第 8.4 节配置了 Responses provider 时执行： # opencode models my-relay-responses

如果配置了 Responses provider，请删除最后一行开头的

# 

这些命令会列出你写入配置文件的模型。这里列出模型只代表配置已登记，不代表每个请求都成功，还要执行第 10 节的实际调用。

**下一步：**使用第 10 节的

opencode run

10. 在 OpenCode 中实际调用

首次验证建议使用独立临时目录，避免 OpenCode 读取当前项目的代码、指令文件或会话上下文。在 Terminal 执行：

TEST_DIR="$(mktemp -d "${TMPDIR:-/tmp}/opencode-gateway-test.XXXXXX")" printf '本次测试目录：%s\n' "$TEST_DIR"

后面的首次测试命令都使用

--dir "$TEST_DIR"

10.1 调用 OpenAI Chat provider

如果你使用了自定义 provider ID，请把命令中的

my-relay

下面使用

openai/gpt-5.5

opencode run \ --dir "$TEST_DIR" \ --model my-relay/openai/gpt-5.5 \ --format json \ '请只回复：OK'

成功时 JSON 中应有模型输出文本。

如果需要测试 DeepSeek，并且自己的目录中存在该模型，先把它加入

my-relay.models

opencode run \ --dir "$TEST_DIR" \ --model my-relay/deepseek/deepseek-v4-pro \ --format json \ '请只回复：OK'

10.2 调用 OpenAI Responses provider（按需）

只有已经执行第 7.2 节和第 8.4 节时，才运行此命令。把示例 ID 替换成你在

/responses

opencode run \ --dir "$TEST_DIR" \ --model my-relay-responses/openai/gpt-5.5 \ --format json \ '请只回复：OK'

如果这条命令成功，说明 OpenCode 已用

@ai-sdk/openai

/responses

10.3 调用 Anthropic provider

如果你使用了自定义 provider ID，请把命令中的

my-relay-anthropic

下面使用

anthropic/claude-opus-5

my-relay-anthropic

opencode run \ --dir "$TEST_DIR" \ --model my-relay-anthropic/anthropic/claude-opus-5 \ --format json \ '请只回复：OK'

如果自己的 Anthropic 目录中有 Sonnet 或 Haiku，先把对应 ID 加入

my-relay-anthropic.models

opencode run --dir "$TEST_DIR" --model my-relay-anthropic/anthropic/claude-sonnet-5 --format json '请只回复：OK' opencode run --dir "$TEST_DIR" --model my-relay-anthropic/anthropic/claude-haiku-4.5 --format json '请只回复：OK'

10.4 默认模型

配置文件中的：

{ "model": "my-relay/openai/gpt-5.5" }

表示未指定

--model

{ "model": "my-relay-anthropic/anthropic/claude-sonnet-5" }

修改后重新执行

opencode debug config

10.5 配置完成后的效果和判断标准

完成配置后，你至少应看到一个自己有权限的模型返回最终文本。如果 API Key 同时有 OpenAI 和 Anthropic 模型权限，再分别检查下面两类结果：

OpenAI Chat provider：返回 OK my-relay/openai/gpt-5.5 Anthropic Messages provider：返回 OK my-relay-anthropic/anthropic/claude-opus-5

如果两类调用都成功，说明：

• OpenCode 能读取配置文件；
• API Key 已通过环境变量传入；
• OpenAI Compatible Chat 路由可用；
• Anthropic Messages 路由可用；
• 至少一个 OpenAI 模型和一个 Claude 模型完成了端到端调用。

如果 API Key 没有 Claude 权限，只检查 OpenAI Chat；如果没有 OpenAI 模型，则只检查 Anthropic provider。不要为了满足示例而添加自己目录中不存在的模型。

这不说明所有模型都可用，也不说明所有高级能力都可用。其他模型必须按照第 11 节的厂商和协议规则选择 provider，并按第 7 节和本节命令单独检查。

**下一步：**按第 11 节的厂商和协议规则选择模型，不要只根据模型名称猜测协议。

11. 按厂商和协议选择模型

模型 ID 由中转站返回，厂商名称或 ID 前缀不能单独决定请求协议。配置时先确认模型属于哪类厂商，再根据该模型在你的目录和测试结果选择 provider。

下面的说明用于帮助你完成配置，不是固定模型清单。模型数量、版本和权限可能随 API Key、套餐和上游路由变化。

11.1 目录和请求结果怎么理解

No upstream candidates

UPSTREAM_ALL_FAILED

Upstream failed

/models

“成功”必须同时满足 HTTP 200 和有最终文本。HTTP 200 但只有思考块、没有最终文本时，仍应继续检查输出预算和响应解析。

11.2 厂商类型与协议选择

my-relay

my-relay-responses

my-relay-anthropic

anthropic/

/models

这里的“通常”表示常见适配方式，不是自动路由规则。每个模型仍需以自己的目录、协议请求和 OpenCode 调用结果为准。

11.3 OpenCode 配置写法

模型引用始终使用下面的格式：

<provider-id>/<model-id>

常见写法：

my-relay/openai/gpt-5.5 my-relay-responses/openai/gpt-5.5 my-relay-anthropic/anthropic/claude-opus-5 my-relay/deepseek/deepseek-v4-pro my-relay-anthropic/deepseek/deepseek-v4-pro

最后两个示例只有在 DeepSeek 分别通过 OpenAI Chat 和 Anthropic Messages 成功时才同时成立。以下写法不会自动改变协议：

my-relay/anthropic/claude-opus-5 my-relay-anthropic/openai/gpt-5.5

11.4 选择模型的实际步骤

对每个准备使用的模型，按以下顺序操作：

1. 确认模型 ID 出现在对应认证方式的

   /models

   /models
   中；
2. 用第 7 节的 OpenAI Chat、Responses 或 Anthropic Messages 请求测试；
3. 只有 HTTP 200 且有最终文本时，才把模型放入对应 provider；
4. 使用第 10 节的

   opencode run

   opencode run
   进行实际调用；
5. OpenCode 失败时，先用同一模型、同一协议的 curl 对照，判断是网关问题还是客户端配置问题。

11.5 Claude 模型 ID 的写法

Claude 版本号和标点是路由键的一部分，必须原样复制：

下面只展示写法示例，不代表 Claude 只有这些版本。请以自己的 Anthropic

/models

正确：anthropic/claude-opus-4.8 错误：anthropic/claude-opus-4-8 正确：anthropic/claude-sonnet-4.6 错误：anthropic/claude-sonnet-4-6 正确：anthropic/claude-haiku-4.5 错误：anthropic/claude-haiku-4-5

错误的连字符版本会返回

No upstream candidates

11.6 OpenCode 能力边界

本文配置覆盖三种请求方式，其中 Responses 是按需配置：

my-relay

@ai-sdk/openai-compatible

/v1/chat/completions

my-relay-responses

@ai-sdk/openai

/v1/responses

my-relay-anthropic

@ai-sdk/anthropic

/v1/messages

模型能否调用，应该这样理解：

1. “目录中出现”表示 API Key 能看到模型 ID；
2. “协议调用成功”表示该模型在某一个协议下返回最终文本；
3. “OpenCode 调用成功”表示对应 provider、模型 ID 和客户端参数组合可以工作；
4. 以上结论只适用于对应协议，不会自动推广到其他协议；
5. 文本调用成功，不代表工具调用、流式、多模态、结构化输出、缓存、长上下文或思考参数都可用。

因此，对本文示例网关，Claude 优先使用

my-relay-anthropic

my-relay

my-relay-responses

**下一步：**需要进一步了解协议字段时，阅读第 12 节；遇到错误时进入第 13 节。

12. OpenCode 的请求协议限制

12.1 三种协议的硬性差异

协议不能只修改 URL 后继续沿用另一种请求体。客户端必须同时匹配端点、认证头、请求结构和响应解析方式。

POST /v1/chat/completions

POST /v1/responses

POST /v1/messages

Authorization: Bearer API_KEY

Authorization: Bearer API_KEY

x-api-key: API_KEY

anthropic-version: 2023-06-01

messages

max_tokens

input

max_output_tokens

messages

max_tokens

system

choices[0].message.content

output[].content[].text

output_text

content[]

type=text

text

my-relay

my-relay-responses

my-relay-anthropic

必须遵守：

1. anthropic/claude-opus-5

   anthropic/claude-opus-5
   中的

   anthropic/

   anthropic/
   只是模型 ID 的一部分，不会自动选择 Anthropic runtime；

2. my-relay/anthropic/claude-opus-5

   my-relay/anthropic/claude-opus-5
   仍走 OpenAI Chat；如果该模型没有通过 Chat 验证，不应使用此写法；

3. my-relay-anthropic/anthropic/claude-opus-5

   my-relay-anthropic/anthropic/claude-opus-5
   会走本文已经验证的 Anthropic Messages 路径；

4. Authorization: Bearer

   Authorization: Bearer
   和

   x-api-key + anthropic-version

   x-api-key + anthropic-version
   会得到不同模型视图，不能只查询一次

   /models

   /models
   ；
5. Chat 成功不代表 Responses 成功；同一个模型需要分别测试；
6. Anthropic Messages 成功不代表 OpenAI Chat 成功；Claude 通常应使用 Anthropic provider；
7. AI Gateway 不保证自动把 OpenAI

   tool_calls

   tool_calls
   转成 Anthropic

   tool_use

   tool_use
   ，也不保证反向转换。

12.2 Responses 必须使用独立 provider

my-relay

@ai-sdk/openai-compatible → OpenAI Compatible Chat Completions

它不会因为某个模型在

/v1/responses

my-relay-responses

@ai-sdk/openai

my-relay

12.3 OpenCode 不自动回退

一次调用选定 provider 后，请求协议固定：

Chat 失败 ≠ 自动改用 Responses ≠ 自动改用 Anthropic Messages ≠ 自动换成另一个模型

需要切换协议时，必须显式选择另一个 provider；需要切换模型时，必须显式填写另一个精确 ID。

12.4 SDK 可能改变请求参数

OpenCode 通过 AI SDK runtime 组装请求。即使裸 curl 成功，客户端仍可能因为自动添加思考、工具、结构化输出或流式相关字段而出现差异。

本文只要求最小文本请求成功，不等于以下能力都已确认：

• streaming 流式输出；
• tool calling / function calling；
• JSON schema 或严格结构化输出；
• 图像、文件和多模态输入；
• prompt caching；
• 长上下文接近上限时的行为；
• 模型特定的思考预算字段。

例如某些客户端给请求加入不被中转站接受的

thinking_budget

12.5 配置上限不是服务端承诺

示例中的：

{ "limit": { "context": 200000, "output": 8192 } }

只是告诉 OpenCode 如何估算上下文和输出预算。它不能扩大模型实际能力、账号额度或中转站限制，也不能保证所有模型都支持相同的工具、图像或思考能力。

**下一步：**如果请求失败，按第 13 节从网络、认证、协议、模型和 provider 逐层排查。

13. 常见错误与定位顺序

13.1 先看错误属于哪一层

建议按以下顺序定位：

网络连接 ↓ 认证头和 API Key ↓ 端点和请求协议 ↓ 模型 ID 与协议路由 ↓ OpenCode provider runtime ↓ 高级参数、工具或流式能力

13.2 错误对照表

Could not resolve host

401

403

No upstream candidates

/models

model_not_found

4.8

4.6

4-8

4-6

502

503

upstream failed

my-relay-anthropic

my-relay

expected object, received string

provider

1.18.18

provider

1024

4096

database is locked

13.3

No upstream candidates

No upstream candidates

的判断方法

按以下顺序执行：

opencode models my-relay opencode models my-relay-anthropic

然后分别用第 7 节的请求测试同一个模型：

OpenAI 模型 → /chat/completions + Bearer Claude 模型 → /messages + x-api-key + anthropic-version

如果正确的模型 ID 在正确协议下仍然失败，才需要让中转站检查上游候选、账号权限和路由配置。不要通过不断修改 provider 名称或在模型 ID 中添加后缀来“碰运气”。

13.4 如何区分 VPN 问题和模型问题

连接不上域名 / TLS 超时 → 网络、代理、防火墙或 VPN HTTP 401 / 403 → API Key 或权限 HTTP 400 No upstream candidates → 模型、协议或上游路由 HTTP 502 upstream failed → 上游暂时故障或模型未路由 HTTP 200 有文本 → 该协议、该模型、该 API Key 的最小调用成功

**下一步：**确认问题层级后，阅读第 14 节了解使用边界和提交问题所需信息。

14. 如何判断产品支持范围

模型是否能在 OpenCode 中使用，不只取决于模型名称，还取决于 API Key 权限、请求协议、provider 配置和上游路由。遇到不同模型时，可以用下面的方式判断：

14.1 四种结果分别代表什么

/models

/models

14.2 使用产品时需要遵守的边界

1. Base URL 必须使用中转站提供的地址，并确认是否已经包含

   /v1

   /v1
   ；
2. OpenAI 和 Anthropic 的认证头不同，不能混用；

3. my-relay

   my-relay
   代表 OpenAI Compatible Chat，

   my-relay-responses

   my-relay-responses
   代表 OpenAI Responses，

   my-relay-anthropic

   my-relay-anthropic
   代表 Anthropic Messages；
4. 本文示例网关的 Claude 优先使用 Anthropic Messages；模型 ID 中出现

   anthropic/

   anthropic/
   不会自动切换协议；
5. Responses 必须按第 8.4 节配置独立 provider，不能把 Chat provider 当成 Responses provider；
6. 模型在某个协议下成功，不代表在其他协议下也成功；
7. 最小文本调用成功，不代表工具、流式、多模态、结构化输出、缓存、长上下文或思考参数都可用；
8. 模型名称、版本号和标点必须与

   /models

   /models
   返回值完全一致。

14.3 提交问题时应提供什么

如果按照本文仍然失败，无需提供 API Key。请提供以下脱敏信息：

• OpenCode 版本：

  opencode --version

  opencode --version
  ；
• 使用的 provider ID：例如

  my-relay

  my-relay
  或

  my-relay-anthropic

  my-relay-anthropic
  ；
• 模型 ID；
• 使用的协议：OpenAI Chat、Responses 或 Anthropic Messages；
• HTTP 状态码；
• 请求时间和 request ID；
• 脱敏后的错误摘要；

• opencode debug config

  opencode debug config
  是否通过。

不要直接粘贴完整的

opencode run --format json

Authorization

x-api-key

• virtualApiKeyAlias

  virtualApiKeyAlias
  、

  tenantId

  tenantId
  等租户信息；
• 上游供应商名称、上游 Base URL 和账号别名；

• endpoint_id

  endpoint_id
  、内部路由编号和完整重试历史；
• 完整

  responseBody

  responseBody
  ，其中可能再次嵌套上述信息。

request ID 通常可以保留，用于支持人员查询服务端日志。支持人员会根据版本、时间、模型、协议、HTTP 状态和 request ID 判断网络、权限或上游路由问题。

**下一步：**完成第 15 节安全检查，再用第 16 节清单逐项确认。

15. 安全与日常运维

15.1 API Key 安全

• 不要把 Key 写入

  opencode.json

  opencode.json
  ；
• 不要把 Key 写入命令参数、聊天记录、工单、截图或 Git；
• 不要在排查时执行

  env

  env
  、

  set

  set
  或

  echo "$CLICKZETTA_API_KEY"

  echo "$CLICKZETTA_API_KEY"
  ；
• 分享日志前，删除

  Authorization

  Authorization
  、

  x-api-key

  x-api-key
  、Cookie、租户信息、上游地址、内部端点编号、完整重试历史和请求体中的敏感字段；
• 不要直接分享

  opencode run --format json

  opencode run --format json
  的完整错误事件，先按第 14.3 节整理为脱敏摘要；
• 怀疑泄露时立即在中转站后台撤销并重新生成 Key。

**下一步：**完成第 16 节的最终成功检查。

15.2 配置备份和恢复

修改前备份：

cp -p "$HOME/.config/opencode/opencode.json" \ "$HOME/.config/opencode/opencode.json.$(date +%Y%m%d-%H%M%S).bak"

恢复时先确认目标文件路径，再覆盖当前配置。恢复后必须重新执行：

jq empty "$HOME/.config/opencode/opencode.json" opencode debug config

15.3 什么时候需要重新验证

以下情况发生后，应重新执行

/models

• 中转站更换 Base URL 或网关版本；
• API Key 权限、套餐或上游账号变化；
• 模型版本号或模型 ID 变化；
• OpenCode 或 AI SDK runtime 升级；
• 出现持续的

  502

  502
  、

  No upstream candidates

  No upstream candidates
  或输出格式异常。

16. 最终成功检查表

逐项确认：

• opencode --version

  opencode --version
  能返回版本；

• CLICKZETTA_API_KEY

  CLICKZETTA_API_KEY
  已加载，但没有写进配置文件；

• RELAY_BASE_URL

  RELAY_BASE_URL
  只包含一个

  /v1

  /v1
  ；
• 已查询自己的 OpenAI 和 Anthropic

  /models

  /models
  ，没有盲目复制本文示例模型；
• OpenAI

  /models

  /models
  已按自己的 API Key 确认 OpenAI/DeepSeek/Qwen 视图；
• Anthropic

  /models

  /models
  已按自己的 API Key 确认 Qwen、DeepSeek 和 Claude 权限范围；

• my-relay

  my-relay
  使用

  @ai-sdk/openai-compatible

  @ai-sdk/openai-compatible
  ；
• 如使用 Responses，

  my-relay-responses

  my-relay-responses
  使用

  @ai-sdk/openai

  @ai-sdk/openai
  ；

• my-relay-anthropic

  my-relay-anthropic
  使用

  @ai-sdk/anthropic

  @ai-sdk/anthropic
  ；

• jq empty

  jq empty
  通过；

• opencode debug config

  opencode debug config
  通过；
• 每个已配置 provider 都能通过

  opencode models <provider-id>

  opencode models <provider-id>
  列出模型；
• 首次实际调用使用了独立临时目录，没有在业务项目目录中直接测试；
• 至少一个自己目录中的 OpenAI Chat 模型实际调用成功；
• 如使用 Responses，至少一个 Responses 模型通过

  my-relay-responses

  my-relay-responses
  实际调用成功；
• 如果 API Key 有 Claude 权限，至少一个 Claude 模型通过

  my-relay-anthropic

  my-relay-anthropic
  实际调用成功；
• 每个准备使用的模型都在自己的对应协议目录中，并完成了最小文本请求；
• Claude 使用点号版本 ID，而不是连字符版本 ID；
• 没有把 OpenCode 的 Chat provider 当成 Responses provider；
• 最小文本测试成功，没有把未确认的工具、流式、多模态能力当成已支持。

17. 一键复查命令

下面命令不会打印 API Key，可在排查时依次执行：

echo "OpenCode: $(opencode --version)" echo "Config: $HOME/.config/opencode/opencode.json" test -n "$CLICKZETTA_API_KEY" && echo 'API Key: loaded' || echo 'API Key: missing' jq empty "$HOME/.config/opencode/opencode.json" && echo 'JSON: valid' opencode debug config >/dev/null && echo 'OpenCode config: valid' opencode models my-relay opencode models my-relay-anthropic # 仅在已配置 Responses provider 时执行： # opencode models my-relay-responses

最小实际调用：

下面命令使用示例模型。如果自己的实时目录没有对应 ID，请替换为同一协议下已经验证成功的模型；不要因为模型 ID 不同，就修改 provider runtime。第三条仅在你已配置并验证 Responses provider 时执行。

if [ -z "${TEST_DIR:-}" ]; then TEST_DIR="$(mktemp -d "${TMPDIR:-/tmp}/opencode-gateway-test.XXXXXX")" fi printf '本次测试目录：%s\n' "$TEST_DIR" opencode run --dir "$TEST_DIR" --model my-relay/openai/gpt-5.5 --format json '请只回复：OK' opencode run --dir "$TEST_DIR" --model my-relay-anthropic/anthropic/claude-opus-5 --format json '请只回复：OK' # opencode run --dir "$TEST_DIR" --model my-relay-responses/openai/gpt-5.5 --format json '请只回复：OK'

如果已配置的模型都返回实际文本，说明 OpenCode 已通过相应协议接入中转站。其他模型仍应按照第 11 节的厂商和协议规则选择 provider。

18. 结论

OpenCode 接入中转站的核心不是“把 Base URL 填进去”，而是同时满足以下关系：

模型 ID + provider ID + AI SDK runtime + 请求端点 + 认证头 + 上游协议路由 = 实际可用调用

配置时可以先记住三条：

OpenAI、DeepSeek、Qwen（Chat） → my-relay/<model-id> OpenAI Responses → my-relay-responses/<model-id> Claude，以及 Anthropic 方式调用的 Qwen/DeepSeek → my-relay-anthropic/<model-id>

Claude 一般使用 Anthropic Messages；OpenAI 系列使用 Chat 或 Responses 时分别使用对应 runtime；DeepSeek、Qwen 和其他厂商模型需要根据自己的目录和协议测试结果选择 provider。任何新模型或新协议都应先经过

/models

19. 相关资料

• OpenCode Providers 官方文档：自定义 OpenAI Compatible provider、Anthropic provider、

  baseURL

  baseURL
  和模型配置。
• OpenCode Config 官方文档：配置文件、默认模型和 provider 配置项。
• OpenCode 官方下载页面：安装脚本、npm、Homebrew 等安装方式。