通过 Flatkey 使用 Codex 桌面端

Codex 桌面端与 Codex CLI 读取同一份用户级 Codex 配置。你可以将 Flatkey 添加为自定义模型供应商，而无需替换官方 ChatGPT 或 Codex 登录。

前置条件

已安装 Codex 桌面端
已在桌面应用中完成至少一次官方 ChatGPT 或 Codex 登录
Flatkey API 密钥——在 Flatkey 控制台中创建
Flatkey 模型目录中的受支持模型 ID
如果使用 CC Switch 配置，需要先安装 CC Switch

手工配置

1. 设置 API 密钥

将密钥保存在用户环境变量中，不要写入配置文件。

[Environment]::SetEnvironmentVariable(
  "FLATKEY_API_KEY",
  "sk-fk-...",
  "User"
)

launchctl setenv FLATKEY_API_KEY "sk-fk-..."

export FLATKEY_API_KEY="sk-fk-..."

更改环境变量后，请完全退出 Codex 桌面端，再重新打开。

2. 更新 `config.toml`

打开用户级 Codex 配置文件：

平台	配置文件路径
Windows	`%USERPROFILE%\.codex\config.toml`
macOS 和 Linux	`~/.codex/config.toml`

替换顶层的 model 和 model_provider 设置前，请先记录它们当前的值，以便之后恢复。然后更新这两项设置。如果其中任一键已存在，请替换它的值，不要追加重复键。保留所有无关设置。添加下方供应商配置表；如果 [model_providers.flatkey] 已存在，请更新该表，不要重复创建：

model = "gpt-5.4"
model_provider = "flatkey"

[model_providers.flatkey]
name = "Flatkey"
base_url = "https://router.flatkey.ai/v1"
env_key = "FLATKEY_API_KEY"
wire_api = "responses"

本文撰写时，gpt-5.4 已在 Flatkey 模型目录中提供。切换到其他模型 ID 前，请先查阅模型目录。

官方凭据可能保存在 auth.json 或操作系统凭据存储中。配置 Flatkey 时，切勿编辑、替换、覆盖、导出或分享任一凭据存储。不要向其中任何一处粘贴 Flatkey API 密钥。模型和供应商路由由 config.toml 控制。

3. 重启并验证

完全退出 Codex 桌面端，重新打开并发送一条简单提示。打开 Flatkey 用量日志，确认模型、token 数量、延迟和费用。

使用 CC Switch 配置

CC Switch 是第三方配置管理器，不是 Flatkey 产品。你也可以从 CC Switch GitHub 仓库下载。以下步骤以当前 CC Switch 界面为准。手工配置和 CC Switch 是两种可替代的配置方式。请只用其中一种方式控制当前供应商。Codex 桌面端和 Codex CLI 共用 macOS 与 Linux 上的 ~/.codex/config.toml，或 Windows 上的 %USERPROFILE%\.codex\config.toml。CC Switch 会控制这份共享文件中的模型和供应商设置。请保留无关设置和供应商。

1. 完成一次官方登录

切换供应商前，请打开 Codex 桌面端并完成一次官方 ChatGPT 或 Codex 登录。桌面应用需要这次有效的官方会话来访问账户和模型目录。官方凭据保存在 auth.json 或操作系统凭据存储中。两者都属于敏感信息。

2. 保留官方登录以便直接切换

在 CC Switch 中打开设置 > 通用 > Codex 应用增强，然后启用非接管切换时保留官方登录。启用后，直接切换供应商时不会丢弃 Codex 桌面端仍需使用的官方登录。

切勿为了复制内容而打开 auth.json，也不要替换、覆盖、分享该文件，或向其中粘贴 Flatkey API 密钥。不要在截图或 CC Switch 供应商导出文件中暴露 Flatkey API 密钥。如果任一凭据已经暴露，请立即轮换或撤销。

3. 将 Flatkey 添加为自定义供应商

打开 CC Switch 的 Codex 面板并添加自定义供应商。请使用下表中的值。本教程不依赖内置的 Flatkey 供应商条目。

供应商字段	值
供应商名称	`flatkey`
API 密钥	`sk-fk-...`
API 请求地址	`https://router.flatkey.ai/v1`
默认模型	截图中使用 `gpt-5.6-sol`——请在 Flatkey 模型目录中确认当前准确的模型 ID
上游格式	Responses（原生）

4. 配置模型

将供应商的默认模型设置为你要使用的准确 Flatkey 模型 ID。截图中的示例是 gpt-5.6-sol。选择 ID 前，请先查看 Flatkey 模型目录。点击获取模型列表加载当前模型 ID。要让模型出现在 Codex /model 菜单中，请将其添加到供应商的模型映射。你也可以将准确 ID 设置为供应商的默认模型，或在 Codex CLI 中通过 codex --model <id> 传入该 ID。验证 Codex 桌面端时，即使选择器没有列出自定义模型，也应将当前供应商和默认模型视为预期路由。发送请求后，请通过 Flatkey 用量日志确认实际路由。

Flatkey 原生支持 Responses API。请关闭本地路由；此配置不需要它。

5. 保存、启用并重启

保存自定义供应商，并为 Codex 启用它。不要从共享的 config.toml 中删除无关设置或供应商。

完全退出 Codex 桌面端。确认没有旧的 Codex 桌面端进程残留，再重新打开应用，让它读取新的供应商设置。

6. 验证实际路由

新建一个上下文较小的对话，并发送一条最简提示。然后打开 Flatkey 用量日志，确认该请求的模型、token 数量、延迟和费用。

保留官方登录并不代表请求会由 OpenAI 计费。共享 config.toml 中的当前供应商和模型设置决定实际路由。Flatkey 用量日志是请求已到达 Flatkey 的权威验证依据。系统提示、工具、对话历史、附件和命令输出都可能增加输入 token，因此输入量可能高于可见提示文本。更高的输入 token 数量可能增加费用。

如果模型不可见

Codex 桌面端可能显示官方模型目录，而不在选择器中显示自定义模型。界面中缺少自定义模型并不能证明路由失败。

确认官方 ChatGPT 或 Codex 登录仍然有效。
确认已启用设置 > 通用 > Codex 应用增强 > 非接管切换时保留官方登录。
确认 Flatkey 供应商已启用，而且其默认模型使用准确的模型 ID。
检查供应商的模型映射。如果你希望模型出现在 /model 菜单中，请使用获取模型列表。
确认共享 config.toml 中是预期的当前供应商和模型，不要更改无关设置。
完全退出所有 Codex 桌面端进程，再重新打开应用。
发送一条最简提示，并在 Flatkey 用量日志中确认实际路由。

切回官方供应商

如果你使用 CC Switch，请启用官方 Codex 供应商。完全退出 Codex 桌面端，确认没有旧进程残留，再重新打开。无需删除 Flatkey 自定义供应商。如果你使用手工配置，请在 config.toml 中恢复之前的顶层 model 和 model_provider 值。保留无关设置和供应商表。不要改动 auth.json 或操作系统凭据存储中的官方凭据。完全退出 Codex 桌面端，确认没有旧进程残留，再重新打开。

CC Switch 故障排查

问题	检查项
官方登录缺失或已过期	通过 Codex 桌面端重新登录，然后在启用 Flatkey 前打开非接管切换时保留官方登录
身份验证失败或 Flatkey 密钥被拒绝	确认 API 密钥仍有效，并已填入自定义供应商的 API 密钥字段；如果密钥已经暴露，请轮换或撤销
API 请求地址或 Responses 报错	将API 请求地址设置为 `https://router.flatkey.ai/v1`，选择 Responses（原生），并关闭本地路由
出现 `Model not found`、自定义模型不可见或缺少 `/model` 映射	从模型目录复制准确 ID，将其设为默认模型，并使用获取模型列表或模型映射
用量日志显示错误的供应商或模型	启用 Flatkey 自定义供应商，并确认其默认模型以及共享 `config.toml` 中的当前值
更改未生效	完全退出 Codex 桌面端，结束所有残留的 Codex 桌面端进程，然后重新打开
Flatkey 余额不足	充值或改用有可用额度的 Flatkey 密钥，然后重试一条最简提示
误开本地路由	关闭本地路由，因为 Flatkey 可以接收原生 Responses 请求
用量日志中没有请求	新建上下文较小的对话并发送一条最简提示，然后重新检查当前供应商、API 请求地址和用量日志
切换后官方登录消失	通过 Codex 桌面端重新登录并启用登录保留设置；切勿替换或覆盖 `auth.json`

快速入门

代码接入

主流 AI 工具

媒体生成

热门模型

控制台

参考

通过 Flatkey 使用 Codex 桌面端

前置条件

手工配置

1. 设置 API 密钥

2. 更新 `config.toml`

3. 重启并验证

使用 CC Switch 配置

1. 完成一次官方登录

2. 保留官方登录以便直接切换

3. 将 Flatkey 添加为自定义供应商

4. 配置模型

5. 保存、启用并重启

6. 验证实际路由

如果模型不可见

切回官方供应商

CC Switch 故障排查

​前置条件

​手工配置

​1. 设置 API 密钥

​2. 更新 config.toml

​3. 重启并验证

​使用 CC Switch 配置

​1. 完成一次官方登录

​2. 保留官方登录以便直接切换

​3. 将 Flatkey 添加为自定义供应商

​4. 配置模型

​5. 保存、启用并重启

​6. 验证实际路由

​如果模型不可见

​切回官方供应商

​CC Switch 故障排查

前置条件

手工配置

1. 设置 API 密钥

2. 更新 `config.toml`

3. 重启并验证

使用 CC Switch 配置

1. 完成一次官方登录

2. 保留官方登录以便直接切换

3. 将 Flatkey 添加为自定义供应商

4. 配置模型

5. 保存、启用并重启

6. 验证实际路由

如果模型不可见

切回官方供应商

CC Switch 故障排查