# 在 TRAE（TraeCode）中把 Router One 添加为自定义模型

> https://router.one/zh/integrations/trae 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-27

TRAE 的 AI IDE 在国际版（trae.ai）和国内版（trae.cn）文档中都已更名为 TraeCode。在「设置 > 模型 > 添加模型」中选择「自定义模型」，填写 API 格式（OpenAI Chat Completions 或 Anthropic Messages）、请求地址、模型 ID 和 API 密钥，选中这个模型后，TraeCode 发出的请求就会用你的 Key 发到 Router One，每个请求的 Token、花费和状态都记录在控制台 → 日志中。截至 2026-09-27，两个版本的内置模型列表里都没有 Claude；要在 TraeCode 里用 Claude 模型，就得把它添加为自定义模型。按 TraeCode 3.3.101（国内版，2026-09-15 发布）与两个版本的 TRAE 模型文档核对（2026-09-27）。

## 添加之前：哪些请求会走 Router One Key

TraeCode 的「添加模型」窗口有两种来源：「模型服务商」只需粘贴该服务商的 API 密钥；「自定义模型」则由你自己设置 API 格式、请求地址、模型 ID 和鉴权信息。Router One 要用「自定义模型」添加。只有选中这个自定义模型时，请求才会发到 Router One：TRAE 文档写明，Auto 模式只调用内置模型，不会调用你添加的自定义模型，所以要在对话输入框右下角的模型菜单里关闭 Auto Mode。Max 模式文档列出的可用模型也都是内置模型；自定义模型的上下文上限由「高级配置」中的「上下文窗口」决定。先在控制台为 TraeCode 单独创建一把设了 maxSpend 的 Router One Key，再从 /models 复制一个对话模型 ID，例如 anthropic/claude-sonnet-5、openai/gpt-5.5 或 deepseek-v4.1-flash。

## 把 TRAE 配置到 Router One base URL

打开「设置 > 模型」，点「添加模型」，选择「自定义模型」。「API 格式」选「OpenAI Chat Completions 格式」，关闭「完整 URL」开关，「自定义请求地址」填 https://api.router.one/v1：TraeCode 会按所选 API 格式自动拼接请求路径，国际版文档中的示例基础地址 https://api.openai.com/v1 也是这种写法。「模型 ID」填 /models 上的精确 ID，「模型展示名称」可选，「API 密钥」填这把专用 Router One Key。首次测试时「高级配置」保持默认，「模型系列」选「默认」，然后点「添加模型」：TraeCode 会先检测连接，成功后才把模型加入列表。以 Claude 的 ID 为例，填好的表单如下：

`traecode-custom-model`

```text
# TraeCode：设置 > 模型 > 添加模型 > 自定义模型
# TraeCode: Settings > Models > Add Model > Custom Model
API 格式 / API Format:                OpenAI Chat Completions
完整 URL / Full URL:                  关闭 / Off
自定义请求地址 / Custom Request URL:  https://api.router.one/v1
模型 ID / Model ID:                   anthropic/claude-sonnet-5
模型展示名称 / Display Name:          Claude Sonnet 5 (Router One)
API 密钥 / API Key:                   sk-your-router-one-key

# 高级配置 / Advanced Settings（首次测试 / first test）
模型系列 / Model Series:              默认 / Default
上下文窗口 / Context Window:          输入与输出留空 / input and output empty (TraeCode defaults)
支持图片输入 / Image Input Support:   仅当模型详情页列出图片输入时开启 / On only if the model page lists image input
思考模式 / Thinking Mode:             跟随模型默认配置 / Follow model default

# Claude 与 DeepSeek V4 的 ID 也可以选 Anthropic 格式 / Claude and DeepSeek V4 IDs can use the Anthropic format instead:
#   API 格式 / API Format: Anthropic Messages，完整 URL 关闭 / Full URL off: https://api.router.one
# 完整 URL 打开 / Full URL on: https://api.router.one/v1/chat/completions
#                     或 / or https://api.router.one/v1/messages
```

## 每个 Router One 模型 ID 该选哪种 API 格式和地址

TraeCode 的拼接规则与文档一致：关闭「完整 URL」时，OpenAI Chat Completions 格式填以 /v1 结尾的基础地址，Anthropic Messages 格式填主机根地址；打开「完整 URL」时，填完整的接口地址。Router One 在 Chat Completions 上提供目录中的全部对话模型，在 Messages 上提供 Claude 系列与 DeepSeek V4 的 ID，所以 API 格式要按模型 ID 来选。GPT、Gemini 或 Grok 的 ID 用 Anthropic Messages 格式发送时，会在调用任何模型之前被拒绝并返回 HTTP 400，错误信息会指明应走的路径（model '<id>' must be called via …）；把这个模型改成 OpenAI Chat Completions 格式即可。Router One 同时接受 Authorization: Bearer 和 x-api-key 两种请求头传递的 Key，所以两种格式可以共用同一把 Key。aws/claude-sonnet-5 这类渠道 ID 是单独定价的目录条目；不带前缀或带厂商前缀的 ID 走默认渠道。

| TraeCode 的 API 格式 | 关闭完整 URL | 打开完整 URL | 适用的 Router One 模型 ID |
| --- | --- | --- | --- |
| OpenAI Chat Completions 格式 | https://api.router.one/v1 | https://api.router.one/v1/chat/completions | 目录中的全部对话模型：Claude、GPT、Gemini、Grok 与 DeepSeek 的 ID |
| Anthropic Messages 格式 | https://api.router.one | https://api.router.one/v1/messages | Claude 系列 ID（含 aws/claude-… 与 vertex/claude-… 渠道 ID），以及 deepseek-v4.1-flash、deepseek-v4-flash |

## 高级配置：模型系列、上下文窗口、工具调用轮数与图片输入

高级配置会改变 TraeCode 组装请求的方式，首次测试请保持默认，之后每次只改一项：

- 模型系列：先选「默认」，普通请求成功后再考虑更换。两个版本都提供 GPT-5 系列、Gemini-3 系列、DeepSeek-4 系列和「默认」；国内版的 Claude-4 系列、GPT-6 系列等选项仅企业版可用。按 TRAE 文档，GPT-5 系列会把输出上限字段从 max_tokens 换成 max_completion_tokens，把 Temperature 固定为 1，并启用 GPT-5 专属 Prompt 模板。Router One 的 Chat Completions 参考文档以 max_tokens 作为输出上限；客户端允许选择时，请发送 max_tokens，在 TraeCode 中就是选「默认」。DeepSeek-4 系列默认开启思考模式，国际版文档还注明该选项不支持图片输入。
- 上下文窗口：分「输入」和「输出」两个值，留空时使用 TraeCode 内置的默认值。填写「输入」时，不要超过该模型在 Router One 详情页上的上下文窗口（anthropic/claude-sonnet-5 为 1,048,576 tokens，openai/gpt-5.5 为 1,050,000，deepseek-v4.1-flash 为 1,000,000）：窗口越大，长时间的 Agent 会话每次请求可带的输入越多，而每个输入 Token 都会计费。「输出」是你自己设定的上限。
- 工具调用轮数：限制单次任务中模型最多调用工具的轮数。每一轮都是一次计费请求，保持默认或调低即可。
- 支持图片输入：只有模型详情页列出图片输入时才开启；例如 deepseek-v4-flash 只支持文本。
- 工具调用与思考模式：Agent 依赖工具调用，优先选详情页列出工具调用的 ID；其他 ID 先试一次工具调用。「思考模式」首次测试时选「跟随模型默认配置」。

## 看懂「添加模型」的检测结果，并在日志中核对首批请求

点「添加模型」后，TraeCode 会调用服务接口检测 Key；检测失败时，窗口会显示错误信息和服务返回的日志。对照 Router One 的常见原因：401 表示 Key 缺失或错误；404 通常是地址与「完整 URL」开关不匹配，例如开关关闭时仍填了完整的 /v1/chat/completions 地址，或 Anthropic Messages 格式填了 https://api.router.one/v1，TraeCode 会在已经以 /v1 结尾的地址后再拼接 /v1/messages；400 且提示 must be called via，说明这个 ID 需要另一种 API 格式；402 表示钱包余额或该 Key 的 maxSpend 已用完。TRAE 文档没有说明检测本身是否会发出计费的模型请求，添加后可到控制台 → 日志查看。之后选中自定义模型发一条简单消息，在日志中按时间、模型和 request_id 找到这次请求：可以看到 Token、花费、状态、总耗时，以及产生过输出的流式请求的首字延迟（TTFT）。一次 Agent 任务可能每一轮工具调用都产生一次请求，所以请给 TraeCode 单独一把设了 maxSpend 的 Key：触顶后该 Key 的请求返回 HTTP 402，其他 Key 不受影响。

## TRAE 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 TRAE 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个客户端或应用单独建 API Key，并设置 maxSpend 消费上限。

## TRAE 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

## 在请求日志里核对 TRAE 的调用

先在 TRAE 发出一次简单文本请求，再到控制台 → 日志按时间、模型和 request_id 找到这条记录，核对 Token、花费、总耗时和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### 在 TRAE 里从哪里添加自定义模型？

在 TraeCode 中打开「设置 > 模型」，点「添加模型」，选择「自定义模型」（不要选预设的模型服务商），依次填写「API 格式」「自定义请求地址」（含「完整 URL」开关）「模型 ID」「模型展示名称」和「API 密钥」，需要时再展开「高级配置」。添加后可以在同一面板编辑、删除、启用或禁用该模型；禁用的模型仍保留在模型管理面板中，但不会出现在对话框的模型列表里。国际版界面对应的路径是 Settings > Models > Add Model > Custom Model。

### 能通过 Router One 在 TRAE 里用 Claude 模型吗？

可以，以自定义模型的方式添加。截至 2026-09-27，TraeCode 两个版本的内置模型列表里都没有 Claude；TRAE 国内版文档中的「常用模型推荐配置速查」也建议 Claude-4 系列使用 Anthropic Messages 格式。接入 Router One 时，anthropic/claude-sonnet-5 这类 Claude ID 既可以用 Anthropic Messages 格式（https://api.router.one），也可以用 OpenAI Chat Completions 格式（https://api.router.one/v1）。「模型系列」请保持「默认」：国内版的 Claude-4 系列选项仅企业版可用，国际版文档中没有这个选项。Router One 按模型公示价格对这把 Key 的每个请求计费；这是用你自己的 Key 使用 TraeCode 的自定义模型功能，不代表 TRAE 与 Router One 之间有任何合作关系。

### 为什么 TraeCode 仍在用内置模型回答？

Auto 模式开着，或者没有选中自定义模型。TRAE 文档写明，Auto 模式只在内置模型中选择，不会调用你添加的自定义模型。在对话输入框右下角打开模型菜单，关闭 Auto Mode，再按展示名称选中 Router One 的模型。如果列表里找不到它，到「设置 > 模型」确认该模型已启用。没有到达 Router One 的请求不会出现在控制台 → 日志里。

### 要不要打开「完整 URL」开关？

开关与填写的值对得上就行。关闭时填基础地址：OpenAI Chat Completions 格式填 https://api.router.one/v1，Anthropic Messages 格式填 https://api.router.one，由 TraeCode 拼接路径；打开时填完整的接口地址：https://api.router.one/v1/chat/completions 或 https://api.router.one/v1/messages。两者不匹配时，路径会重复或缺一段，通常返回 404。

### TRAE 能通过网关用哪些模型？

选用当前目录中同时支持 TRAE 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只说明它从自身配置或 GET /v1/models 读到了这个 ID，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

### 报 401/402/403/429 怎么排查？

先到控制台 → 日志核对这条请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- TRAE 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- Qoder 接入：https://router.one/zh/integrations/qoder
- CodeBuddy 接入：https://router.one/zh/integrations/codebuddy
- Cursor 接入：另一款可自带 Key 的 AI IDE：https://router.one/zh/integrations/cursor
- Claude API 价格与充值：https://router.one/zh/cheap-claude-api
- 连接与 /v1 路径排查：https://router.one/zh/api-connection-troubleshooting
- 跨模型工具调用：https://router.one/zh/llm-tool-calling
- TRAE 官方文档：内置模型 & 自定义模型：https://docs.trae.cn/ide/models
- TRAE 官方文档：Auto 模式：https://docs.trae.cn/ide/auto-mode
- TRAE 国际版文档：模型设置：https://docs.trae.ai/ide/models
- TraeCode 更新日志：https://docs.trae.cn/ide/changelog
- 统一 LLM API 网关概览：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/trae
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md