Codex CLI 安装教程（macOS）

macOS 下推荐使用 npm 安装 Codex CLI。整个流程不需要管理员权限，所有文件都落在用户目录内。

0. 前置：安装 Node.js

Codex CLI 需要 Node.js 22 及以上。若系统尚未安装，可任选一种方式：

# 方式 1：Homebrew
brew install node

# 方式 2：官网安装包
# 前往 https://nodejs.org/ 下载 macOS Installer

安装完验证：

node -v
npm -v

1. 安装 Codex

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

若提示写入权限问题，通常是 npm 全局前缀指向了系统目录。可用 nvm / fnm 切到用户级 Node，或 npm config set prefix ~/.npm-global 后重新安装。

2. 配置 Codex 接入 AI通道

2.1 配置文件在哪里

Codex 默认从用户主目录读取：

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

2.2 创建配置目录

mkdir -p ~/.codex

2.3 写入主配置 config.toml

cat > ~/.codex/config.toml <<'EOF'
model = "gpt-5-codex"
model_provider = "aitongdao"
approval_policy = "on-request"

[model_providers.aitongdao]
name = "aitongdao"
base_url = "https://ai.aitongdao.com/v1"
wire_api = "responses"
EOF

字段说明：

• model：默认调用的模型名，可改为 gpt-5.2-codex 或 gpt-5。
• model_provider：指向下方 [model_providers.xxx] 的 key，名字可自定义。
• approval_policy：on-request 表示 Codex 在执行有副作用的命令前会询问确认。
• base_url：AI通道的 OpenAI 兼容端点，注意要带 /v1。
• wire_api：使用 Responses 协议（Codex 推荐）。

2.4 写入认证文件 auth.json

cat > ~/.codex/auth.json <<'EOF'
{
  "OPENAI_API_KEY": "sk-你的密钥"
}
EOF

把 sk-你的密钥 替换为在 aitongdao.com「令牌」页创建的实际值。

2.5 验证配置文件是否创建成功

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

3. 启动并验证

codex --version
cd ~/your-project
codex

首次进入会话后，可让 Codex 读取当前目录做一次简单任务（例如"解释下这个仓库的结构"）确认调用链路正常。

常见问题

codex 命令找不到

执行 npm prefix -g 查看全局前缀，把 <前缀>/bin 加入 ~/.zshrc 的 PATH：

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

cat > ~/.codex/config.toml 写入失败

检查目录权限：ls -ld ~/.codex。必要时 chmod 755 ~/.codex 修正。

API 调用返回 401 或 404

• 401：API Key 错误，或令牌分组不是 codex。
• 404：base_url 没带 /v1，或 wire_api 写错（必须是 responses）。

想同时保留原生 OpenAI 配置

可在 config.toml 中写多个 [model_providers.xxx] 段落，然后在命令行用 codex --config model_provider=xxx 切换。