---
title: "通过 TrueFoundry 连接模型服务"
summary: "用户层 [model_providers.truefoundry]，SaaS base_url 是 https://gateway.truefoundry.ai，wire_api = responses。env_key 读 TFY_API_KEY，不要把 Bearer 写进 http_headers。"
category: config
level: intermediate
surfaces: [cli, app, ide]
tags: ["model_providers", "TrueFoundry", "wire_api", "profile"]
canonical: /tips/truefoundry-codex-gateway/
---

# 通过 TrueFoundry 连接模型服务

用户层 [model_providers.truefoundry]，SaaS base_url 是 https://gateway.truefoundry.ai，wire_api = responses。env_key 读 TFY_API_KEY，不要把 Bearer 写进 http_headers。

TrueFoundry 官方 Codex 网关：profile 写 [model_providers.truefoundry]，base_url 用 gateway.truefoundry.ai，密钥用 env_key 不要 http_headers。

这是换 Codex **使用的模型**，流量打到 TrueFoundry AI Gateway，不是添加 MCP 服务。官方 Codex 页给了 `[model_providers.truefoundry]`，但把 `Authorization = "Bearer TFY_API_KEY"` 写进 `http_headers`——那是把密钥写进 TOML。改成 `env_key`（变量**名**），在启动 Codex 的进程里 `export TFY_API_KEY`。不要和 `experimental_bearer_token` / `requires_openai_auth` / `[model_providers.*.auth]` 叠在同一张供应商表。

SaaS 的 `base_url` 就是 `https://gateway.truefoundry.ai`。自建实例从 Playground 的 Code Snippet 抄，写成字面量。**Codex 不会在 `base_url` 里展开环境变量**。不要写 `openai_base_url`，也不要抄 OpenAI SDK 页的 `OPENAI_BASE_URL`。

先在网关建 **Virtual Model**：slug 用 Codex 认识的短名（例如 `gpt-5.2-codex`），目标才是 `openai-main/gpt-5.2-codex` 这种全名。Virtual Model 的类型要勾 `responses`。Codex 里只写 slug；写全名会把 thinking tokens 搞乱。

不要把顶层 `model_provider = "truefoundry"` 一上来写进用户 config，除非你就是要把**所有**会话都改走网关。官方手册示例就是全局默认。更稳妥是独立 profile（用户层 `$CODEX_HOME`，不是项目 `.codex`）。0.134 起不要再写 `[profiles.truefoundry]`。官方还写 `wire_api = "chat"` 给「其他模型」——现行 Codex 会不受支持的配置，只留 `responses`。

```toml
# ~/.codex/config.toml
[model_providers.truefoundry]
name = "TrueFoundry AI Gateway"
base_url = "https://gateway.truefoundry.ai"
env_key = "TFY_API_KEY"
wire_api = "responses"
```

```toml
# ~/.codex/truefoundry.config.toml
model_provider = "truefoundry"
model = "gpt-5.2-codex"
```

```bash
export TFY_API_KEY=YOUR_TFY_API_KEY
codex --profile truefoundry
codex --profile truefoundry -m gpt-5.2-codex
```

本地开发用 Access → Personal Access Tokens 的 PAT；生产、CI、长跑 agent 用 Virtual Account token（VAT）。密钥只显示一次。项目 `.codex/config.toml` 无法修改 `model_provider` / `model_providers`。

走 ChatGPT 订阅而不是用量 API key 时：不要写 `env_key`。网关里 OpenAI 集成的 Base URL 改成 `https://chatgpt.com/backend-api/codex`，API key 留空，让网关转发 Codex 的 OAuth。供应商表加 `requires_openai_auth = true`，网关自己的票用 `env_http_headers = { "x-tfy-api-key" = "TFY_API_KEY" }`，不要把字面量写进 `http_headers`。

官方给的 MCP 搜索是另一张表：`url` 形如 `https://YOUR_GATEWAY/YOUR_TENANT/mcp/YOUR_SERVER/server`，令牌用 `bearer_token_env_var = "TFY_API_KEY"`，不要把 Bearer 写进 `http_headers`。那不是这张模型供应商表。

配置说明：

- 不要再写 `[profiles.truefoundry]` 或 `wire_api = "chat"`。
- 不要把 `openai-main/gpt-5.2-codex` 写进 Codex 的 `model`。
- 不要把密钥写进 `http_headers`。
- 不要抄 `codex chat --model` 当主路径；日常是 `codex --profile truefoundry`。
- 不要覆盖内置 ID `openai`、`ollama`、`lmstudio`。`truefoundry` 是新 ID，可以。
- 不要写进项目 `.codex/config.toml`。
- 不要把这张表当成 MCP。

改完新开会话。`codex --profile truefoundry` 启动后，发送一条简短请求验证连接。401 先看进程里有没有 PAT/VAT；thinking 异常先看 Virtual Model slug 是不是短名、类型有没有 `responses`。

## 来源

- [TrueFoundry · OpenAI Codex CLI](https://www.truefoundry.com/docs/ai-gateway/openai-codex-cli)
- [TrueFoundry · Virtual Model](https://www.truefoundry.com/docs/ai-gateway/virtual-model)
- [TrueFoundry · API Keys](https://www.truefoundry.com/docs/generating-truefoundry-api-keys)