CPA + Codex 配置避坑指南
前言
本文记录了配置 CLI Proxy API (CPA) 与 Codex 集成时遇到的各种坑，希望能帮助后来者少走弯路。
环境信息
-
系统: macOS (Apple Silicon)
-
CPA 版本: v6.9.29
-
Codex 版本: 0.121.0
-
代理工具: ClashX / Clash Verge
核心问题：502 Bad Gateway
症状
Codex 启动后尝试连接 API 时，反复出现：
Unexpected status 502 Bad Gateway: Unknown error, url: http://localhost:8321/v1/responses
根本原因
系统代理拦截了 localhost 请求！
ClashX/Clash Verge 等代理工具默认会拦截所有 HTTP 请求，包括 localhost 和 127.0.0.1。当 Codex 尝试访问本地 CPA 服务时，请求被代理转发，导致：
-
请求无法直接到达本地服务
-
代理返回 502 错误
-
日志中看不到任何请求记录（因为请求根本没到达目标服务）
解决方案
方法 1：设置 NO_PROXY 环境变量（推荐）
# 添加到 ~/.zshrc 或 ~/.bashrc
export NO_PROXY="localhost,127.0.0.1"
# 应用配置
source ~/.zshrc
重要： 必须在新终端中启动 Codex，才能加载新的环境变量。
方法 2：配置代理绕过规则
在 ClashX/Clash Verge 中添加绕过规则，让 localhost 不走代理。
其他常见问题
1. API Key 不匹配 (401 Unauthorized)
症状：
Unexpected status 401 Unauthorized: {"error":"Invalid API key"}
原因：
Codex 使用了自己的 API key（格式如 sk-sub-Pack6n6X...），而不是配置文件中的 api_key。
解决方案：
将 Codex 使用的 key 添加到 CPA 配置中：
# ~/cpa-config.yaml
api-keys:
- "your-custom-key"
- "sk-sub-Pack6n6X_yKXdwEwPB2mT0iGkcQyE4IMMHe-kCN7TIy4L-gf" # Codex 的 key
重启 CPA：
pkill -f "cpa.*config"
~/.local/bin/cpa -config ~/cpa-config.yaml > /tmp/cpa.log 2>&1 &
2. 端口被占用
症状：
Error: listen EADDRINUSE: address already in use 127.0.0.1:8321
原因：
-
旧的 shim 进程还在运行
-
LaunchAgent 自动重启服务
解决方案：
# 查找占用端口的进程
lsof -nP -iTCP:8321 -sTCP:LISTEN
# 停止进程
kill -9 <PID>
# 禁用自动启动
launchctl unload ~/Library/LaunchAgents/com.linkunkun.codex.cliproxy-shim.plist
3. 旧版本冲突
症状：
Homebrew 安装的旧版本 cliproxyapi 自动重启。
解决方案：
# 停止 Homebrew 服务
brew services stop cliproxyapi
# 卸载旧版本
brew uninstall cliproxyapi
# 清理配置
rm -rf /opt/homebrew/etc/cliproxyapi*
rm -f ~/Library/LaunchAgents/homebrew.mxcl.cliproxyapi.plist
4. Shim 是否必需？
答案：不需要！
早期以为需要 shim 来转换请求格式，但实际上：
-
CPA 原生支持
/v1/responses端点 -
直接连接 CPA 更简洁高效
推荐配置：
# ~/.codex/config.toml
[model_providers.custom]
name = "custom"
wire_api = "responses"
base_url = "http://localhost:8317/v1" # 直接连 CPA
api_key = "your-api-key"
完整安装步骤
1. 安装 CPA
# 下载最新版本
curl -L -o /tmp/cpa.tar.gz https://github.com/router-for-me/CLIProxyAPI/releases/download/v6.9.29/CLIProxyAPI_6.9.29_darwin_arm64.tar.gz
# 解压并安装
cd /tmp
tar -xzf cpa.tar.gz
mkdir -p ~/.local/bin
mv cli-proxy-api ~/.local/bin/cpa
chmod +x ~/.local/bin/cpa
# 添加到 PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
2. 配置 CPA
# 复制示例配置
cp /tmp/config.example.yaml ~/cpa-config.yaml
# 编辑配置
vim ~/cpa-config.yaml
关键配置项：
port: 8317
# 管理密钥
remote-management:
secret-key: "your-admin-password"
# API keys
api-keys:
- "your-api-key"
3. 启动 CPA
nohup ~/.local/bin/cpa -config ~/cpa-config.yaml > /tmp/cpa.log 2>&1 &
4. 配置 Codex
# ~/.codex/config.toml
model_provider = "custom"
model = "gpt-5.4"
[model_providers.custom]
name = "custom"
wire_api = "responses"
base_url = "http://localhost:8317/v1"
api_key = "your-api-key"
5. 配置代理绕过（关键！）
# 添加到 ~/.zshrc
echo 'export NO_PROXY="localhost,127.0.0.1"' >> ~/.zshrc
source ~/.zshrc
6. 测试
# 测试 CPA
curl http://localhost:8317/v1/models -H "Authorization: Bearer your-api-key"
# 在新终端启动 Codex
codex
调试技巧
1. 查看 CPA 日志
tail -f /tmp/cpa.log
2. 查看 Codex 日志
tail -f ~/.codex/log/codex-tui.log
3. 检查端口占用
lsof -nP -iTCP:8317 -sTCP:LISTEN
4. 测试 API 连接
curl -v http://localhost:8317/v1/responses \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-5.4","input":[{"role":"user","content":[{"type":"input_text","text":"test"}]}]}'
5. 检查代理设置
# 查看环境变量
env | grep -i proxy
# 查看活动连接
lsof -nP -iTCP | grep codex | grep ESTABLISHED
常见错误排查流程
502 Bad Gateway
↓
检查是否有代理 (lsof -nP -iTCP | grep codex)
↓
有代理 → 设置 NO_PROXY
↓
无代理 → 检查服务是否运行
↓
401 Unauthorized
↓
检查 Codex 使用的 API key (查看日志)
↓
将 key 添加到 CPA 配置
↓
重启 CPA
总结
配置 CPA + Codex 的最大坑就是系统代理。记住：
-
设置 NO_PROXY环境变量 -
在新终端启动 Codex
-
直接连接 CPA，不需要 shim
-
将 Codex 的 API key 添加到 CPA 配置
遵循这些原则，可以避免 90% 的问题。
参考资源
最后更新: 2026-04-18
作者: 基于实际踩坑经历整理
5 个帖子 - 3 位参与者