CLI Proxy (Codex API Proxy) Troubleshooting Guide

排查基于 [CLI Proxy API](https://github.com/stainless-codex/cli-proxy-api) 的 Codex OAuth / OpenAI-compatible 代理问题。

使用方式

当遇到以下情况时，先按本文的“快速诊断流程”执行，再按需阅读 references/source-architecture.md：

• API 报 unknown provider for model
• 配置已写但模型列表不对
• 认证文件或 API key 看起来存在，但请求仍失败
• 代理启动正常，但上层客户端无法完成实际调用

架构概述

CLI Proxy 的核心架构：

config.yaml / auth-dir → reloadClients → snapshotCoreAuths
  → refreshAuthState → dispatchAuthUpdates → applyCoreAuthAddOrUpdate
    → registerModelsForAuth → 模型注册表（全局单例）

请求处理链路：

HTTP → ChatCompletions handler → getRequestDetails(modelName)
  → GetProviderName(baseModel) → GetModelProviders(modelName)
    → AuthManager.Execute(providers, req) → Codex executor → ChatGPT

• 模型注册表是全局单例（sync.Once），运行中可热加载
• 认证信息变更会触发模型重新注册
• 配置热重载有 debounce + SHA256 hash 对比

模型注册机制

认证 → 模型映射

不同认证类型注册不同的模型集：

模型列表来源

内嵌模型定义在 internal/registry/models/models.json，编译时打包进二进制。

常见问题与根因

1. "unknown provider for model" 报错

错误消息的细节决定排查方向：

• "unknown provider for model gpt-5.4" → 模型名被正确解析，但 provider（认证）未注册 → 检查认证文件和 API key
• "unknown provider for model"（没有模型名） → 请求体被破坏，模型字段缺失 → 检查请求编码

💡 核心发现： 错误消息中的模型名是否出现，直接指向完全不同的根因。

2. PowerShell + curl 请求体编码问题

PowerShell 会对 -d 参数中的 JSON 做转义处理，导致：

• 引号被转义（" → \" 或丢失）
• 请求体结构被破坏
• model 字段可能丢失

修复方法：

# 用文件方式（推荐）
echo '{"model":"gpt-5.4","messages":[{"role":"user","content":"hi"}]}' > body.json
curl -X POST <proxy-base-url>/v1/chat/completions -d @body.json

# 或用 Python 发请求
python -c "
import requests
r = requests.post('<proxy-base-url>/v1/chat/completions',
    json={'model':'gpt-5.4','messages':[{'role':'user','content':'hi'}]})
print(r.text)
"

3. codex-api-key 不生效 (SanitizeCodexKeys)

CLI Proxy 启动时会调用 SanitizeCodexKeys() 清理配置中的 codex-api-key 条目。

清理规则： 移除**没有 base-url** 的条目。

# ❌ 会被移除
codex_api_keys:
  my-key:
    key: "sk-xxx"

# ✅ 保留
codex_api_keys:
  my-key:
    key: "sk-xxx"
    base-url: "https://chatgpt.com/backend-api/codex"

base-url 必须是 /backend-api/codex 路径，不是纯域名。

4. 认证文件正确加载但模型不出现

**管理 API 返回 None 不代表配置没加载。** auth-dir 字段是 json:"-" 标记的，管理 API 故意不暴露。

排查方法： 直接检查：

1. <auth-dir>/ 目录 — 认证文件是否存在
2. 日志中是否有 applied core auth / registerModelsForAuth 输出
3. 测试 API 调用是否正常返回

5. 请求超时 / 502

CLI Proxy 需要访问 chatgpt.com 后端。如果 ChatGPT 被墙：

• 必须在 config.yaml 中配置 proxy-url: "http://127.0.0.1:PORT"
• 或通过环境变量设置代理
• 代理关闭时请求会直接超时

6. 图片生成报错

图片生成通过 Responses API 转发，使用 tool_choice: {type: "image_generation"} 调用。

常见失败场景：

• Codex Free 账号不支持 → 报 Tool choice 'image_generation' not found
• 需要 Codex Pro 账号

快速诊断流程

当用户报告模型调用异常时：

1. 确认错误消息 — 看是否包含模型名
2. 检查请求体 — 用 Python 或 @body.json 重发验证
3. 检查认证 — 确认 codex-api-key 有 base-url，auth-dir 文件正确
4. 检查网络 — 确认代理配置正确、目标可达
5. 查看日志 — 搜索 registerModelsForAuth、applied core auth、provider_not_found

参考

• 先看本文件：适合快速定位常见根因
• 需要源码级确认时，再看 references/source-architecture.md

该 reference 文件包含关键源码文件、函数链路和模型注册逻辑的完整说明。