📋 简介
✅ 前置条件
📦 安装 CLI
📁 配置文件
⚙️ 配置 TOML
🔑 配置 API Key
🔒 安全检查
🧪 连接验证
🚀 启动 Codex
🔧 故障排查
📊 当前状态

🖥️ Mac 版 Codex 客户端配置手册

适配 rongchuan.ai 网关的完整配置指南

macOS Node.js + npm rongchuan.ai

📋 简介

本手册指导你在 macOS 系统上配置 Codex CLI，并将其连接到 rongchuan.ai 网关。

通过本手册，你将学会：

  • 安装 Codex CLI
  • 配置 config.toml 文件
  • 设置 API Key
  • 验证网络连接
  • 排查常见问题
✅ 推荐配置
本手册使用 chat API（更兼容 new-api），不锁死模型版本，确保最大灵活性。

✅ 前置条件

在开始之前，确保你的 Mac 满足以下条件：

1. 操作系统

macOS
支持 zsh（默认） 或 bash（带 conda 也可）

2. Node.js 和 npm

验证安装：

node --version
npm --version

如果未安装，可通过 Homebrew 安装：

brew install node

3. API 网关地址

rongchuan.ai 网关
基础 URL: https://rongchuan.ai/v1

4. API Key

你需要从 rongchuan.ai 获取一个有效的 API Key。确保：

  • Key 已激活
  • Key 具有 chat 和 models 权限
  • Key 未过期

📦 安装 Codex CLI

步骤 1: 全局安装

npm i -g @openai/codex

步骤 2: 验证安装

codex --version

或检查命令路径：

command -v codex
✅ 安装成功
如果上述命令输出版本号和路径，则安装完成。
⚠️ 如果命令不found
• npm 可能需要重新配置 PATH
• 尝试重启终端
• 或使用 npx @openai/codex 直接运行

📁 配置文件位置说明

Codex 默认目录结构

Codex 使用 ~/.codex/ 目录存储配置和数据：

文件/目录 说明 用途
config.toml 主配置文件 设置 API 地址、认证方式、模型等
auth.json 认证信息 存储 API Key
history.jsonl 对话历史 记录所有对话
sessions/ 会话目录 保存会话状态
tmp/ 临时文件 缓存数据
log/ 日志文件 调试和诊断

检查配置文件

ls -la ~/.codex/

⚙️ 配置 config.toml

推荐配置（使用 chat API）

这是最稳定、最兼容的配置方式。

✅ 推荐配置

执行以下命令写入配置文件：

cat > "$HOME/.codex/config.toml" <<'EOF'
model_provider = "aicodewith"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://rongchuan.ai/v1"
wire_api = "chat"
env_key = "OPENAI_API_KEY"
requires_openai_auth = true

[projects."/Users/qmk"]
trust_level = "untrusted"

[projects."/Users/qmk/.codex"]
trust_level = "trusted"
EOF
🎯 关键配置说明
• base_url: rongchuan.ai 网关地址
• wire_api = "chat": 使用稳定的 chat 端点
• env_key = "OPENAI_API_KEY": 从 auth.json 读取
• 未设置 model: 保持模型灵活性

可选配置（使用 responses API）

如果你的后端完全支持 responses 且 SSE 正常，可以使用流式 API：

⚠️ 可选配置

在推荐配置基础上，修改 wire_api：

sed -i '' 's/^wire_api = "chat"/wire_api = "responses"/' "$HOME/.codex/config.toml"
注意事项
• 仅在确认后端支持 /v1/responses 时使用
• SSE 连接不稳定可能导致断流
• 首先建议用推荐配置测试

验证配置文件

cat "$HOME/.codex/config.toml"

🔑 配置 auth.json（API Key）

当前状态检查

检查 auth.json 是否存在以及是否为空：

cat "$HOME/.codex/auth.json"
⚠️ 常见问题
如果看到 { "OPENAI_API_KEY": "" }，说明 Key 为空字符串，需要填入实际 Key。

写入 API Key

将你的 API Key 替换到以下命令中（REPLACE_WITH_YOUR_KEY）：

⚠️ 重要：替换你的 Key

cat > "$HOME/.codex/auth.json" <<'EOF'
{
  "OPENAI_API_KEY": "REPLACE_WITH_YOUR_KEY"
}
EOF
🔒 安全提醒
• 不要在聊天记录中暴露你的 Key
• 如果 Key 已泄露，立即撤销并重置
• auth.json 权限应该是 600（仅所有者可读写）

验证 auth.json 权限

ls -la "$HOME/.codex/auth.json"

应该看到类似：-rw------- ... auth.json（权限 600）

如果权限不对，执行：
chmod 600 "$HOME/.codex/auth.json"

🔒 安全检查

检查 1: 验证 auth.json 中 Key 存在

这个检查不会打印 Key（安全），只检查是否存在和长度：

python3 - <<'PY'
import json, pathlib
p = pathlib.Path.home()/".codex"/"auth.json"
d = json.loads(p.read_text())
k = d.get("OPENAI_API_KEY","")
print("auth.json exists:", p.exists())
print("OPENAI_API_KEY present:", bool(k))
print("OPENAI_API_KEY length:", len(k))
PY
✅ 预期输出
auth.json exists: True
OPENAI_API_KEY present: True
OPENAI_API_KEY length: 50+ (实际长度)

检查 2: 验证 config.toml 配置

grep -nE 'base_url|wire_api|model_provider|preferred_auth_method|model =' "$HOME/.codex/config.toml"
✅ 预期输出（示例）
2:model_provider = "aicodewith"
4:preferred_auth_method = "apikey"
7:base_url = "https://rongchuan.ai/v1"
8:wire_api = "chat"

检查 3: 确保没有硬编码 Key

grep -r "sk-" "$HOME/.codex/config.toml"
✅ 预期输出
无输出（没有找到 Key）

🧪 连接验证

验证 1: 获取模型列表

这个测试会向 API 请求 /v1/models 列表，验证认证是否通过：

KEY="$(python3 -c 'import json, pathlib; print(json.loads((pathlib.Path.home()/".codex"/"auth.json").read_text())["OPENAI_API_KEY"])')"
curl -sS -i "https://rongchuan.ai/v1/models" \
  -H "Authorization: Bearer $KEY" | head -n 20
✅ 成功的响应
HTTP/2 200 (或 HTTP/1.1 200)
Content-Type: application/json
返回模型列表 JSON
❌ 常见错误
• 401 Unauthorized: Key 不对或无权限
• 403 Forbidden: Key 已禁用
• 404 Not Found: API 地址错误

验证 2: 测试 chat.completions（非流式）

这是最稳定的测试方式，不使用流式 API：

KEY="$(python3 -c 'import json, pathlib; print(json.loads((pathlib.Path.home()/".codex"/"auth.json").read_text())["OPENAI_API_KEY"])')"
curl -sS "https://rongchuan.ai/v1/chat/completions" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"gpt-5.2",
    "messages":[{"role":"user","content":"hello"}],
    "stream": false
  }' | head -n 40
✅ 成功的响应
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [...],
  "usage": {...}
}
📝 注意
• 这里使用 gpt-5.2 只是为了测试
• 你可以替换为你平台支持的其他模型
• 可以先用 /models 查询可用模型列表

🚀 启动 Codex

启动命令

codex

使用 Codex

启动后，你可以直接输入问题：

hello
>
type your message and press Enter...
Hello! How can I help you today?

常用命令

命令 说明
exit 或 quit 退出 Codex
help 显示帮助信息
clear 清空对话历史
history 显示对话历史
✅ 启动成功
如果成功连接，你应该能收到 API 的响应。

🔧 故障排查

问题 A: stream disconnected before completion

❌ 错误现象
对话中途断连，显示 "stream disconnected"

原因分析

  • 使用了 responses API（流式），但反代/Nginx/后端提前关闭连接
  • 后端不支持 /v1/responses 端点
  • SSE 配置不完整

解决方案

步骤 1: 改用 chat API

这是最稳定的方式，已在推荐配置中使用：

grep "wire_api" "$HOME/.codex/config.toml"

确保输出是 wire_api = "chat"

步骤 2: 用 curl 测试非流式 API

使用前面"验证 2"中的 curl 命令，确保基础连接正常。

步骤 3: 如果必须用 responses

需要在服务端配置：

  • Nginx: 关闭 buffering，增加 read_timeout
  • 后端: 确保 /v1/responses 完全支持 SSE
  • 测试: 用 curl 流式测试验证

问题 B: 返回 HTML（首页）

❌ 错误现象
收到 HTML 响应，说明打到了网站前端而不是 API

原因和解决

原因： 使用了错误的 API 前缀或路径

解决： 确认 base_url 是 https://rongchuan.ai/v1（不是 /chatgpt/v1）

grep "base_url" "$HOME/.codex/config.toml"

问题 C: 401 Unauthorized

❌ 错误现象
返回 401，说明认证失败

排查步骤

步骤 1: 检查 Key 是否为空

python3 -c "import json, pathlib; d = json.loads((pathlib.Path.home()/'.codex'/'auth.json').read_text()); print('Key is empty' if not d.get('OPENAI_API_KEY') else 'Key present')"

步骤 2: 确认 Key 有效

  • 检查 Key 是否在 rongchuan.ai 后台激活
  • 确认 Key 未过期
  • 检查 Key 是否具有 API 访问权限

步骤 3: 重新填入 Key

如果 Key 已泄露或无效，重置后重新填入：

cat > "$HOME/.codex/auth.json" <<'EOF'
{
  "OPENAI_API_KEY": "your-new-key-here"
}
EOF

问题 D: 查看详细日志

如果上述方法不能解决问题，查看日志文件：

tail -f "$HOME/.codex/log/codex.log"

然后重新运行 codex 命令，观察日志输出。

📊 当前状态评估

✅ 配置文件

config.toml 和 auth.json 已存在

需要确认 Key 是否填入

⚠️ API Key

auth.json 显示 Key 为空字符串

需要填入有效的 API Key

🔄 配置同步

建议统一使用 auth.json 存储 Key

避免混用环境变量和配置文件

推荐后续步骤

  1. 按照"配置 auth.json"部分，填入你的 API Key
  2. 运行"安全检查"部分的三个检查
  3. 执行"连接验证"中的两个 curl 测试
  4. 启动 Codex 并测试基本功能
  5. 如有问题，参考"故障排查"部分

📖 Mac 版 Codex 客户端配置手册 | 适配 rongchuan.ai

📍 配置位置: ~/.codex/

🔗 API 网关: https://rongchuan.ai/v1