CLIProxyAPI / CPA 添加 codex-header-defaults.user-agent 修复方案总结

1. 问题现象

在使用 CLIProxyAPI / CPA 调用 Codex 后端时，原本应该返回 API JSON 数据，但实际返回了 Cloudflare 验证页面 HTML，典型内容包括：

Enable JavaScript and cookies to continue

这说明请求没有正常进入 Codex 后端，而是在访问 chatgpt.com/backend-api/codex/responses 时被 Cloudflare Challenge 拦截。

---

2. 已确认可行的解决方案

在 CLIProxyAPI/config.yaml 中添加或修改以下配置：

codex-header-defaults:
  user-agent: "codex-tui/0.118.0 (Mac OS 26.3.1; arm64) iTerm.app/3.6.9 (codex-tui; 0.118.0)"

修改后需要：

1. 保存 config.yaml；
2. 重启 CLIProxyAPI / CPA；
3. 再次测试 /v1/chat/completions 或相关 Codex 请求；
4. 如果不再返回 Cloudflare HTML 验证页，而是正常返回模型响应，说明配置生效。

你这边已经确认：该方案可行。

---

3. 为什么添加 user-agent 会有效

3.1 User-Agent 是客户端身份标识

User-Agent 是 HTTP 请求头，用来告诉服务器：当前请求来自什么客户端、什么系统、什么版本。也就是说，它是请求指纹的一部分。

原理上，服务器或中间风控系统可以通过 User-Agent 判断请求像不像正常客户端。

---

3.2 CLIProxyAPI 支持给 Codex 请求设置默认请求头

CLIProxyAPI 的配置示例中包含类似：

codex-header-defaults:
  user-agent: "..."

这说明 CLIProxyAPI 本身支持为 Codex 请求设置默认 header。也就是说，把 user-agent 写到 codex-header-defaults 下，是符合这个工具配置逻辑的。

---

3.3 原来的请求可能不像官方 Codex 客户端

如果 CLIProxyAPI 默认发出的请求头比较普通，例如接近：

User-Agent: Go-http-client/1.1

或者没有带上接近 Codex 客户端的身份信息，那么上游可能更容易把它识别为脚本请求、代理请求或异常自动化流量。

而添加下面这个 UA 后：

User-Agent: codex-tui/0.118.0 (Mac OS 26.3.1; arm64) iTerm.app/3.6.9 (codex-tui; 0.118.0)

请求看起来更接近一个真实的 Codex TUI 客户端环境，因此 Cloudflare / 上游服务更可能把它当作正常 Codex 客户端请求处理。

---

3.4 Cloudflare Challenge 不只看账号 token，也看请求特征

之前返回的是 Cloudflare Challenge 页面，而不是普通的账号认证错误。这说明问题重点不一定是 token 本身错误，而可能是请求在到达后端前，被 Cloudflare 根据请求特征拦截。

Cloudflare 的 Challenge / Managed Challenge 会根据请求特征、浏览器信号、会话状态等因素动态判断是否展示挑战页。因此，修改 User-Agent 可以改变请求特征，降低被误判的概率。

---

4. 这个方案的本质

这个方案的本质不是“修复模型”，也不是“修复账号”，而是：

让 CLIProxyAPI 发出的 Codex 请求携带更接近官方 Codex TUI 的客户端标识。

因此，它解决的是：

CLIProxyAPI 请求特征不像正常 Codex 客户端
        ↓
Cloudflare / 上游风控返回验证页
        ↓
API 客户端收到 HTML，而不是 JSON

添加 user-agent 后变成：

CLIProxyAPI 请求带有 codex-tui 风格 UA
        ↓
请求特征更接近正常 Codex 客户端
        ↓
后端更可能正常返回 Codex 响应

---

5. 需要注意的地方

5.1 YAML 缩进必须正确

推荐写法：

codex-header-defaults:
  user-agent: "codex-tui/0.118.0 (Mac OS 26.3.1; arm64) iTerm.app/3.6.9 (codex-tui; 0.118.0)"

不要写成：

codex-header-defaults:
user-agent: "..."

也不要混用 Tab 缩进。

---

5.2 修改配置后必须重启 CLIProxyAPI

只保存 config.yaml 通常不够，需要重启服务，否则新 header 可能不会被加载。

---

5.3 该方法不是万能方案

虽然你已经确认这个方案可行，但它仍然依赖当前网络环境、账号状态、CLIProxyAPI 版本和上游策略。

如果后续再次失败，可能原因包括：

• VPN / 代理节点 IP 风险较高；
• 账号 token 过期或异常；
• CLIProxyAPI 没有加载到正确的 config.yaml；
• YAML 缩进或字段名写错；
• 上游对 Codex 客户端请求头要求发生变化；
• CLIProxyAPI 版本过旧。

---

6. 验证是否成功

可以通过以下现象判断是否成功：

成功表现

• 不再返回完整 HTML 页面；
• 不再出现 Enable JavaScript and cookies to continue；
• /v1/chat/completions 可以正常返回模型结果；
• CLIProxyAPI 日志中请求状态正常。

失败表现

如果仍然看到类似内容：

Enable JavaScript and cookies to continue

或者返回大量 Cloudflare HTML / JS 代码，说明请求仍然被 Challenge 拦截。

---

7. 推荐排查顺序

如果添加后仍然不行，建议按这个顺序排查：

1. 检查 config.yaml 路径是否正确；
2. 检查 codex-header-defaults 缩进是否正确；
3. 重启 CLIProxyAPI / CPA；
4. 查看日志，确认请求是否带上新的 User-Agent；
5. 换更干净稳定的 VPN / 代理节点；
6. 重新生成自己的账号 JSON / token；
7. 更新 CLIProxyAPI / CPA 到新版。

---

8. 最终结论

目前这个问题的可行解决方案是：

codex-header-defaults:
  user-agent: "codex-tui/0.118.0 (Mac OS 26.3.1; arm64) iTerm.app/3.6.9 (codex-tui; 0.118.0)"

该配置的作用是：

让 CLIProxyAPI 的 Codex 请求带上更接近官方 Codex TUI 的客户端身份信息，从而避免请求被 Cloudflare / 上游风控误判为异常脚本请求。

你已经确认该方案有效，因此后续可以把它作为当前环境下的固定修复项保留在 CLIProxyAPI/config.yaml 中。

---

参考资料

1. MDN Web Docs: User-Agent header
   https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/User-Agent

2. Cloudflare Docs: Challenges
   https://developers.cloudflare.com/cloudflare-challenges/

3. Cloudflare Docs: Challenge Pages / Managed Challenges
   https://developers.cloudflare.com/cloudflare-challenges/challenge-types/challenge-pages/

4. CLIProxyAPI config.example.yaml
   https://github.com/router-for-me/CLIProxyAPI/blob/main/config.example.yaml

5. OpenAI Codex CLI documentation
   https://developers.openai.com/codex/cli