Codex 客户端跨平台配置手册

📋 简介

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

选择你的操作系统，然后按照对应的步骤进行配置。

✅ 推荐配置
本手册使用 chat API（更兼容 new-api），不锁死模型版本，确保最大灵活性。

✅ 前置条件

macOS 前置条件

1. 操作系统

macOS 10.15+
支持 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。

Windows 前置条件

1. 操作系统

Windows 10/11
建议使用 PowerShell 或 CMD（Administrator 权限）

2. Node.js 和 npm

验证安装：

node --version
npm --version

如果未安装：

访问 nodejs.org
下载 LTS 版本
运行安装程序（选择"Add to PATH"）
重启 PowerShell/CMD

3. API 网关地址

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

4. API Key

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

Linux 前置条件

1. 操作系统

Ubuntu 18.04+，Debian，CentOS 等
需要 bash/zsh 和 curl

2. Node.js 和 npm

验证安装：

node --version
npm --version

如果未安装，使用包管理器：

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# CentOS/RedHat
sudo yum install nodejs npm

3. API 网关地址

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

4. API Key

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

📦 安装 Codex CLI

macOS 安装步骤

步骤 1: 全局安装

npm i -g @openai/codex

步骤 2: 验证安装

codex --version

或检查命令路径：

command -v codex

✅ 安装成功
如果上述命令输出版本号和路径，则安装完成。

Windows 安装步骤

步骤 1: 以管理员身份打开 PowerShell

按 Win + X，选择 PowerShell (Admin)，或右键 PowerShell 选择"以管理员身份运行"

步骤 2: 全局安装

npm i -g @openai/codex

步骤 3: 验证安装

codex --version

如果看到版本号，则安装成功。

⚠️ 如果报错"不允许执行脚本"
在 PowerShell (Admin) 中执行：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
输入 Y 确认，然后重试安装。

Linux 安装步骤

步骤 1: 全局安装

sudo npm i -g @openai/codex

或者使用用户权限（推荐）：

npm i -g @openai/codex

步骤 2: 验证安装

codex --version
which codex

✅ 安装成功
如果输出版本号和路径，则安装完成。

📁 配置文件位置说明

macOS 配置目录

~/.codex/

完整路径：/Users/YOUR_USERNAME/.codex/

文件/目录	说明
`config.toml`	主配置文件
`auth.json`	认证信息（存储 API Key）
`history.jsonl`	对话历史

检查配置文件

ls -la ~/.codex/

Windows 配置目录

%USERPROFILE%\.codex\

完整路径：C:\Users\YOUR_USERNAME\.codex\

文件/目录	说明
`config.toml`	主配置文件
`auth.json`	认证信息（存储 API Key）
`history.jsonl`	对话历史

检查配置文件

在 PowerShell 中：

dir $PROFILE\..\\.codex\

或者直接在文件浏览器中导航到 C:\Users\YOUR_USERNAME\.codex\

Linux 配置目录

~/.codex/

完整路径：/home/YOUR_USERNAME/.codex/

文件/目录	说明
`config.toml`	主配置文件
`auth.json`	认证信息（存储 API Key）
`history.jsonl`	对话历史

检查配置文件

ls -la ~/.codex/

⚙️ 配置 config.toml

macOS - 推荐配置

✅ 写入配置文件

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

验证配置

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

Windows - 推荐配置

✅ 写入配置文件

在 PowerShell 中执行：

$configPath = "$env:USERPROFILE\.codex\config.toml"
$configContent = @"
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."C:\Users\YOUR_USERNAME"]
trust_level = "untrusted"

[projects."C:\Users\YOUR_USERNAME\.codex"]
trust_level = "trusted"
"@
New-Item -Path "$env:USERPROFILE\.codex" -ItemType Directory -Force | Out-Null
Set-Content -Path $configPath -Value $configContent

⚠️ 注意
将 YOUR_USERNAME 替换为你的实际用户名，或直接用文本编辑器打开并手动编辑 C:\Users\YOUR_USERNAME\.codex\config.toml

验证配置

type "$env:USERPROFILE\.codex\config.toml"

Linux - 推荐配置

✅ 写入配置文件

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."/home/$(whoami)"]
trust_level = "untrusted"

[projects."/home/$(whoami)/.codex"]
trust_level = "trusted"
EOF

验证配置

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

🔑 配置 auth.json（API Key）

macOS - 写入 API Key

⚠️ 重要：替换你的 Key

cat > "$HOME/.codex/auth.json" <<'EOF'
{
  "OPENAI_API_KEY": "REPLACE_WITH_YOUR_KEY"
}
EOF

将 REPLACE_WITH_YOUR_KEY 替换为你的实际 API Key。

设置正确的权限

chmod 600 "$HOME/.codex/auth.json"

验证权限

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

应该显示：-rw------- ... auth.json

Windows - 写入 API Key

⚠️ 重要：替换你的 Key

在 PowerShell 中执行：

$authPath = "$env:USERPROFILE\.codex\auth.json"
$authContent = @{
    OPENAI_API_KEY = "REPLACE_WITH_YOUR_KEY"
} | ConvertTo-Json
New-Item -Path "$env:USERPROFILE\.codex" -ItemType Directory -Force | Out-Null
Set-Content -Path $authPath -Value $authContent

将 REPLACE_WITH_YOUR_KEY 替换为你的实际 API Key。

🔒 安全提醒
Windows 会自动限制该文件的访问权限，只有当前用户可以访问。

验证内容

type "$env:USERPROFILE\.codex\auth.json"

Linux - 写入 API Key

⚠️ 重要：替换你的 Key

cat > "$HOME/.codex/auth.json" <<'EOF'
{
  "OPENAI_API_KEY": "REPLACE_WITH_YOUR_KEY"
}
EOF

将 REPLACE_WITH_YOUR_KEY 替换为你的实际 API Key。

设置正确的权限

chmod 600 "$HOME/.codex/auth.json"

验证权限

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

应该显示：-rw------- ... auth.json

🔒 安全检查

macOS - 安全检查

检查 1: 验证 auth.json 中 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

Windows - 安全检查

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

在 PowerShell 中执行：

$authPath = "$env:USERPROFILE\.codex\auth.json"
if (Test-Path $authPath) {
    $content = Get-Content $authPath | ConvertFrom-Json
    $key = $content.OPENAI_API_KEY
    Write-Host "auth.json exists: True"
    Write-Host "OPENAI_API_KEY present: $($null -ne $key -and $key -ne '')"
    Write-Host "OPENAI_API_KEY length: $($key.Length)"
} else {
    Write-Host "auth.json does not exist"
}

Linux - 安全检查

检查 1: 验证 auth.json 中 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

🧪 连接验证

macOS - 连接验证

验证 1: 获取模型列表

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

验证 2: 测试 chat.completions

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

Windows - 连接验证

验证 1: 获取模型列表

在 PowerShell 中执行：

$authPath = "$env:USERPROFILE\.codex\auth.json"
$auth = Get-Content $authPath | ConvertFrom-Json
$key = $auth.OPENAI_API_KEY

$headers = @{
    "Authorization" = "Bearer $key"
}

$response = Invoke-WebRequest -Uri "https://rongchuan.ai/v1/models" -Headers $headers
$response.Content | ConvertFrom-Json | ConvertTo-Json

验证 2: 测试 chat.completions

$authPath = "$env:USERPROFILE\.codex\auth.json"
$auth = Get-Content $authPath | ConvertFrom-Json
$key = $auth.OPENAI_API_KEY

$headers = @{
    "Authorization" = "Bearer $key"
    "Content-Type" = "application/json"
}

$body = @{
    model = "gpt-5.2"
    messages = @(@{ role = "user"; content = "hello" })
    stream = $false
} | ConvertTo-Json

$response = Invoke-WebRequest -Uri "https://rongchuan.ai/v1/chat/completions" -Headers $headers -Body $body -Method Post
$response.Content | ConvertFrom-Json | ConvertTo-Json

Linux - 连接验证

验证 1: 获取模型列表

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

验证 2: 测试 chat.completions

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

🚀 启动 Codex

macOS - 启动 Codex

启动命令

codex

然后你可以输入问题交互。

Windows - 启动 Codex

启动命令

在 PowerShell 或 CMD 中：

codex

然后你可以输入问题交互。

Linux - 启动 Codex

启动命令

codex

然后你可以输入问题交互。

🔧 故障排查

macOS - 常见问题

问题 1: stream disconnected

解决方案：使用 chat API（已在推荐配置中使用）。

问题 2: 401 Unauthorized

检查 API Key 是否正确填入并有效。

问题 3: codex 命令找不到

重新安装或检查 npm 全局路径：

npm list -g @openai/codex

Windows - 常见问题

问题 1: "不允许执行脚本"

在 PowerShell (Admin) 中执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

问题 2: codex 命令找不到

检查 npm 全局路径：

npm list -g @openai/codex

或重启 PowerShell 重新加载 PATH。

问题 3: 401 Unauthorized

检查 API Key 是否正确填入并有效。

Linux - 常见问题

问题 1: permission denied

使用 sudo 安装：

sudo npm i -g @openai/codex

问题 2: codex 命令找不到

检查 npm 全局路径：

npm list -g @openai/codex
which codex

问题 3: 401 Unauthorized

检查 API Key 是否正确填入并有效。

🖥️ Codex 客户端跨平台配置手册

📋 简介

✅ 前置条件

macOS 前置条件

1. 操作系统

2. Node.js 和 npm

3. API 网关地址

4. API Key

Windows 前置条件

1. 操作系统

2. Node.js 和 npm

3. API 网关地址

4. API Key

Linux 前置条件

1. 操作系统

2. Node.js 和 npm

3. API 网关地址

4. API Key

📦 安装 Codex CLI

macOS 安装步骤

步骤 1: 全局安装

步骤 2: 验证安装

Windows 安装步骤

步骤 1: 以管理员身份打开 PowerShell

步骤 2: 全局安装

步骤 3: 验证安装

Linux 安装步骤

步骤 1: 全局安装

步骤 2: 验证安装

📁 配置文件位置说明

macOS 配置目录

检查配置文件

Windows 配置目录

检查配置文件

Linux 配置目录

检查配置文件

⚙️ 配置 config.toml

macOS - 推荐配置

✅ 写入配置文件

验证配置

Windows - 推荐配置

✅ 写入配置文件

验证配置

Linux - 推荐配置

✅ 写入配置文件

验证配置

🔑 配置 auth.json（API Key）

macOS - 写入 API Key

⚠️ 重要：替换你的 Key

设置正确的权限

验证权限

Windows - 写入 API Key

⚠️ 重要：替换你的 Key

验证内容

Linux - 写入 API Key

⚠️ 重要：替换你的 Key

设置正确的权限

验证权限

🔒 安全检查

macOS - 安全检查

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

Windows - 安全检查

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

Linux - 安全检查

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

🧪 连接验证

macOS - 连接验证

验证 1: 获取模型列表

验证 2: 测试 chat.completions

Windows - 连接验证

验证 1: 获取模型列表

验证 2: 测试 chat.completions

Linux - 连接验证

验证 1: 获取模型列表

验证 2: 测试 chat.completions

🚀 启动 Codex

macOS - 启动 Codex

启动命令

Windows - 启动 Codex

启动命令