Codex 配置教程

本页从安装开始配置 Codex CLI。Codex 桌面应用和 VS Code 扩展也会使用同一套默认 .codex 配置，但请以控制台 API Keys -> 使用密钥 为最终来源：它会按照当前站点、Key、客户端版本和可用模型生成配置，避免手工复制过期字段。

WARNING

使用单独的 API Key 配置 Codex。不要把别人的 auth.json、截图或 Key 导入本机，也不要把自己的配置文件提交进项目仓库。

1. 准备终端与 Node.js

Codex CLI 通过 Node.js 安装。先安装当前受支持的 Node.js LTS，再在终端确认命令可用。

node --version
npm --version

• Windows 可使用 PowerShell、Windows Terminal 或已配置的 WSL；不要求额外安装 Git Bash。
• macOS 可从 Node.js 官方安装包或你的包管理器安装 Node.js。
• Linux / WSL 请使用发行版或 Node.js 官方提供的受支持安装方式。

如果 node 或 npm 不存在、版本过旧或来自多个冲突安装位置，先修复该问题再继续。不要为了绕过权限把全局安装目录改成项目目录。

2. 安装或更新 Codex CLI

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

日后更新可重新执行安装命令。若企业代理、系统策略或包管理器权限阻止安装，请按本机 Node.js 安装方式处理；不要把 API Key 作为 npm 参数或写入 shell 历史。

3. 创建专用 API Key

1. 登录 AIShop 控制台，进入 API Keys。
2. 新建一个名称清晰的 Key，例如 macbook-codex 或 project-a-codex。
3. 为该 Key 选择拥有目标 OpenAI/Codex 模型权限的分组，并确认余额与限制。
4. 在该 Key 的操作中选择 使用密钥 -> Codex CLI，再选择你的操作系统和鉴权模式。
5. 保留控制台生成的 config.toml 与 auth.json 内容；Key 只在受控环境中保存一次。

每台设备或环境应使用不同 Key。泄露、设备遗失或人员变更时，先在控制台撤销对应 Key，再创建新的替代 Key。

4. 找到默认配置目录

环境	配置目录
Windows	%USERPROFILE%\\.codex\\
macOS	~/.codex/
Linux	~/.codex/
WSL	~/.codex/（WSL Linux 用户目录，不是 Windows 目录）

首次配置时目录可能不存在。创建目录前如果已有配置，先备份而不是覆盖未知文件。

# macOS / Linux / WSL
mkdir -p ~/.codex/backup-before-aishop
test -f ~/.codex/config.toml && cp ~/.codex/config.toml ~/.codex/backup-before-aishop/
test -f ~/.codex/auth.json && cp ~/.codex/auth.json ~/.codex/backup-before-aishop/

Windows PowerShell 可先复制 %USERPROFILE%\\.codex\\config.toml 和 auth.json 到一个不在同步盘和 Git 仓库内的备份目录。

5. 写入控制台生成的两个文件

将“使用密钥”窗口生成的内容分别保存为：

~/.codex/config.toml
~/.codex/auth.json

Windows 对应为 %USERPROFILE%\\.codex\\config.toml 和 %USERPROFILE%\\.codex\\auth.json。典型的 config.toml 会使用 Responses 协议，示意结构如下；字段和模型值必须以控制台生成内容为准。

model_provider = "OpenAI"
model = "your-console-model"
review_model = "your-console-model"
model_reasoning_effort = "xhigh"
disable_response_storage = true

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://ai.tavonilo.com"
wire_api = "responses"
requires_openai_auth = true

auth.json 由控制台生成，形状类似：

{
  "OPENAI_API_KEY": "sk-your-own-key"
}

不要把真实 Key 粘贴到 config.toml，不要额外拼成 /v1/v1，也不要把未被当前 Codex 版本支持的 profile 当作默认配置的替代品。需要 WebSocket 配置时，在控制台选择对应选项并完整重启客户端。

6. 启动并验证

完全关闭正在运行的 Codex CLI、桌面应用和 VS Code 中的 Codex 会话，再重新打开一个项目目录。

mkdir -p ~/code/my-codex-project
cd ~/code/my-codex-project
codex

在模型选择器中只选择当前 Key 实际返回的模型。先发送一个不含机密的小请求，例如“只回复 connected”。如果命令行能启动但模型不可选，请先运行下面的 API 检查，确认不是客户端缓存或 Key 分组问题：

curl 'https://ai.tavonilo.com/v1/models' \
  -H "Authorization: Bearer $AI_SHOP_API_KEY"

7. 桌面应用、VS Code 与 WSL

• Codex 桌面应用：使用同一用户目录下的默认 .codex 文件，写入后需完全退出并重新打开应用。
• VS Code：先完成本页的 CLI 配置，再按 Codex VS Code 安装或连接扩展；扩展和终端可能是不同进程，修改文件后都要重启。
• WSL：将配置放到 WSL 的 ~/.codex/，不要假定 Windows 的 %USERPROFILE%\\.codex 会自动同步到 Linux 用户目录。

常见问题与恢复

现象	先检查什么	恢复方式
401 / Unauthorized	auth.json 是否为当前 Key，文件路径是否正确	在控制台重新复制该 Key 的配置，完整重启 Codex。
模型不在选择器	Key 的 /v1/models、分组、订阅和余额	不要猜测模型名；调整 Key 权限后再刷新客户端。
404 或重复路径	base_url 是否来自控制台	恢复控制台生成的根地址，不手工重复添加 /v1。
403 / Forbidden	Key 的分组、模型可见性、余额与订阅	从该 Key 的 /v1/models 重新选择模型，再按控制台权限修复。
429	并发、额度、余额或上游限制	遵循 Retry-After（若有），排队并降低并发，不要并行重放。
请求中断、5xx 或超时	时间、模型、请求 ID、网络/SSE 设置	不要盲目重发长生成；按 错误码与排障 收集脱敏信息。
升级后无法启动	Codex 版本和旧配置字段	先备份旧文件，再重新从“使用密钥”生成版本匹配的配置。

your-console-model 是占位符，不是模型承诺。模型及价格以 模型与价格 和实际 Key 的模型列表为准。