XCodeCLI

Appearance

Codex 配置指南 ​

Codex 是 OpenAI 推出的终端 AI 编码助手。通过 XCodeCLI API 路由器，你可以将其连接到自定义 API 端点，畅享 GPT-5.5、GPT-5.4 等最新模型。

Codex 支持 API 模式（推荐）与 OAuth 登录模式。

快速安装与配置 ​

使用下面的单行命令即可全自动完成 Node.js 环境检查、Codex CLI 安装及 API 模式配置。

bash
API_KEY='你的密钥' bash -c "$(curl -fsSL https://docs.xcodecli.com/scripts/codex/setup-codex.sh)"
powershell
$key='你的密钥'; $f="$env:TEMP\xc.ps1";iwr -useb https://docs.xcodecli.com/scripts/codex/setup-codex.ps1 -OutFile $f;& $f

请将命令中的 你的密钥 替换为你在 XCodeCLI 控制台获取的 API Key。

Windows 执行策略

如果 PowerShell 拦截 .ps1 脚本执行，请先以管理员身份打开 PowerShell，运行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned，出现确认提示时输入 Y 并按 Enter。

⚠️ 配置完成后请重启终端

如果脚本刚安装了 Codex，请重启终端使命令 PATH 生效：

  • macOS / Linux：重新打开终端，或执行 source ~/.zshrc（或 source ~/.bashrc）
  • Windows：重新打开 PowerShell 窗口

API 模式（推荐） ​

API 模式无需 ChatGPT 官方账号，直接使用 XCodeCLI 提供的 API Key 连接。

配置文件位置 ​

  • macOS / Linux：~/.codex/config.toml 与 ~/.codex/auth.json
  • Windows：C:\Users\<用户名>\.codex\config.toml 与 auth.json

1. config.toml ​

toml
# 默认使用的模型提供商
model_provider = "xcodecli"

# 默认模型 (支持 gpt-5.6-sol, gpt-5.5, gpt-5.4 等)
model = "gpt-5.6-sol"

# 思考深度 (low / medium / high / xhigh)
model_reasoning_effort = "high"

# [可选] 高权限模式（初次接触建议保持注释）
# approval_policy = "never"               # 无需每次确认指令
# sandbox_mode = "danger-full-access"     # 全权限沙箱模式

[model_providers.xcodecli]
name = "xcodecli"
base_url = "https://api2.xcodecli.com/v1"
wire_api = "responses"
requires_openai_auth = true

🔑 为什么必须配置 requires_openai_auth = true？

Codex CLI 默认将自定义 Provider 视作免鉴权的本地服务（如本地 Ollama）。必须显式设置 requires_openai_auth = true，Codex 才会自动读取 auth.json 中的密钥并在请求时携带 Authorization: Bearer 认证头，否则会导致 401 Unauthorized 报错。

2. auth.json ​

json
{
  "OPENAI_API_KEY": "sk-your-api-key-here"
}

请将 sk-your-api-key-here 替换为你的实际 API Key。

OAuth 登录模式 ​

如果你希望使用 ChatGPT 账户（支持任意订阅，包含免费账户）登录 Codex CLI 或 Codex App，同时将底层请求路由至 XCodeCLI：

  1. 先在终端运行 codex login 完成官方 ChatGPT 账户登录。
  2. 仅需修改 ~/.codex/config.toml：
toml
model_provider = "xcodecli"
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
supports_websockets = false

[model_providers.xcodecli]
name = "xcodecli"
base_url = "https://api2.xcodecli.com/v1"
wire_api = "responses"
requires_openai_auth = false
experimental_bearer_token = "sk-your-api-key-here" # 这里填入你在 XCodeCLI 的 API Key

OAuth 登录模式下登录凭证由 codex login 自动管理，无需手动编辑 auth.json。

常用参数说明 ​

参数项可选值 / 说明作用
model_provider"xcodecli"指定生效的模型提供商名称
model"gpt-5.6-sol" / "gpt-5.5" / "gpt-5.4" 等指定默认调用的模型
wire_api"responses"API 协议，XCodeCLI 推荐且兼容 OpenAI Responses 协议
requires_openai_authtrue / falseAPI 模式需为 true（读取 auth.json）；OAuth 模式配置 experimental_bearer_token 时设为 false
model_reasoning_effort"low" / "medium" / "high" / "xhigh"模型的推理思考强度
plan_mode_reasoning_effort"high" / "xhigh"规划（Plan）模式下的推理思考强度
supports_websocketsfalse是否开启 WebSocket 流式传输（建议设为 false，使用标准 HTTP SSE 流式）

常见问题与排查 ​

Q1: 运行提示 401 Unauthorized / Authentication Failed？ ​

  • 检查 ~/.codex/config.toml 的 [model_providers.xcodecli] 节点下是否包含 requires_openai_auth = true。
  • 检查 ~/.codex/auth.json 中的 "OPENAI_API_KEY" 格式是否正确，前后无多余空格。

Q2: 提示无法连接到 API 端点？ ​

  • 默认端点为 https://api2.xcodecli.com/v1。
  • 若网络环境受限，可尝试切换为备用端点 https://api.xcodecli.com/v1（直接在 config.toml 中修改 base_url 即可）。

Q3: 分组选择说明 ​

  • Codex 请使用 codex 分组（提供专门的 GPT / Responses 端点支持），不再推荐使用 cc2api 分组。

XCodeCLI API Router

© 2026