这是一份面向 TRAE 国际版用户的操作指南。按照文档顺序完成后，你可以把 AI Gateway 中的自定义模型添加到 TRAE，并确认 TRAE Agent 确实在使用你选择的模型。

完成本指南后，你将能够：

  • 确认安装的是 TRAE 国际版并完成登录；
  • 安全输入 AI Gateway 的 Base URL 和 API Key；
  • 查询自己的 API Key 在 OpenAI 和 Anthropic 两种协议视图中可以看到的模型；
  • 根据模型和协议边界选择 OpenAI Chat 或 Anthropic Messages；
  • 用标准 
    curl
    curl
    验证模型是否能返回最终文本；
  • 在 TRAE 中添加自定义模型并完成连通性测试；
  • 关闭 Auto Mode，使用 TRAE Agent 发送第一条真实消息；
  • 根据错误信息判断问题属于网络、鉴权、路径、协议、权限还是上游。

示例 AI Gateway Base URL：

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

如果你使用的中转站地址不同，请替换 Base URL、API Key 和模型 ID。不要把真实 API Key 发到聊天、工单、截图、Git 仓库或公开网页。

官方入口：

先看结论

TRAE 国际版的“自定义模型”支持两种 API 格式：

格式TRAE 自定义模型是否支持请求端点
OpenAI Chat Completions支持
/chat/completions
/chat/completions
Anthropic Messages支持
/v1/messages
/v1/messages
OpenAI Responses不支持
/responses
/responses

配置能否完成，取决于四件事：

  1. API Key 能否在目标协议的模型目录中看到模型；
  2. 模型在该协议下能否通过标准 HTTP 请求返回文本；
  3. TRAE 中的 API 格式、URL 和模型 ID 是否填写正确；
  4. TRAE Agent 是否明确选择了自定义模型并返回文本。

模型名称前缀不会自动切换协议。模型 ID 写成 

anthropic/claude-opus-5
anthropic/claude-opus-5
，并不代表 TRAE 会自动使用 Anthropic Messages；必须在 TRAE 的 API 格式中明确选择 Anthropic Messages。

0. 配置流程

安装并登录 TRAE 国际版 ↓ 准备 Base URL、API Key、模型 ID ↓ 根据协议查询模型目录 ↓ 用同一协议的标准 curl 验证 ↓ 在 TRAE 添加自定义模型 ↓ 通过 TRAE 连通性测试 ↓ 打开项目、关闭 Auto Mode ↓ 选择自定义模型并发送 Agent 消息

不要跳过标准 

curl
curl
验证。它可以先区分“网络/鉴权/路径/上游问题”和“TRAE 页面配置问题”，排查会更快。

1. 准备 TRAE 国际版

1.1 区分中国版和国际版

界面语言不能作为判断依据，国际版也可以显示简体中文。请使用应用 Bundle ID 判断：

项目中国版国际版
常见应用名
Trae CN.app
Trae CN.app
Trae.app
Trae.app
Bundle ID
cn.trae.app
cn.trae.app
com.trae.app
com.trae.app
官网
trae.com.cn
trae.com.cn
trae.ai
trae.ai

1.2 在 Terminal 检查版本

按 

Command + Space
Command + Space
，输入 
Terminal
Terminal
，按回车打开终端。

如果 TRAE 安装在当前用户的 Applications 目录，执行：

TRAE_APP="$HOME/Applications/Trae.app" if [ -d "$TRAE_APP" ]; then defaults read "$TRAE_APP/Contents/Info" CFBundleIdentifier defaults read "$TRAE_APP/Contents/Info" CFBundleShortVersionString else echo '没有在 ~/Applications 找到 Trae.app' fi

国际版必须输出：

com.trae.app

如果安装在系统 Applications 目录，执行：

defaults read "/Applications/Trae.app/Contents/Info" CFBundleIdentifier defaults read "/Applications/Trae.app/Contents/Info" CFBundleShortVersionString

1.3 如果安装的是中国版

先退出 TRAE，再从 TRAE 国际版下载页 下载国际版。不要直接删除用户数据目录，以免丢失登录状态或本地配置。

安装完成后重新执行第 1.2 节，确认 Bundle ID 为 

com.trae.app
com.trae.app
。

TRAE IDE 需要满足下载页列出的 macOS 系统要求。Apple Silicon Mac 请选择 

macOS (Apple Silicon)
macOS (Apple Silicon)
安装包。

1.4 登录并确认自定义模型入口

启动 

Trae.app
Trae.app
，完成国际版账号登录，然后确认：

  1. TRAE 主界面可以正常打开；
  2. 左下角账号菜单可以显示当前账号；
  3. 设置中可以进入 
    Models
    Models
    或“模型”；
  4. 页面中存在 
    Add Custom Model
    Add Custom Model
    、
    Custom Models
    Custom Models
    或对应的中文入口。

如果看不到自定义模型入口，先确认应用版本、登录状态和是否误装了中国版。

1.5 检查 Terminal 工具

后续命令使用 

curl
curl
发送 HTTP 请求，使用 
jq
jq
生成 JSON 和读取响应。

执行：

command -v curl command -v jq

正常情况下会输出两个命令路径，例如：

/usr/bin/curl /opt/homebrew/bin/jq

macOS 默认带有 

curl
curl
。如果没有 
jq
jq
，且已经安装 Homebrew，执行：

brew install jq

1.6 是否需要 VPN

是否需要 VPN 取决于所在网络，不取决于 OpenAI 或 Anthropic 协议。

只有在以下情况出现时，才需要检查网络代理或 VPN：

  • trae.ai
    trae.ai
    下载页面无法打开；
  • curl
    curl
    报 
    Could not resolve host
    Could not resolve host
    ；
  • curl
    curl
    连接超时或无法建立连接；
  • TRAE 登录页面无法加载。

如果已经收到 HTTP 200、401、403、404、429 或 5xx，说明请求通常已经到达服务器，应先按状态码排查 API Key、URL、权限、限流或上游问题，不要先把它判断为 VPN 问题。

2. 准备中转站信息

2.1 Base URL

示例 Base URL：

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

这个地址已经包含 

/v1
/v1
。OpenAI Chat 配置时不要再手动追加 
/v1
/v1
或 
/chat/completions
/chat/completions
，除非你打开了 TRAE 的“完整 URL”选项。

Anthropic Messages 的 URL 规则不同，第 8 节会给出两种正确填写方式。

2.2 API Key

确认：

  • API Key 未过期；
  • API Key 有目标模型的调用权限；
  • API Key 和 Base URL 属于同一个环境；
  • 复制时没有多余空格或换行；
  • API Key 没有泄露。

2.3 模型 ID

模型 ID 是路由键，必须从你自己的模型目录中原样复制。

正确示例：

openai/gpt-5.5 anthropic/claude-opus-5 deepseek/deepseek-v4-pro qwen/qwen3.6-flash

错误示例：

gpt-5.5 anthropic/claude-opus-4-8 anthropic/claude-sonnet-4-6

不要省略厂商前缀，不要自行修改点号、连字符或版本号。

3. 厂商与协议边界

3.1 TRAE 支持的协议

TRAE 自定义模型页面支持：

API 格式鉴权方式TRAE 自定义模型
OpenAI Chat Completions
Authorization: Bearer API_KEY
Authorization: Bearer API_KEY
支持
Anthropic Messages
x-api-key
x-api-key
加 
anthropic-version: 2023-06-01
anthropic-version: 2023-06-01
支持
OpenAI Responses
Authorization: Bearer API_KEY
Authorization: Bearer API_KEY
不支持

TRAE 不能因为模型名称或厂商前缀自动改变请求格式。协议必须在模型配置页面中手动选择。

3.2 不同厂商模型的选择原则

模型类别首选协议其他协议TRAE 中的配置方式注意事项
OpenAI 模型OpenAI Chat Completions某些模型或网关也可能提供 ResponsesOpenAI Chat CompletionsTRAE 自定义模型不能选择 Responses；必须确认 Chat 路由可用
Anthropic ClaudeAnthropic Messages通常没有 OpenAI Chat 或 Responses 路由Anthropic Messages不要因为模型 ID 含 
anthropic/
anthropic/
就省略 API 格式选择
DeepSeek 模型由具体模型和网关路由决定部分模型可能同时提供 OpenAI Chat 和 Anthropic Messages以成功的协议 
curl
curl
为准		不要根据厂商名推断所有 DeepSeek 模型都支持同一协议
Qwen 模型由具体模型和网关路由决定部分模型可能提供 OpenAI Chat、Responses 或 Anthropic Messages以成功的协议 
curl
curl
为准		Responses 即使可用，也不能在 TRAE 自定义模型中选择
其他厂商模型以协议目录和标准请求为准以协议目录和标准请求为准只配置验证成功的格式厂商名称不等于协议能力

这里的“厂商”只帮助你确定排查方向，不能替代模型级验证。最终以“模型 ID + API Key + 协议 + 网关路由”的组合结果为准。

3.3 同一个模型支持两种协议时

如果同一个模型在 OpenAI 和 Anthropic 两套目录中都能看到，并且两种标准 

curl
curl
都返回 HTTP 200，可以在 TRAE 中分别创建两条配置：

同一个模型 + OpenAI Chat Completions 同一个模型 + Anthropic Messages

两条配置的 API 格式、鉴权头、URL 和响应解析方式不同，不能互相复制。一个协议成功，也不能推断另一个协议成功。

3.4 OpenAI Responses 的边界

某个模型的 Responses 请求即使成功，也不能直接添加到 TRAE 自定义模型中，因为 TRAE 当前没有 OpenAI Responses 自定义格式。

因此：

  • Chat Completions 成功的模型，可以按 OpenAI 格式添加；
  • Anthropic Messages 成功的模型，可以按 Anthropic 格式添加；
  • 只支持 Responses 的模型，不能通过 TRAE 自定义模型直接接入；
  • 其他使用 Responses 的工具配置不能直接复制到 TRAE。

3.5 模型目录不是固定清单

模型目录由 API Key 的租户、权限、套餐、额度、地区和上游发布状态决定。不同用户看到的模型可能不同。

配置时只使用你自己的 

/models
/models
返回结果：

自己的模型目录 → 选择模型 ID 同协议 curl 成功 → 选择 TRAE API 格式 TRAE 连通性测试成功 → 继续 Agent 实际验证

如果模型不在自己的协议目录中，不要手动猜测模型 ID，也不要只修改 URL。需要增加模型权限时，请联系 AI Gateway 服务支持。

4. 在 Terminal 安全输入 API Key

不要把 API Key 直接写进命令历史。在同一个 Terminal 执行：

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

粘贴时屏幕不显示字符是正常的。

只检查变量是否为空，不显示 API Key：

if [ -n "$RELAY_API_KEY" ]; then echo 'API Key 已载入当前 Terminal' else echo 'API Key 为空，请重新输入' fi

完成验证前不要关闭这个 Terminal。关闭后变量会消失。

5. 查询自己的模型目录

TRAE 不会自动导入 AI Gateway 的全部模型。先查询目录，再选择模型。

5.1 查询 OpenAI 协议目录

执行：

curl -sS -o /tmp/trae-openai-models.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/models" \ -H "Authorization: Bearer $RELAY_API_KEY" jq -r '.data[]?.id' /tmp/trae-openai-models.json

这条命令查询的是 OpenAI 协议视图。它只显示当前 API Key 在该协议下能看到的模型。

5.2 查询 Anthropic 协议目录

执行：

curl -sS -o /tmp/trae-anthropic-models.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/models" \ -H "x-api-key: $RELAY_API_KEY" \ -H 'anthropic-version: 2023-06-01' jq -r '.data[]?.id' /tmp/trae-anthropic-models.json

这条命令查询的是 Anthropic 协议视图。Claude、DeepSeek、Qwen 或其他厂商模型是否出现，以当前 API Key 的实际输出为准。

5.3 目录、curl 和 TRAE 分别说明什么

这三个结果对应三个不同阶段，不要把它们当成同一个“成功”标记：

结果能说明什么下一步
/models
/models
中有模型		当前 API Key 在该协议视图中能看到完整模型 ID继续做同协议 
curl
curl
同协议 
curl
curl
返回 HTTP 200 和最终文本		AI Gateway 的该模型路由可以完成基础文本请求在 TRAE 选择相同 API 格式
TRAE 连通性测试成功TRAE 的 URL、API 格式和 API Key 已基本匹配打开项目并完成 Agent 实际验证
TRAE Agent 返回最终文本TRAE、AI Gateway、协议和模型的基础文本链路已接通开始使用或按需验证高级能力

5.4 为什么两套目录可能不同

中转站会根据请求头判断协议：

Authorization: Bearer → OpenAI 协议目录 x-api-key + anthropic-version → Anthropic 协议目录

因此：

  • OpenAI 目录中没有 Claude，不一定表示 Claude 不可用；
  • Anthropic 目录中没有 OpenAI 模型，不一定表示 OpenAI 不可用；
  • 一个模型出现在目录中，只表示它可被发现，不代表请求一定成功；
  • 目录中没有模型时，不要手动添加或修改模型名称。

5.5 目录请求状态码

状态码说明处理方式
HTTP 200网络和基本鉴权正常继续验证模型
HTTP 401API Key 缺失、错误或失效重新输入 API Key
HTTP 403API Key 没有访问权限检查租户、套餐和模型权限
HTTP 404Base URL 或路径错误检查是否填写到 
/gateway/v1
/gateway/v1
HTTP 429限流或额度不足等待后重试或更换额度
HTTP 5xx网关或上游故障保存错误信息并稍后重试
DNS 失败或连接超时网络、代理或 VPN 问题检查网络环境

6. 用标准 curl 验证模型

选择模型后，必须使用与 TRAE 相同的协议验证。标准请求成功后，再打开 TRAE 配置页面。

6.1 验证 OpenAI Chat Completions

把模型 ID 替换为你自己的模型：

export RELAY_MODEL='openai/gpt-5.5'

执行：

curl -sS -o /tmp/trae-openai-test.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/chat/completions" \ -H "Authorization: Bearer $RELAY_API_KEY" \ -H 'Content-Type: application/json' \ -d "$(jq -cn \ --arg model "$RELAY_MODEL" \ '{model:$model,max_tokens:256,messages:[{role:"user",content:"请只回复：OpenAI 测试成功"}]}')" jq -r '.choices[0].message.content // .error.message // "未找到最终文本，请查看完整响应"' \ /tmp/trae-openai-test.json

成功标准：

HTTP 200 OpenAI 测试成功

6.2 验证 Anthropic Messages

把模型 ID 替换为你自己的 Anthropic 协议模型：

export RELAY_MODEL='anthropic/claude-opus-5'

执行：

curl -sS -o /tmp/trae-anthropic-test.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/messages" \ -H "x-api-key: $RELAY_API_KEY" \ -H 'anthropic-version: 2023-06-01' \ -H 'Content-Type: application/json' \ -d "$(jq -cn \ --arg model "$RELAY_MODEL" \ '{model:$model,max_tokens:256,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 // "未找到最终文本，请查看完整响应") end' \ /tmp/trae-anthropic-test.json

成功标准：

HTTP 200 Anthropic 测试成功

6.3 HTTP 200 但没有最终文本

部分推理模型会消耗较多输出预算。如果只有 thinking/reasoning，没有最终文本，可以提高：

max_tokens: 256

到：

max_tokens: 1024

或：

max_tokens: 4096

只有“HTTP 200 + 正常结束 + 最终文本”才算验证成功。

7. 在 TRAE 配置 OpenAI Chat 模型

7.1 打开自定义模型页面

在 TRAE 国际版中打开：

右上角设置 → 模型 → 添加模型 → 自定义模型

不要选择 TRAE 内置的 OpenAI 服务商预设。使用自有 AI Gateway 时，必须选择“自定义模型”。

7.2 推荐填写方式：关闭完整 URL

填写：

字段值
API 格式
OpenAI Chat Completions 格式
OpenAI Chat Completions 格式
完整 URL关闭
自定义请求地址
https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1
https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1
模型 ID从自己的 OpenAI 目录原样复制
模型展示名称可留空，或填写便于识别的名称
API 密钥自己的 AI Gateway API Key

关闭“完整 URL”时，TRAE 会自动追加：

/chat/completions

最终请求地址应为：

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

7.3 OpenAI 完整 URL 写法

也可以打开“完整 URL”，直接填写：

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

两种写法只能选一种。不要在已经关闭“完整 URL”的情况下填写带 

/chat/completions
/chat/completions
的地址，否则会重复拼接。

7.4 保存并测试

点击“添加模型”或“保存”。TRAE 会发起一次真实连接测试，可能消耗少量 Token。

连通性测试成功后：

  • 自定义模型出现在模型列表；
  • 模型开关可以启用；
  • 没有 401、403、404 或上游错误。

保存成功只表示连接测试通过，还要完成第 9 节的 Agent 实际验证。

8. 在 TRAE 配置 Anthropic Messages 模型

8.1 推荐填写方式：打开完整 URL

进入：

设置 → 模型 → 添加模型 → 自定义模型

填写：

字段值
API 格式
Anthropic Messages 格式
Anthropic Messages 格式
完整 URL开启
自定义请求地址
https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/messages
https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/messages
模型 ID从自己的 Anthropic 目录原样复制
模型展示名称可留空
API 密钥自己的 AI Gateway API Key

打开“完整 URL”时，TRAE 不会再追加路径。最终请求地址就是：

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

8.2 关闭完整 URL 的写法

如果关闭“完整 URL”，基础地址只能填写到：

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

TRAE 会自动追加：

/v1/messages

最终地址仍然是：

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

不要在关闭“完整 URL”时填写 

.../gateway/v1
.../gateway/v1
，否则会变成：

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

这个地址通常会返回 404。

8.3 保存并测试

点击“添加模型”或“保存”。如果连通性测试成功，自定义模型会出现在模型列表中。

如果返回 

No upstream candidates
No upstream candidates
，优先检查：

  1. 模型 ID 是否从 Anthropic 目录原样复制；
  2. API 格式是否确实选择 Anthropic Messages；
  3. URL 是否为 
    /gateway/v1/messages
    /gateway/v1/messages
    ；
  4. API Key 是否有该模型权限。

9. 用 TRAE Agent 实际验证

连通性测试成功后，还需要在真实 Agent 会话中确认模型选择和返回结果。

9.1 打开项目文件夹

点击：

打开文件夹

可以打开已有代码项目，也可以新建空文件夹进行测试。

如果没有打开项目，TRAE 可能提示：

请先打开文件夹以保存项目中的文件

这表示缺少项目上下文，不等于 API 连接失败。

9.2 关闭 Auto Mode

如果模型选择器显示 

Auto
Auto
，先关闭 Auto Mode。Auto Mode 可能选择 TRAE 内置模型，无法确认请求是否经过你的 AI Gateway。

9.3 选择自定义模型

在 Agent 输入框底部打开模型选择器，选择刚刚添加的自定义模型。

确认选择器显示的是目标自定义模型，而不是：

Auto GPT-5.4 其他 TRAE 内置模型

9.4 发送最小消息

OpenAI Chat 测试：

请只回复：TRAE relay 正常

Anthropic Messages 测试：

请只回复：TRAE Claude 正常

成功标准：

  1. 用户消息出现在会话中；
  2. Agent 结束分析状态；
  3. 返回预期文本；
  4. 没有 401、403、404、429、502 或其他上游错误；
  5. 模型选择器仍显示目标自定义模型。

10. 添加第二种协议或更多模型

10.1 添加第二种协议

如果已经配置并验证了 OpenAI Chat，还要使用 Claude 或其他 Anthropic 协议模型，不需要重新安装 TRAE，也不需要删除已有模型：

  1. 执行第 5.2 节，查询 Anthropic 协议目录；
  2. 执行第 6.2 节，使用目标模型发送 Anthropic Messages 请求；
  3. 执行第 8 节，新增一条 Anthropic 自定义模型；
  4. 执行第 9 节，打开项目、关闭 Auto Mode 并选择新模型；
  5. 发送 Anthropic 测试消息，确认新模型返回最终文本。

OpenAI Chat 和 Anthropic Messages 是两条独立配置。保留已有模型不会影响新增模型。

10.2 添加更多模型

每增加一个模型，都要按照“目录 → 同协议 

curl
curl
→ TRAE 连通性 → Agent 消息”的顺序验证。

同一个模型如果支持两种协议，可以分别添加两条记录：

同一个模型 + OpenAI Chat Completions 同一个模型 + Anthropic Messages

两条记录的 API 格式、URL、鉴权方式和请求结构不能混用。建议先添加一个已经通过完整流程的模型，再逐个增加其他模型，方便定位问题。

如果新增模型没有出现在自己的协议目录中，或同协议 

curl
curl
返回 400、401、403、429 或 5xx，请先停止 TRAE 配置，确认 API Key 权限和上游路由。

11. 产品支持边界

11.1 可以完成的能力

通过 TRAE 自定义模型和 AI Gateway，可以完成：

  • 在 TRAE 中配置自定义 Base URL；
  • 使用自己的 API Key；
  • 使用通过协议验证的 OpenAI Chat 模型；
  • 使用通过协议验证的 Anthropic Messages 模型；
  • 在 Agent/SOLO 会话中进行文本对话和代码任务；
  • 根据不同模型选择对应协议和模型 ID。

11.2 不应直接推断的能力

文本对话验证成功，不代表以下能力一定可用：

  • OpenAI Responses；
  • CUE 或代码补全；
  • Code Review；
  • Git 提交信息生成；
  • 流式 SSE；
  • 工具调用和多轮工具结果；
  • 图片、PDF、音频等多模态输入；
  • JSON Schema 或结构化输出；
  • Prompt Cache；
  • Extended Thinking；
  • 超长上下文；
  • 并行 Agent、Max Mode 或其他 TRAE 专属功能。

这些能力需要 TRAE、网关、模型上游和请求参数同时支持，应单独验证。

11.3 内置模型、自定义模型和 Auto Mode

三者不是同一类配置：

类型说明
TRAE 内置模型由 TRAE 账号、地区、套餐和服务端配置决定
服务商预设使用对应服务商的官方接口字段
自定义模型使用你填写的 AI Gateway 地址、API Key 和模型 ID
Auto Mode由 TRAE 自动选择模型，不能用于确认指定自定义模型

选择自定义模型时，不要同时依赖 Auto Mode。

11.4 配置成功不等于永久稳定

模型上游可能发生限流、额度不足、临时 5xx、资源不足、长上下文限制或参数不兼容。

遇到偶发失败时，先重新执行同协议 

curl
curl
。如果 
curl
curl
也失败，问题在 TRAE 之外；如果 
curl
curl
成功而 TRAE 失败，再检查 TRAE 的 API 格式、URL、项目文件夹和模型选择。

12. 常见问题排查

12.1 找不到 Anthropic Messages

依次确认：

  1. 使用的是 TRAE 国际版；
  2. Bundle ID 为 
    com.trae.app
    com.trae.app
    ；
  3. 已登录国际版账号；
  4. 进入的是“添加模型 → 自定义模型”；
  5. TRAE 版本支持 Anthropic Messages。

12.2 连通性测试返回 404

先检查是否重复拼接路径。

OpenAI 错误地址：

/gateway/v1/chat/completions/chat/completions

Anthropic 错误地址：

/gateway/v1/v1/messages

正确方式：

  • OpenAI：关闭完整 URL，填到 
    /gateway/v1
    /gateway/v1
    ；
  • Anthropic：推荐打开完整 URL，填写完整 
    /gateway/v1/messages
    /gateway/v1/messages
    。

12.3 HTTP 401 或 403

可能原因：

  • API Key 错误或过期；
  • API Key 没有模型权限；
  • Base URL 与 API Key 不属于同一环境；
  • 使用了错误协议的鉴权头。

先在 Terminal 重新执行第 5 节和第 6 节命令。

12.4 No upstream candidates

常见原因：

  • 模型 ID 拼写错误；
  • 选择了错误 API 格式；
  • 当前 API Key 没有该模型权限；
  • 当前协议没有该模型路由。

处理顺序：

  1. 查询对应协议的 
    /models
    /models
    ；
  2. 原样复制模型 ID；
  3. 使用相同协议的标准 
    curl
    curl
    ；
  4. 检查 TRAE API 格式；
  5. 检查完整 URL 和自动拼接规则。

12.5 HTTP 429

HTTP 429 通常表示限流、额度不足或并发限制。

处理方式：

  1. 等待后重试；
  2. 检查账户额度和模型权限；
  3. 降低请求频率；
  4. 不要通过反复点击“添加模型”来测试。

12.6 HTTP 5xx

HTTP 5xx 表示网关或上游调用失败，常见原因包括上游暂时不可用、供应商资源不足、模型参数不兼容或网关故障。

保存以下信息后联系 AI Gateway 服务支持：

  • 模型 ID；
  • 请求协议；
  • HTTP 状态码；
  • 错误信息；
  • 发生时间；
  • request ID 或 trace ID。

发送前删除 API Key、Authorization 和 

x-api-key
x-api-key
。

12.7 模型已添加但 Agent 不回复

依次检查：

  1. 是否打开了项目文件夹；
  2. 是否关闭 Auto Mode；
  3. 是否明确选择自定义模型；
  4. 自定义模型开关是否启用；
  5. 标准 
    curl
    curl
    是否仍然成功；
  6. 是否出现 401、404、429 或 5xx。

12.8 TRAE 实际使用了内置模型

如果输出结果不像目标模型，或请求没有到达 AI Gateway：

  1. 关闭 Auto Mode；
  2. 在输入框底部重新选择自定义模型；
  3. 新建会话；
  4. 使用最小测试消息重试。

12.9 HTTP 200 但没有最终文本

可能是输出预算被 thinking/reasoning 消耗，或请求格式和响应解析不匹配。

先提高 

max_tokens
max_tokens
，再确认：

  • OpenAI 读取 
    .choices[0].message.content
    .choices[0].message.content
    ；
  • Anthropic 读取 
    .content[]
    .content[]
    中 
    type=text
    type=text
    的 
    .text
    .text
    ；
  • 请求没有把 Anthropic Body 发到 OpenAI 端点，或反过来。

13. API Key 安全

请遵守：

  • 不要把 API Key 写进文档、脚本或公开仓库；
  • 不要分享包含 API Key 的配置截图；
  • 不要执行 
    echo "$RELAY_API_KEY"
    echo "$RELAY_API_KEY"
    ；
  • 不要把带鉴权头的调试命令截图发出；
  • API Key 泄露后立即撤销并重新生成；
  • 不同客户、项目和环境使用不同 API Key。

完成测试后清理变量：

unset RELAY_API_KEY unset RELAY_BASE_URL unset RELAY_MODEL

如果使用剪贴板粘贴过 API Key，可以清空 macOS 剪贴板：

pbcopy </dev/null

14. 完成检查

安装与登录

[ ] 安装 TRAE 国际版 [ ] Bundle ID 为 com.trae.app [ ] macOS 版本满足要求 [ ] 已完成国际版账号登录 [ ] 设置中能进入自定义模型页面

AI Gateway

[ ] Base URL 正确 [ ] API Key 未过期且未泄露 [ ] 使用自己的 API Key 查询了目标协议的 /models [ ] 模型 ID 从目录原样复制 [ ] 选择了与 curl 相同的 API 协议 [ ] 同协议 curl 返回 HTTP 200 [ ] curl 响应中有最终文本

TRAE

[ ] OpenAI 使用 Chat Completions 格式 [ ] Anthropic 使用 Messages 格式 [ ] 没有在 TRAE 中选择 OpenAI Responses [ ] OpenAI URL 没有重复 /chat/completions [ ] Anthropic URL 没有重复 /v1/messages [ ] 自定义模型保存成功 [ ] TRAE 连通性测试成功

Agent

[ ] 已打开项目文件夹 [ ] 已关闭 Auto Mode [ ] 当前会话明确选择自定义模型 [ ] Agent 返回预期文本 [ ] 没有 401、403、404、429 或 5xx [ ] 高级能力单独验证并单独记录

全部完成后，说明 TRAE 已通过 AI Gateway 接入指定模型并完成实际文本调用。

如果只有目录可见，写“模型可发现”；如果标准 

curl
curl
成功，写“协议调用成功”；如果 TRAE 连通性和 Agent 消息也成功，才可以写“TRAE 已验证可用”。

15. 相关资料

TRAE 和 AI Gateway 都可能更新。遇到页面字段或命令结果与文档不完全一致时，优先确认 TRAE 版本、API 格式、完整 URL 和目标协议，再按照第 12 节的状态码顺序排查。

Codex CLI配置指南
Kilo Code配置指南
Yunqi © 2024 Yunqi, Inc. All Rights Reserved.
联系我们
预约咨询
微信咨询
电话咨询
邮件咨询