主题
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:
Bashbrew install node node --versionLinux(Debian / Ubuntu):
Bashcurl -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/
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
Windows
1. 安装 Node.js(需 18+)
前往 Node.js 官网 下载安装 LTS 版本,装完在 PowerShell 执行 node --version 确认版本 ≥ 18。

2. 安装 Codex CLI
按 Win + R 输入 powershell 打开 PowerShell,执行:
PowerShell
npm install -g @openai/codex --registry=https://registry.npmmirror.com/
若提示「在此系统上禁止运行脚本」,以管理员身份运行 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'
4. 验证安装
PowerShell 中输入 codex 启动:
PowerShell
codex
若弹出 Since this folder is not version controlled…,选第一个 Allow Codex to work in this folder without asking for approval 回车。输入「您好!」,能正常回复即配置成功。

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