反向代理 / 反代
客户端把 Base URL 指向 127.0.0.1:8791，由它替你去访问官方上游并把响应带回来。这个名字强调的是谁在真正发出上游请求——客户端版本头、Authorization: Bearer 鉴权、流式解析全部在这一跳完成，客户端一行协议代码都不用改。
OPENAI 兼容网关 · v1.0.0 · MIT · 零 pip 依赖
把 Trae 双区，
接成一个 OpenAI 端点。
Trae2API-Hub 把 Trae 国际版与国内版的原生模型服务封装成标准 OpenAI 兼容 API—— Chat Completions、Responses 与 Anthropic Messages 三协议同时在线。双区账号池、自动换区、 额度预警与自动降级、API Key 配额治理、8 页签看板，全部由一个纯标准库的 Python 进程承担。
1.0.0 的关键变化：国际版不再需要 Trae 桌面版。 Docker、Linux 无桌面环境可直接运行。
- 可直接驱动
- Codex CLI
- Claude Code
- Cursor
- Cline
- Continue
- OpenAI SDK
国际版
Gemini-3.1-Pro-Preview
200 · chunked
GET /pingpong
调度器运行中
自动降级armed
2区域独立出口
3协议 Chat / Responses / Messages
35模型目录 CN 25 + INTL 10
0外部 pip 依赖
204项离线自检断言全通过
8791默认端口
它也常被叫作
同一件事有四五种叫法。
它们强调的不是同一个层面。
搜「Trae 反代」「Trae 中转」「Trae 网关」「Trae 协议适配」找过来的，多半是同一件事。搞清楚你要的是哪一层，才知道该配哪个客户端、该看哪个日志、出问题该查哪一跳。
API 中转 / 中转站
一层 OpenAI 协议进、Trae 协议出，中间夹着账号池轮换、出口绑定、冷却与配额。强调的是流量经过它：换号、重试、故障切换、额度降级都发生在中转这一跳，客户端只看到一个稳定的端点和一个自己的 Key。
协议适配
Chat Completions、Responses、Anthropic Messages 三种入站协议映射到上游 llm_raw_chat，含流式 SSE、reasoning_content、工具调用与 DSML 回退解析。强调的是翻译而不是转发——思考档位、工具信封、错误码都要逐字段对齐。
网关中枢
除转发之外还有账号生命周期、每日签到与 Token 保活、整点调度、额度快照、用量指标、配置备份恢复与 Web 看板。强调的是它是一个有状态的控制面，而不只是一根管子——这也是它和一次性脚本的分界线。
常见搜法：Trae 反代 · Trae API 中转 · Trae 签到 · Trae Docker 部署 · Codex 接入 Trae · Claude Code 接入 Trae · Trae 转 OpenAI · Trae 协议适配
01 / 双区域
两套官方服务，两种链路。
网关让它们各走各的门。
国际版与国内版的域名、鉴权方案、模型清单都不相同。网关按区域独立配置账号、独立选号、独立计量；模型按归属自动路由，你也可以用 ?realm= 或 X-Realm 显式钉死出口——显式指定永远优先。
国际版 · INTL
core-normal.traeapi.us
直连 HTTP，不依赖桌面版
- 当前客户端版本头 +
Authorization: Bearer <access_token> - 直接调用官方
llm_raw_chat，无需启动 Trae、调试端口 - 不需要
websocket-client，Docker / Linux 无桌面环境可跑 - 目录 10 个模型，其中 6 个 Free 可用
- 额度快照解析
notify_usage，暴露/quota
国内版 · CN
api.trae.com.cn
沿用成熟链路
- 目录 25 个模型，覆盖面更宽
- 与国际版独立的账号池、冷却与轮换策略
- 可作为国际版额度耗尽时的降级出口
- 同一套看板里并列展示，状态一眼可比
- Key 可绑定固定出口，不随调度漂移
自动换区的判定顺序
- 显式指定
?realm=intl/X-Realm: cn—— 永远优先，不被覆盖 - Key 绑定API Key 上配置的固定出口 —— 保证同一客户端不换区
- 模型归属按模型目录自动路由到拥有该模型的区域
- 额度与降级额度耗尽或需升级时切到备用模型 / 出口，写
X-Trae-Degraded
02 / v1.0.0 直连
国际版从「得开着一个客户端」
变成「一条 docker 命令」。
旧方案要在本机跑起 Trae 桌面版、调试端口、引入 websocket-client 才能拿到国际版响应。1.0.0 重做了鉴权链路，服务器、容器、无头 Linux 都能直接跑。
1.0.0 之前
需要桌面版在场
4015— 客户端版本头过期，上游直接拒4023— 鉴权方案不对，签名对不上- 依赖本机 Trae 进程与调试端口
- 额外引入
websocket-client - 容器化困难，无头环境跑不起来
1.0.0 现在
纯 HTTP 直连官方接口
- 当前客户端版本头，不再触发
4015 Authorization: Bearer <access_token>，不再触发4023- 直接调用官方
llm_raw_chat - CN / INTL 推理链路零 pip 依赖
- Docker Compose 与 GHCR 多架构镜像开箱即用
错误码不做伪装
官方免费额度用尽返回 4008 quota exceeded，网关统一转成 HTTP 429 + Retry-After: 60：不冷却账号，也不把它包装成 4015 风控。需要升级的模型返回 upgrade_required=true，同样直说。你能从状态码判断真正发生了什么，而不是对着一个含糊的「被风控了」猜。
03 / 模型目录
目录保留官方展示名、
上下文、最大输出与思考档位。
以当前目录快照为准：国内版 25 个、国际版 10 个。/v1/models 支持按区域过滤，看板「模型库」页签把 Free 与升级标记一并列出。
国际版 INTL 10 个 · 其中 6 个 Free 可用
| 模型 | 状态 |
|---|---|
Gemini-3.1-Pro-Preview | Free |
Gemini-3-Flash-Preview | Free |
Gemini-2.5-Pro | Free |
Gemini-2.5-Flash | Free |
Kimi-K2-0905 | Free |
Grok-4 | Free |
Claude-Opus-4.7 | 需升级 |
Claude-Sonnet-4.6 | 需升级 |
GPT-5.5 | 需升级 |
GPT-6-Astra | 需升级 |
国内版另有 25 个模型，含 Doubao-1.5-pro 等常用作降级出口的型号；完整清单以 GET /v1/models?realm=cn 的实时返回为准。
04 / 能力矩阵
不是一个转发脚本，
是一个有状态的控制面。
转发只占它一小部分。账号生命周期、配额治理、降级策略、定时任务与用量透视，才是它能 7×24 挂着的原因。
双区账号池与轮换
多账号、权重、启停、冷却、失败重试与自动轮换。双区独立选号，Key 可绑定固定出口，不会在区域之间漂。
会话亲和
同一对话优先固定账号，让上游的 prompt cache 尽量命中——长对话里这直接体现在首字延迟和 token 成本上。
额度预警 + 自动降级
额度耗尽或模型需升级时，自动切到备用模型 / 出口，响应头写 X-Trae-Degraded。面板顶部告警，账号行标注 INTL 额度已用尽。默认关闭，设置页显式开启。
API Key 模型白名单
每个 Key 可限定 Gemini-*、Kimi-* 这类 fnmatch 通配，大小写不敏感，留空即不限制。模型不匹配返回 400 并附中文说明。
Key 级日配额
daily_requests / daily_tokens，0 表示不限制。超限返回 429。计数取自 usage.jsonl，10 秒缓存，不额外增加上游调用。
按 Key 用量透视
请求数、Token、缓存命中、平均延迟、模型分布与最近请求，逐个 Key 拆开看。哪个客户端在烧额度一目了然。
7×24 定时任务
Token 保活、用量刷新、每日签到与模型探测常驻调度，不用你手动跑脚本维持凭证有效。
配置备份 / 恢复
一键导出面板密码、API Key、limits、auto_degrade 与双区凭证；恢复前自动写 config-backup-<时间>.json。两个接口都需要面板 token。
流式与工具调用
流式 SSE、reasoning_content、工具调用与 DSML 回退解析，兼容 Cursor、Continue、Cline、Codex、Claude Code 与 OpenAI SDK。
05 / 监控看板
单文件看板，8 个页签，
桌面与移动端都自适应。
看板与网关同源同端口，打开 http://127.0.0.1:8791/ 即是。图表用零依赖 Canvas 手绘，不拉外部资源。以下为仓库内真实截图。
06 / 部署
双击脚本，或者一条 docker 命令。
三种方式任选。本机脚本适合先试，Docker Compose 适合长期挂着，GHCR 镜像适合不想拉源码的场景。
推荐先试这种。Windows 双击 .bat，Linux / macOS 跑 .sh。
start-trae2api-hub.batchmod +x start-trae2api-hub.sh
./start-trae2api-hub.sh- API Base
http://127.0.0.1:8791/v1 - 看板
http://127.0.0.1:8791/ - 面板默认密码
admin（登录后请立即修改） - 局域网访问改用
start-trae2api-hub-lan.bat/.sh
git clone https://github.com/shuishuipingan/trae2api-hub.git
cd trae2api-hub
docker compose up -d --build
docker compose logs -f首次以 LAN 模式启动会生成随机 API Key 并打印在日志里：
docker compose logs trae2api-hub | grep -i "api key"- 端口
8791 - 持久化
./accounts（凭证 / 设置）、./usage（用量流水） - 环境变量
HOST/PORT/API_KEY/TZ可覆盖 - 健康检查
GET /ping
docker pull ghcr.io/shuishuipingan/trae2api-hub:latest
docker run -d --name trae2api-hub --restart unless-stopped \
-p 8791:8791 \
-v $(pwd)/accounts:/app/accounts \
-v $(pwd)/usage:/app/usage \
-e TZ=Asia/Shanghai \
ghcr.io/shuishuipingan/trae2api-hub:latest- 架构
amd64+arm64多架构镜像 - 必须挂载
/app/accounts与/app/usage - 监听
0.0.0.0:8791 - 版本记录Releases · GHCR Packages
数据目录含 token、refresh token、面板密码哈希与 API Key，绝不要提交到 Git；.gitignore 已排除。配置导出文件同样包含密钥，妥善保管。
生成你的客户端配置
选一个客户端，直接复制。<YOUR_API_KEY> 换成看板里生成并绑定出口的 Key。
07 / 接口
看板与接口，全部同源。
同一个进程、同一个端口。对外是 OpenAI 兼容协议，对内是看板与运维接口。
推理协议
POST /v1/chat/completionsOpenAI Chat Completions，支持流式与工具调用POST /v1/responsesOpenAI Responses，Codex / Claude Code 走这条POST /v1/messagesAnthropic Messages 适配GET /v1/models模型目录，支持?realm=intl/?realm=cn
额度与运维
GET /quota·/v1/quota额度快照，解析自notify_usageGET /ping健康检查，返回 pongGET /config/export?download=1导出设置与双区凭证，需面板 tokenPOST /config/restore恢复配置，恢复前自动备份，需面板 token
值得知道的响应头
X-Trae-Degraded自动降级发生时写入，形如 Gemini-3.1-Pro-Preview -> Doubao-1.5-pro (quota)，让你知道这次实际用的是哪个模型。
X-Realm请求侧显式钉死出口，优先级高于自动路由。
Retry-After额度耗尽时随 429 返回 60，客户端可据此退避而不是立刻重试。
离线自检
python _test_trae.py
python _diag_gateway.py --chat当前基线
PASS=204 FAIL=0 SKIP=0
断言全部离线确定性执行，不依赖真实上游账号，可以在 CI 里跑。
08 / FAQ
接入时最容易卡住的几件事。
国际版还需要装 Trae 桌面版吗？
1.0.0 之后不需要。旧版本因为客户端版本头过期会返回 4015、鉴权方案不对会返回 4023。现在国际版直接用当前客户端版本头加 Authorization: Bearer <access_token> 调用官方 llm_raw_chat，Docker 与 Linux 无桌面环境可以直接运行。
模型名称应该填什么？
填 /v1/models 返回的 id，也就是官方模型名，例如 Gemini-3.1-Pro-Preview 或 Doubao-1.5-pro。区域独占模型会自动路由到归属出口；需要钉死区域时用 ?realm= 或 X-Realm。
额度用完了会怎样？会不会把账号搞冷却？
官方返回 4008 quota exceeded 时，网关统一转成 HTTP 429 并带 Retry-After: 60，不会冷却账号，也不会伪装成 4015 风控。面板顶部会显示国际版额度告警，账号行标注 INTL 额度已用尽。开启自动降级后会切到备用模型 / 出口并写入 X-Trae-Degraded。
Codex CLI 与 Claude Code 怎么接？
把 base_url 指向 http://127.0.0.1:8791/v1，api_key 填看板里生成并绑定出口的 Key。Codex 与 Claude Code 走 /v1/responses；Claude 生态客户端也可以直接用 /v1/messages。流式 SSE、reasoning_content 与工具调用都已适配。
API Key 的白名单和日配额怎么配？
设置页「API Key 与出口绑定」里每个 Key 支持 models、daily_requests、daily_tokens。models 大小写不敏感、支持 * 通配、留空不限制；两个配额填 0 表示不限制。超配额 429，模型不匹配 400，都带中文可执行说明。
自动降级默认是开的吗？
不是，默认关闭，需要在设置页显式开启。配置形如 fallback_model / fallback_realm / on_quota / on_upgrade / warn_below。默认关闭是为了不让你以为自己在用 A 模型、实际拿到的是 B。
数据放在哪？会不会被提交到 Git？
accounts/ 存 token、refresh token、面板密码哈希与 API Key；usage/ 存请求流水。两者都不要提交，.gitignore 已排除。Docker 下对应挂载 /app/accounts 与 /app/usage。
生产环境要注意什么？
修改默认面板密码 admin、启用 API Key、限制网络入口。配置导出文件包含密钥，妥善保管。生产环境建议只暴露给内网或加上自己的反向代理与鉴权。