# Headroom × Codex：一次本地代理接入的排错笔记

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

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

## 验证环境

| 项目 | 版本或状态 |
| — | — |
| 验证日期 | 2026-07-10 |
| Headroom | 0.31.0 |
| Codex Desktop | 26.707.3748.0 |
| 登录方式 | ChatGPT 订阅账号 |
| 操作系统 | Windows |

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

## 1. 安装后先检查两件事

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

“`powershell
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 也需要走本机代理，可以设置：

“`powershell
$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`：

“`powershell
Write-Host $env:CODEX_HOME
“`

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

“`text
$env:CODEX_HOME\config.toml
“`

而不一定是：

“`text
%USERPROFILE%\.codex\config.toml
“`

可以直接检查实际配置：

“`powershell
Get-Content “$env:CODEX_HOME\config.toml”
“`

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

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

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

[Headroom Quickstart](https://headroom-docs.vercel.app/docs/quickstart) 给通用 OpenAI 兼容客户端的入口是 `http://localhost:8787/v1`。

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

“`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 版本中，不要额外设置：

“`toml
model_provider = “headroom”
“`

也不要创建：

“`toml
[model_providers.headroom]
“`

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

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

## 4. Headroom MCP 是可选项

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

“`toml
[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 文档](https://headroom-docs.vercel.app/docs/proxy) 提供 `/health`、`/stats` 等端点。

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

“`powershell
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 进程。

恢复时重新添加：

“`toml
openai_base_url = “http://127.0.0.1:8787/v1”
“`

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

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

“`powershell
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](https://headroom-docs.vercel.app/docs/installation)
– [Headroom 官方文档：Quickstart](https://headroom-docs.vercel.app/docs/quickstart)
– [Headroom 官方文档：Proxy Server](https://headroom-docs.vercel.app/docs/proxy)
– [OpenAI 官方文档：Codex Configuration Reference](https://developers.openai.com/codex/config-reference/)
– [Headroom 源码：Codex 订阅模式路由说明](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/cli/wrap.py#L1854-L1862)
– [Headroom issue #961：Codex 会话 provider 迁移](https://github.com/headroomlabs-ai/headroom/issues/961)