Codex CLI

Codex CLI 是 OpenAI 的终端编码代理，适合在本地仓库中阅读代码、生成补丁、运行命令并推进多步骤开发任务。新手选择很简单：Windows 用 WSL2 跑 CLI，macOS 和 Linux 直接用系统终端；如果你想要图形界面，先回到 Codex 选择桌面端。

建议先用独立项目或低风险仓库验证 AIDMX Provider，再把配置迁移到日常工作环境。

下载和官方入口

入口	用途
Codex CLI 官方文档	查看当前安装、登录、沙箱和配置说明。
OpenAI Codex GitHub	查看源码、README、问题追踪和开发动态。
GitHub Releases	下载指定版本或排查版本回退问题。
npm: @openai/codex	使用 Node/npm 全局安装。
Homebrew codex cask	macOS 或已配置 Homebrew 的 Linux 用户参考 Homebrew 安装。

常用安装命令：

npm install -g @openai/codex

验证版本：

node --version
npm --version
codex --version

检查 npm 全局可执行目录是否在 PATH：

npm config get prefix
which codex
echo "$PATH"

Windows PowerShell：

node --version
npm --version
codex --version
npm config get prefix
Get-Command codex
$env:Path

如果 codex 找不到，重新打开终端；仍失败时，把 npm 或 Homebrew 提示的 bin 目录加入当前用户 PATH。

配置 AIDMX

1. 创建 Codex 配置目录

macOS / Linux / WSL：

mkdir -p ~/.codex

Windows 原生 PowerShell：

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex"

2. 写入 config.toml

编辑 ~/.codex/config.toml：

model = "控制台可用模型"
model_provider = "aidmx"
model_reasoning_effort = "medium"
disable_response_storage = true

[model_providers.aidmx]
name = "AIDMX"
base_url = "https://ai.aidmx.xyz/v1"
wire_api = "responses"
requires_openai_auth = true

如果当前 Codex CLI 版本提示不认识 requires_openai_auth，删除这一行后重试。如果模型或网关暂不支持 Responses API，把 wire_api 改为 chat 后再验证。

3. 写入 auth.json

把 你的 AIDMX API Token 替换成 令牌管理 中创建的 Token。

{
  "OPENAI_API_KEY": "你的 AIDMX API Token"
}

也可以使用登录命令写入密钥：

printf '%s' "$AIDMX_API_KEY" | codex login --with-api-key

4. 做一次非交互验证

codex exec --skip-git-repo-check "用一句话说明当前环境是否可用，不要修改文件"

Windows (WSL) 端图文流程

1. 安装 NVM for Windows

winget install Schniz.fnm

fnm install --lts
fnm use lts-latest
node --version
npm --version

2. 验证 Node.js

node --version
npm --version

3. 安装 Codex CLI

在 WSL 中执行：

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

4. 修改配置文件

在 WSL 中创建并编辑配置：

mkdir -p ~/.codex
nano ~/.codex/config.toml

写入 AIDMX Provider：

model = "控制台可用模型"
model_provider = "aidmx"
model_reasoning_effort = "medium"
disable_response_storage = true

[model_providers.aidmx]
name = "AIDMX"
base_url = "https://ai.aidmx.xyz/v1"
wire_api = "responses"
requires_openai_auth = true

再写入 Token：

nano ~/.codex/auth.json

{
  "OPENAI_API_KEY": "你的 AIDMX API Token"
}

5. 开始使用 Codex CLI

进入项目目录后启动：

cd /mnt/c/path/to/your/project
codex

首次运行时按提示确认工作区和权限模式。

Codex 会询问是否允许自动修改文件。低风险验证阶段建议选择更保守的授权模式。

需要切换模型时输入：

/model

发送一条只读测试任务：

请用一句话说明当前项目是什么，不要修改文件。

macOS 端图文流程

1. 安装 Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. 安装 Node.js

brew install node
node --version
npm --version

3. 安装 Codex CLI

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

如果遇到 npm 全局权限问题，优先配置 npm 用户目录；临时验证时也可以使用 sudo npm install -g @openai/codex。

4. 修改配置文件

创建配置目录：

mkdir -p ~/.codex

编辑 ~/.codex/config.toml：

model = "控制台可用模型"
model_provider = "aidmx"
model_reasoning_effort = "medium"
disable_response_storage = true

[model_providers.aidmx]
name = "AIDMX"
base_url = "https://ai.aidmx.xyz/v1"
wire_api = "responses"
requires_openai_auth = true

编辑 ~/.codex/auth.json：

{
  "OPENAI_API_KEY": "你的 AIDMX API Token"
}

5. 开始使用 Codex CLI

进入项目目录：

cd /path/to/your/project
codex

首次运行时确认工作区。

选择合适的权限模式。

使用 /model 检查模型选择：

/model

完成一次只读测试：

请总结当前目录，不要修改任何文件。

Linux 端图文流程

1. 安装 Node.js

Ubuntu / Debian 可以使用 NodeSource 安装：

sudo apt install -y curl ca-certificates
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs
node --version
npm --version

2. 安装 Codex CLI

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

如果遇到权限问题，可以配置 npm 用户目录：

npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex

3. 修改配置文件

mkdir -p ~/.codex
nano ~/.codex/config.toml

写入：

model = "控制台可用模型"
model_provider = "aidmx"
model_reasoning_effort = "medium"
disable_response_storage = true

[model_providers.aidmx]
name = "AIDMX"
base_url = "https://ai.aidmx.xyz/v1"
wire_api = "responses"
requires_openai_auth = true

再编辑：

nano ~/.codex/auth.json

{
  "OPENAI_API_KEY": "你的 AIDMX API Token"
}

4. 开始使用 Codex CLI

cd /path/to/your/project
codex

确认当前工作区。

选择权限模式。

使用 /model 检查模型：

/model

发送只读测试任务：

请说明当前项目结构，不要写入文件。

成功验证

1. codex --version 能输出版本号。
2. ~/.codex/config.toml 中的 base_url 是 https://ai.aidmx.xyz/v1。
3. ~/.codex/auth.json 中存在 OPENAI_API_KEY 且值为有效的 AIDMX Token。
4. 在项目目录中执行 codex，发送只读任务后能收到正常回复。

常见问题

找不到 codex 命令

检查安装和 PATH：

node --version
npm --version

然后重新安装：

npm install -g @openai/codex

如果是 npm 全局目录没有加入 PATH，把 npm config get prefix 对应的 bin 目录加入 shell 配置后重新打开终端。

配置后仍然没有 AIDMX 日志

确认 Codex 读取的是同一个用户目录下的配置：

ls -la ~/.codex
cat ~/.codex/config.toml

Windows 使用 WSL 时，PowerShell 的 %USERPROFILE%\.codex 和 WSL 的 ~/.codex 不是同一个目录。你在哪个环境运行 codex，就在哪个环境配置。

wire_api = "responses" 报错

把 wire_api 临时改成 chat 后再试。如果 chat 能成功，说明当前模型或网关对 Responses API 的支持不匹配；后续以 AIDMX 控制台和错误日志为准。

401 或 API Key 无效

重新从 令牌管理 复制 Token，确认 auth.json 没有多余换行、中文引号或转义错误。泄露过的 Token 应删除并重新创建。

模型名称不可用

把 model = "控制台可用模型" 改成 AIDMX 控制台实际可用的模型名称。修改后重新启动 Codex CLI。

不想影响默认 Codex 配置

先备份当前目录：

cp -R ~/.codex ~/.codex.backup

需要恢复时：

mv ~/.codex.backup ~/.codex

下一步

• 需要桌面端说明时，阅读 Codex。
• 需要理解通用 OpenAI 兼容配置时，阅读 OpenAI 兼容工具。
• 需要排查消耗和模型命中时，查看 使用日志。