Skip to content

Codex(终端) ​

通过配置文件在电脑上安装和接入 Codex CLI。

  • 协议与地址: OpenAI Responses 协议,base_url 填 https://aicode.cat/v1(要加 /v1)。
  • 密钥与配置: Key 写在 ~/.codex/auth.json 的 OPENAI_API_KEY;模型与地址写在 ~/.codex/config.toml。
  • 前置准备: 先到 创建 API Key 拿一把绑定了 OpenAI / Codex 分组的 Key。下面示例模型用 gpt-6.1(以 主站控制台 为准)。

macOS / Linux ​

1. 安装 Node.js(需 18+) ​

已经装过 Node.js 18+ 可直接跳到第 2 步。

  • macOS: 先安装 Homebrew(部分海外资源需开启 TUN 代理),再安装 Node.js:

    Bash
    brew install node
    node --version
  • Linux(Debian / Ubuntu):

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

2. 安装 Codex CLI ​

Bash
npm install -g @openai/codex --registry=https://registry.npmmirror.com/

安装 Codex CLI

3. 创建配置文件 ​

把 在这里替换成你的_API_KEY 换成你的 Key,在终端执行:

命令行写入
dir="$HOME/.codex"
mkdir -p "$dir"

cat > "$dir/auth.json" << 'EOF'
{
  "OPENAI_API_KEY": "在这里替换成你的_API_KEY"
}
EOF

cat > "$dir/config.toml" << 'EOF'
model_provider = "codex"
model = "gpt-6.1"

[model_providers.codex]
name = "codex"
base_url = "https://aicode.cat/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false
EOF

echo "配置完成"
手动:~/.codex/auth.json
{
  "OPENAI_API_KEY": "在这里替换成你的_API_KEY"
}
手动:~/.codex/config.toml
model_provider = "codex"
model = "gpt-6.1"

[model_providers.codex]
name = "codex"
base_url = "https://aicode.cat/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

核对配置(只检查字段和地址,不把 Key 打印到终端):

Bash
grep -q '"OPENAI_API_KEY"' "$HOME/.codex/auth.json" && echo 'OPENAI_API_KEY=<已设置>'
grep '^base_url' "$HOME/.codex/config.toml"

核对配置

4. 验证安装 ​

终端输入 codex 启动,在对话框里输入「您好!」,能正常回复即配置成功。

Bash
codex

验证对话

Windows ​

1. 安装 Node.js(需 18+) ​

前往 Node.js 官网 下载安装 LTS 版本,装完在 PowerShell 执行 node --version 确认版本 ≥ 18。

Windows 检查 Node 版本

2. 安装 Codex CLI ​

按 Win + R 输入 powershell 打开 PowerShell,执行:

PowerShell
npm install -g @openai/codex --registry=https://registry.npmmirror.com/

Windows 安装 Codex CLI

若提示「在此系统上禁止运行脚本」,以管理员身份运行 PowerShell,执行 Set-ExecutionPolicy Unrestricted 并输入 Y 确认,再重新安装。

3. 创建配置文件 ​

把 在这里替换成你的_API_KEY 换成你的 Key,在 PowerShell 执行:

命令行写入
$dir = Join-Path $env:USERPROFILE ".codex"
New-Item -ItemType Directory -Path $dir -Force | Out-Null

$auth = @'
{
  "OPENAI_API_KEY": "在这里替换成你的_API_KEY"
}
'@
[System.IO.File]::WriteAllText(
  (Join-Path $dir "auth.json"),
  $auth,
  (New-Object System.Text.UTF8Encoding($false))
)

$config = @'
model_provider = "codex"
model = "gpt-6.1"

[model_providers.codex]
name = "codex"
base_url = "https://aicode.cat/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false
'@
[System.IO.File]::WriteAllText(
  (Join-Path $dir "config.toml"),
  $config,
  (New-Object System.Text.UTF8Encoding($false))
)
手动:auth.json
{
  "OPENAI_API_KEY": "在这里替换成你的_API_KEY"
}
手动:config.toml
model_provider = "codex"
model = "gpt-6.1"

[model_providers.codex]
name = "codex"
base_url = "https://aicode.cat/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

手动方式的文件路径:C:\Users\<你的用户名>\.codex\auth.json 和 C:\Users\<你的用户名>\.codex\config.toml。

核对配置:

PowerShell
if (Select-String -Path "$env:USERPROFILE\.codex\auth.json" -Pattern 'OPENAI_API_KEY') { 'OPENAI_API_KEY=<已设置>' }
Select-String -Path "$env:USERPROFILE\.codex\config.toml" -Pattern '^base_url'

Windows 核对配置

4. 验证安装 ​

PowerShell 中输入 codex 启动:

PowerShell
codex

Windows 启动 Codex

若弹出 Since this folder is not version controlled…,选第一个 Allow Codex to work in this folder without asking for approval 回车。输入「您好!」,能正常回复即配置成功。

Windows 验证对话

常见问题 ​

1. 非版本控制目录授权提示(Since this folder is not version controlled…) ​

非版本控制目录授权提示

选第一个 Allow Codex to work in this folder without asking for approval,允许它在当前文件夹读写和执行命令,避免每次操作都弹窗确认。

2. 手动打开配置目录与改完不生效排查 ​

  • Windows(CMD): start "" "%USERPROFILE%\.codex"(用记事本新建时请勾选显示「文件扩展名」,防止保存成 config.toml.txt;Windows 与 WSL 的 .codex 目录彼此独立)
  • macOS(终端): mkdir -p "$HOME/.codex" && open "$HOME/.codex"(访达按 Command + Shift + . 显示隐藏文件)

如果改了 config.toml 但不生效,按顺序检查 5 点:

  1. 是否彻底重启: 终端按 Ctrl + C 退出重进;VS Code 执行 Reload Window;Codex App 需在系统托盘图标上右键退出。
  2. 字段位置对不对: model_provider、model 等顶层字段必须写在所有 [xxx] 表头之前;base_url 必须写在 [model_providers.codex] 下面。
  3. provider 名字对不对: 顶层 model_provider = "codex" 要与 [model_providers.codex] 完全一致,不要命名为内置保留名 openai。
  4. 有没有残留官方登录: 若之前登录过 ChatGPT 官方账号,先运行 codex logout 退出登录。
  5. 有没有环境变量覆盖: 检查系统是否设置了 OPENAI_BASE_URL 或 CODEX_HOME。

3. 改完配置后打不开或报 requires Responses for tool calls ​

  • 打不开 / 点了没反应: 打开任务管理器(Ctrl + Shift + Esc)结束所有 Codex、ChatGPT、codex.exe 进程;Windows 路径在 TOML 里要用双反斜杠 \\ 或单引号包裹。
  • 报 requires Responses for tool calls: 检查 [model_providers.codex] 下是否写了 wire_api = "responses",并到 密钥页 确认 Key 绑定的是 Codex / OpenAI 分组。

4. Windows 下输出中文乱码 ​

按 Win + R 输入 intl.cpl 回车 → 切到「管理」选项卡 → 点「更改系统区域设置」→ 勾选 Beta 版:使用 Unicode UTF-8 提供全球语言支持 → 确定并重启电脑。

5. 全局提示词(AGENTS.md)与常用斜杠命令 ​

可在 ~/.codex/AGENTS.md(Windows 为 %USERPROFILE%\.codex\AGENTS.md)写全局指令,或在项目根目录放 AGENTS.md(运行 /init 可生成模板)。

斜杠命令作用
/model切换当前模型与思考强度
/review审查当前工作区改动(后台会调用辅助模型,账单出现小模型属正常现象)
/compact压缩历史对话释放上下文(上下文超过 60% 建议 /new 新开会话)
/resume恢复历史会话
/new开启新对话
/diff查看当前 Git 改动
/status查看当前生效配置与 Token 用量
/mcp查看已加载的 MCP 工具