给 Codex Desktop 订阅用户的 Headroom 安装、持久路由、验证与回退清单。Dashboard 能打开，只是排查的起点。

本文针对使用 ChatGPT 订阅登录的 Codex Desktop。结论不是“装好 Headroom 就会自动生效”，而是还要确认代理进程、Codex 实际配置目录、内置 OpenAI provider 的 base URL，以及真实的 /v1/responses 流量。

验证环境

版本会持续更新，文中的配置原则和检查方法比具体版本号更重要。

1. 安装后先检查两件事

Headroom Installation 要求 Python 3.10 或更高版本，并按功能提供不同 extras。需要代理、Dashboard 和完整能力时，可以在独立虚拟环境中安装 headroom-ai[all]：

py -3.12 -m venv headroom-venv
.\headroom-venv\Scripts\python.exe -m pip install "headroom-ai[all]"
.\headroom-venv\Scripts\python.exe -m headroom.cli --version

安装后，确认 headroom proxy 在 Codex 启动前已经运行。Codex 不负责管理 Headroom 的生命周期；想持久使用，需要配置启动项、计划任务或系统服务。

安全软件若拦截创建启动项，应只放行经过核对的 Headroom 启动脚本，不要关闭整套安全防护。

按需使用上游代理

如果 Headroom 访问上游 API 也需要走本机代理，可以设置：

$env:HEADROOM_HTTP_PROXY = "http://127.0.0.1:10808"
$env:HTTP_PROXY  = "http://127.0.0.1:10808"
$env:HTTPS_PROXY = "http://127.0.0.1:10808"
$env:ALL_PROXY   = "http://127.0.0.1:10808"

headroom proxy --host 127.0.0.1 --port 8787 --no-telemetry

10808 不是 Headroom 的必需端口。它只用于 Headroom 访问上游 API 时复用本机代理；网络能直连时应省略这些环境变量。

2. 找到 Codex 真正读取的配置

先在 PowerShell 查看 CODEX_HOME：

Write-Host $env:CODEX_HOME

如果它有值，Codex 实际读取的是：

$env:CODEX_HOME\config.toml

而不一定是：

%USERPROFILE%\.codex\config.toml

可以直接检查实际配置：

Get-Content "$env:CODEX_HOME\config.toml"

移动过 Codex 数据目录的用户必须检查这一点。同一台机器可能存在两份语法都正确的 config.toml，但只有 Codex 当前读取的那一份会生效。

Headroom 0.31.0 的 wrap codex 已会读取 CODEX_HOME，但部分安装或审计路径仍可能从默认的 ~/.codex 开始查找。因此，执行自动配置后仍要核对最终被修改的文件。

3. 订阅用户的最小路由配置

Headroom Quickstart 给通用 OpenAI 兼容客户端的入口是 http://localhost:8787/v1。

在 Codex Desktop 的 ChatGPT 订阅模式中，本次验证最稳定的做法是保留内置 openai provider，只在实际使用的 config.toml 顶层加入：

openai_base_url = "http://127.0.0.1:8787/v1"

# 其他 [section] 放在顶层键之后

openai_base_url 必须是 TOML 顶层键，不能误放进前一个 [section]。Headroom 当前源码也注明：ChatGPT 订阅认证会走 Codex 内置的 openai provider，这个 base URL 才是订阅流量的关键入口。

历史记录兼容注意事项

在本文验证的 Codex Desktop 版本中，不要额外设置：

model_provider = "headroom"

也不要创建：

[model_providers.headroom]

自定义 provider 可能使旧会话在重启后被历史列表过滤。数据通常没有删除，但用户会看到项目或聊天记录消失。

这是本次环境的兼容性实测结论，不代表所有 Codex 版本都必然表现相同。更新 Codex 或 Headroom 后应重新验证。

4. Headroom MCP 是可选项

Headroom MCP 是增强能力，不是代理路由成立的必要条件。需要 MCP 工具时，应使用 Python 虚拟环境的绝对路径，避免 Codex 启动时找不到解释器：

[mcp_servers.headroom]
command = "C:\\absolute\\path\\headroom-venv\\Scripts\\python.exe"
args = ["-m", "headroom.cli", "mcp", "serve"]

是否配置 MCP，不影响 openai_base_url 将模型请求发送到 Headroom 代理。

5. 不看“能打开”，看请求是否增长

Headroom Proxy 文档 提供 /health、/stats 等端点。

先读取一次统计，在 Codex 中发送一条新消息，再重新读取：

Invoke-RestMethod http://127.0.0.1:8787/health
Invoke-RestMethod http://127.0.0.1:8787/stats

应同时确认：

• /health 返回 status: healthy 和 ready: true。
• summary.api_requests 在发送消息后增加。
• proxy_inbound.by_path["/v1/responses"] 增加。
• Recent Requests 出现当前时间和当前 Codex 模型。
• 订阅兼容配置下，Recent Requests 中的 provider 仍为 openai。

Dashboard 可访问只说明本地 HTTP 页面正常；健康检查只说明 Headroom 进程存活。只有新的模型请求、时间戳和计数一起变化，才能证明 Codex 正在使用 Headroom。

6. 重启后历史消失时怎么判断

如果 Codex 重启后项目还在，但任务或聊天记录为空，先恢复原配置，再检查是否引入了自定义 model_provider。

本次故障中，会话 JSONL 和 SQLite 数据都还存在，Codex Desktop 只是按 provider 重新索引和过滤。只修改 SQLite 标签并不稳定，因为下次启动可能再次从 JSONL 重建。

推荐处理顺序：

1. 退出 Codex。
2. 备份有效的 config.toml、session_index.jsonl 和 state_5.sqlite。
3. 移除自定义 model_provider 与 [model_providers.headroom]。
4. 保留顶层 openai_base_url，让会话继续归属内置 openai。
5. 重启 Codex，确认历史记录恢复。
6. 在 Codex 中发送新消息，确认 Headroom 请求统计同时增长。

不要在没有备份的情况下批量修改会话 JSONL 或 SQLite 数据库。

7. 持久使用时还要检查什么

安装最新版 Codex 和 Headroom 后，还需要逐项确认：

• Headroom 代理确实监听 127.0.0.1:8787。
• Headroom 在 Codex 启动前运行。
• 开机启动脚本或计划任务没有被安全软件拦截。
• 需要代理时，Headroom 的上游流量正确使用 127.0.0.1:10808。
• 修改的是实际 CODEX_HOME 下的 config.toml。
• openai_base_url 位于 TOML 顶层。
• ChatGPT 订阅会话继续使用内置 openai provider。
• Codex 重启后项目和聊天记录仍正常显示。
• /v1/responses 和 API 请求计数会随新消息增长。

8. 临时停用和恢复

临时停用不需要卸载 Headroom。

手动方式：

1. 删除或注释 config.toml 顶层的 openai_base_url。
2. 退出并重新启动 Codex。
3. 停止监听 8787 端口的 Headroom 进程。

恢复时重新添加：

openai_base_url = "http://127.0.0.1:8787/v1"

然后先启动 Headroom，再启动 Codex。

本文测试环境还提供了本地切换脚本：

powershell -ExecutionPolicy Bypass -File .\outputs\toggle-headroom-codex.ps1 -Action status
powershell -ExecutionPolicy Bypass -File .\outputs\toggle-headroom-codex.ps1 -Action disable
powershell -ExecutionPolicy Bypass -File .\outputs\toggle-headroom-codex.ps1 -Action enable

这些脚本路径属于本文测试环境。分享给其他人时，需要根据对方实际存放位置调整路径。

最终检查清单

• Python 和 Headroom 版本正确。
• Headroom 代理健康并先于 Codex 启动。
• 上游代理按需使用 10808。
• 已确认实际 CODEX_HOME。
• 顶层 openai_base_url 指向 http://127.0.0.1:8787/v1。
• 未因自定义 provider 导致订阅会话历史被过滤。
• Codex 重启后历史记录正常。
• /v1/responses 和 summary.api_requests 随新消息增长。
• 已准备可恢复的配置与会话索引备份。

资料来源

• Headroom 官方文档：Installation
• Headroom 官方文档：Quickstart
• Headroom 官方文档：Proxy Server
• OpenAI 官方文档：Codex Configuration Reference
• Headroom 源码：Codex 订阅模式路由说明
• Headroom issue #961：Codex 会话 provider 迁移