使用 X-AIO Coding Helper 配置 Codex

本教程以 macOS、当前 Codex CLI（示例版本 0.149.1）和 X-AIO Coding Helper 当前 0.9.x 主线为例，逐步完成安装、创建并复制 API Key、粘贴密钥、选择模型、核对全局配置和首次请求验证。教程兼容 0.7.x 或更高版本，安装使用 @latest 获取当前主线的最新补丁。在同一操作系统用户环境中，Codex 的 CLI、IDE 扩展和桌面端会共享用户级配置；Windows 桌面端与 WSL 默认使用不同的 CODEX_HOME，例外情况见第 8 节。如果你已经在 Codex 中登录或正在运行会话，请先退出，再执行配置步骤。

1. 准备 Node.js 和 npm

Coding Helper 需要 Node.js 18 或更高版本。使用 npm 安装 Codex 的备用渠道时，建议使用仍在支持期内的 Node.js LTS。先检查本机环境：

node --version
npm --version

如果尚未安装 Node.js，请从 Node.js 官网安装当前 LTS 版本。Codex 的原生安装器本身不依赖 Node.js，但 Coding Helper 仍然需要它。

2. 按官方方式安装或更新 Codex

macOS、Linux 或 WSL

当前官方首选是 standalone 安装器。在终端运行：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

安装完成后，重新打开终端并检查：

codex --version

如果提示 codex: command not found，按安装器最后显示的 Next steps 把安装目录加入 PATH。不要直接把别人的 /opt/homebrew、/usr/local/bin 或 ~/.local/bin 路径复制到自己的配置中。

Windows PowerShell

以普通用户身份打开 PowerShell，运行：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

然后重新打开 PowerShell，运行 codex --version。

macOS Homebrew

如果你已经使用 Homebrew 管理命令行工具，可以使用官方 cask：

brew install --cask codex
codex --version

以后继续用同一渠道更新：

brew upgrade --cask codex

npm 备用方式

如果你的团队已经统一使用 npm，或无法使用 standalone 安装器，可以运行：

npm install -g @openai/codex@latest
codex --version

更新时应继续使用原来的渠道。standalone 用户重新运行官方安装命令：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

npm 用户运行上面的 npm install -g @openai/codex@latest。不要在已用 standalone 或 Homebrew 的机器上点击 Coding Helper 菜单中的 Codex 更新项来强制切换到 npm；本教程只使用官方安装器或原渠道更新。

Homebrew 用户运行 brew upgrade --cask codex。如果不确定当前来源，先运行 command -v codex 和 codex --version，再按原安装渠道更新。

3. 创建 X-AIO API Key，并从列表复制

1. 在 Chrome 中打开 X-AIO API 密钥管理，登录演示账号。
2. 点击 创建新密钥。
3. 在“密钥用途”中填写容易识别的名称，例如 Coding Helper - Codex 教程。
4. 选择有效期，建议选择 90 天，不要为教程或临时测试创建永久密钥。
5. 点击 创建密钥，等待成功提示。
6. 点击提示框中的 OK，返回 API 密钥列表。
7. 在列表中找到 Coding Helper - Codex 教程，确认状态为“有效”，再点击该行的 复制 API 密钥。如需人工核对，可使用该行的 显示 API 密钥，核对后立即再次隐藏。

新建完成的密钥不是只在创建瞬间显示一次。正确流程是“创建 → 关闭成功提示 → 回到密钥列表 → 找到目标行 → 复制 API 密钥”；列表中的遮罩字符串（例如 sk-••••...••••）不是完整密钥，不能直接粘贴到 Helper。

4. 安装 Coding Helper 并粘贴密钥

使用 @latest 安装 Coding Helper 当前 0.9.x 主线。教程最低要求为 0.7.x 或更高版本，不锁定某个精确 patch：

npm install -g @x-all-in-one/coding-helper@latest

使用 npm 的 @latest 标签会安装当前最新稳定版；教程要求它为 0.7.x 或更高版本，不绑定某个固定 patch。安装完成后，只运行不带任何参数的正式命令启动完整交互向导：

xaio-chelper

首次运行时，按顺序完成：

1. 在第一个语言选择界面中选择 [CN] 中文，按回车确认。
2. 向导随后进入 API Key 配置；选择 输入 API Key。
3. 看到 请在这里输入您的 API key, 回车键确认: 后，粘贴刚才从 API 密钥列表目标行复制的完整值，再按回车。
4. 等待 Helper 调用 https://llm-api.x-aio.com/v1/models 验证密钥，确认显示 设置成功。
5. 回到主菜单，确认 API Key 状态显示为 已设置。

如果不是首次运行，启动后会直接进入主菜单。此时选择 配置 API Key → 更新 API Key；只有尚未保存密钥时，该选项才显示为 输入 API Key。后续所有配置都从这个交互向导继续，不使用快捷子命令。

本教程后续每次重新进入 Coding Helper 都只运行 xaio-chelper，再按页面写出的菜单路径操作。

Helper 自身的配置保存在 ~/.xaio-chelper/config.yaml，不要把它提交到仓库。API Key 不会回显到终端。

5. 选择 Codex 模型并立即同步

继续使用刚才打开的交互向导。在主菜单中按顺序操作：

1. 选择 配置编码工具。
2. 在工具列表中选择 Codex。
3. 在 Codex 管理菜单中选择 配置模型 - (选择模型)。
4. 从实时模型列表中选择 gpt-5.6-sol。这是本教程的默认推荐模型。
5. 看到 是否立即将配置应用到 Codex？ 时，直接按回车接受默认的 Yes。
6. 等待 Helper 完成配置装载并返回 Codex 管理菜单。

如果菜单提示 Codex 尚未安装，请选择返回并退出 Helper，按照第 2 节的官方安装方式完成安装，再重新运行 xaio-chelper 进入同一流程；这样不会意外把 standalone 或 Homebrew 安装切换成 npm。

6. 核对同步状态和安全写入

返回 Codex 管理菜单后，应该看到：

Coding Helper 会把公开配置和凭据分开保存：

没有设置 CODEX_HOME 时，它的默认值是 ~/.codex。如果你已经设置了 CODEX_HOME，Helper 会使用该目录，而不是擅自写入另一个 home 目录；目录应先存在并且只属于当前用户。

Helper 会把 X-AIO Provider 写入用户级 $CODEX_HOME/config.toml，让同一用户环境中的 CLI、IDE 扩展和桌面端共享。受信任项目的 .codex/config.toml 仍会参与 Codex 配置优先级，并可能覆盖用户级的 model 或 model_provider；如果某个项目没有使用 X-AIO，请先检查该项目是否存在有意设置的局部覆盖，不要把 API Key 写入项目配置。

为了让文件更新可恢复，0.7.x 或更高版本会先取得同目录锁并严格读取 config.toml、auth.json 和内部状态文件的快照，再以临时文件加原子替换的方式写入凭据和配置。写入前会再次检查快照；任一步失败都会在没有外部改动时恢复快照，检测到并发改动则停止恢复并报告冲突。解析失败的旧配置不会被空对象覆盖。auth.json 和内部状态文件会按密码文件处理，权限为 0600。Helper 同时把 Codex 的凭据存储方式设为 file，确保刚复制的 API Key 不会因为系统只使用 keyring 而被忽略；卸载时会恢复接管前的存储方式和 API Key。

在同一操作系统用户环境中，Codex 的用户级配置会被 CLI、IDE 扩展和桌面端共享。Windows 桌面端与 WSL 默认使用不同的 CODEX_HOME；如果要共享，必须在 WSL 中显式指向 Windows 的 Codex 目录，并确认权限和路径可用。配置前请关闭正在运行的 Codex；不要在当前 Codex 会话自己的 ~/.codex 上做教程演示，也不要通过临时修改 HOME 或 CODEX_HOME 来干扰正在运行的会话。需要演示或排障时，使用独立的测试目录和显式的临时配置路径，完成后删除临时文件。

7. 在空目录中验证一次真实请求

先创建一个新的空目录，避免测试请求接触重要项目：

demo_dir="$(mktemp -d /tmp/xaio-codex-demo.XXXXXX)"
printf '%s\n' "$demo_dir"
if [ -n "$(ls -A "$demo_dir")" ]; then
  ls -la "$demo_dir"
else
  printf '%s\n' '(empty)'
fi

保存当前目录并进入刚创建的临时目录，然后以只读沙箱启动 Codex 交互界面：

original_dir="$PWD"
cd "$demo_dir"
codex --sandbox read-only -m gpt-5.6-sol

如果你上一步选择的不是 gpt-5.6-sol，请把 -m 后的模型 ID 替换成实际选择值。

进入 Codex TUI 后：

1. 输入 /status 并按回车，确认活动模型是刚选择的模型、当前目录是临时目录，沙箱模式是 read-only。
2. 输入 只回复“配置成功”，不要创建、修改或删除任何文件。 并按回车。
3. 收到 配置成功 后，输入 /exit 并按回车退出 Codex。

-m 和 --sandbox 只覆盖这一次启动，不会重写当前 Codex 全局配置；只读沙箱也禁止模型在演示目录中写文件。真实请求会消耗 API 配额；如果返回 402，请前往 Tokens Plan 的订阅总览检查额度，并核对 API Key 有效期和模型可用性，再判断是否为配置问题。

回到 shell 后，检查临时目录仍为空：

if [ -n "$(ls -A .)" ]; then
  ls -la .
else
  printf '%s\n' '(empty)'
fi

如果输出为 (empty)，表示验证目录没有被写入；如果列出了文件，先停止并检查请求参数和沙箱设置。确认完成后可删除该临时目录：

cd "$original_dir"
rmdir "$demo_dir"

8. 常见问题

菜单显示“配置未加载”或“配置不同步”

确认 Codex 管理菜单中的 Provider 是 x-aio，端点是 https://llm-api.x-aio.com/v1，协议是 responses，模型与 Helper 配置一致。升级到 Coding Helper 0.7.x 或更高版本后，重新运行 xaio-chelper，再选择 配置编码工具 → Codex。

选择 Codex 管理菜单当前显示的 配置装载 或 配置刷新（取决于当前状态）。新版本会同时检查 Provider、API Key、模型、端点和 Responses 协议，不会因为只匹配 API Key 和模型而误报同步。

Codex TUI 提示未登录或认证不可用

检查 $CODEX_HOME/auth.json 是否存在、权限是否为 0600，并确认 config.toml 中有：

cli_auth_credentials_store = "file"

如果你手动把凭据存储设置成 keyring，Codex 不会读取 Helper 写入的 auth.json。重新运行 Helper 的 Codex 配置流程，或按官方 Authentication 文档选择一种凭据存储方式。不要把 API Key 写进项目级 .codex/config.toml。

API Key 无效或已过期

• 确认复制的是 API 密钥列表目标行的完整值，而不是遮罩字符串。
• 新建密钥后等待片刻，再运行 xaio-chelper，从主菜单选择 配置 API Key → 更新 API Key 重新粘贴。
• 检查密钥有效期、工作空间和账户余额；必要时删除旧密钥并创建新的 90 天密钥。

模型不存在、请求协议不兼容或返回 400

模型列表会随时间、套餐和上游供应商变化。Coding Helper 会按接口返回的元数据和兼容性规则筛选 Responses 候选；如果预期模型没有出现，它可能只支持 Chat Completions。重新进入 配置模型 获取实时列表，并使用第 7 步的只读请求验证候选模型。不要把只支持 Chat Completions 的模型强行写入 Codex；wire_api = "chat" 不是当前 Codex 自定义 Provider 的有效替代方案。

设置了 CODEX_HOME 后仍找不到配置

确认环境变量指向已经创建的绝对目录，并在同一个终端检查：

printf '%s\n' "$CODEX_HOME"
ls -l "$CODEX_HOME/config.toml" "$CODEX_HOME/auth.json"

CLI、IDE 扩展和 Helper 必须使用同一个 CODEX_HOME。不要为了测试覆盖当前会话的环境变量；请使用单独的临时目录，并在验证后清理。

在 Windows + WSL 场景中，Windows 桌面端默认使用 %USERPROFILE%\.codex，WSL 默认使用 Linux 家目录下的 ~/.codex，两者不会自动共享。需要共享时，在 WSL 中按官方说明设置一个可访问的 Windows 路径，例如：

export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex

确认路径和权限后，再分别重启 Helper、CLI 和桌面端。

9. 官方参考

• Codex CLI 安装与使用
• Codex Authentication
• Config basics
• Advanced config：自定义 Model Provider
• Codex Models