Codex CLI 安装使用教程（Windows & macOS）

Codex CLI 是 OpenAI 推出的本地运行 AI 编程助手，支持终端命令行交互、代码生成、项目重构等。本文详细介绍在 Windows 和 macOS 上的安装与配置过程。

一、macOS 安装 Codex CLI

1.1 一键安装（推荐）

打开终端（Terminal），执行以下命令：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

安装完成后，终端会显示 Codex CLI installed successfully。

1.2 通过 Homebrew 安装

如果你使用 Homebrew 包管理器：

brew install --cask codex

1.3 通过 npm 安装

如果你已安装 Node.js：

npm install -g @openai/codex

1.4 从 GitHub Release 手动下载

前往 GitHub Releases 下载对应架构的二进制文件：

• Apple Silicon（M1/M2/M3/M4）：下载 codex-aarch64-apple-darwin.tar.gz
• Intel 芯片：下载 codex-x86_64-apple-darwin.tar.gz

# 解压并安装
tar -xzf codex-aarch64-apple-darwin.tar.gz
sudo mv codex-aarch64-apple-darwin /usr/local/bin/codex
chmod +x /usr/local/bin/codex

1.5 验证安装

codex --version

输出类似 codex 0.x.x 即安装成功。

二、Windows 安装 Codex CLI

2.1 一键安装（推荐）

打开 PowerShell（以管理员身份运行），执行：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

安装完成后会显示成功提示。

2.2 通过 npm 安装（需 Node.js）

先安装 Node.js，然后：

npm install -g @openai/codex

2.3 从 GitHub Release 手动下载

前往 GitHub Releases 下载 Windows 版本二进制文件，解压后将 codex.exe 放到系统 PATH 路径下（如 C:\\Windows\\ 或自建目录并添加到环境变量）。

2.4 验证安装

codex --version

2.5 Windows 额外说明

⚠️ Codex CLI 在 Windows 上的某些功能（如文件沙箱）需要 WSL2 支持。推荐安装 WSL2 + Ubuntu，然后在 WSL 的 Linux 环境中运行 Codex，体验更佳。

# 安装 WSL2
wsl --install
# 重启后在 WSL Ubuntu 终端中安装 Codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh

三、登录认证（两种方式）

3.1 使用 ChatGPT 账号登录（推荐）

如果你有 ChatGPT Plus / Pro / Business / Edu 订阅，可以直接用账号登录，无需额外付费：

codex login

执行后会自动打开浏览器，登录 ChatGPT 账号并授权即可。授权完成后终端会显示 Logged in successfully。

3.2 使用 API Key 登录

如果你没有 ChatGPT 订阅，但有 OpenAI API Key，可以用以下方式登录：

macOS / Linux：

printenv OPENAI_API_KEY | codex login --with-api-key

Windows PowerShell：

$env:OPENAI_API_KEY | codex login --with-api-key

📌 API Key 登录按照标准 API 费率计费，不使用 ChatGPT 订阅额度。API Key 可在 OpenAI Dashboard 获取。

3.3 检查登录状态

codex login status

3.4 退出登录

codex logout

四、配置文件详解

Codex CLI 的配置文件位于 ~/.codex/config.toml（macOS）或 C:\\Users\\你的用户名\\.codex\\config.toml（Windows）。

💡 第一次运行 codex 时会自动创建 .codex 目录。

4.1 基本配置示例

# 选择模型（默认 gpt-5.4-codex）
model = "gpt-5.4-codex"

# 推理强度（low / medium / high / xhigh）
reasoning_effort = "medium"

# 审批模式（untrusted / on-failure / never）
approval_mode = "on-failure"

4.2 使用第三方 API 中转站（自定义 Provider）

如果你使用第三方 API 中转站（如自己的 NewAPI 中转），可以自定义 model provider：

# 指定使用自定义 provider
model_provider = "myrelay"

# 定义 provider
[model_providers.myrelay]
name = "My API Relay"
base_url = "https://api.ffmx.online/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

⚠️ env_key 对应环境变量名，Codex 会从该环境变量读取 API Key。使用前需要设置：
bash export OPENAI_API_KEY="sk-xxxxxxxxxxxxx"

4.2.1 在 auth.json 中直接写入第三方 Key（免设置环境变量）

除了用环境变量，你也可以直接把第三方 API Key 写入 Codex 的认证缓存文件 ~/.codex/auth.json，这样不需要每次都 export 环境变量。

macOS / Linux：

mkdir -p ~/.codex
cat > ~/.codex/auth.json << 'EOF'
{
  "OPENAI_API_KEY": "sk-你的第三方中转站key"
}
EOF
chmod 600 ~/.codex/auth.json

Windows（PowerShell）：

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex"
@'
{
  "OPENAI_API_KEY": "sk-你的第三方中转站key"
}
'@ | Set-Content -Path "$env:USERPROFILE\.codexuth.json" -Encoding UTF8

📌 auth.json 文件格式为 JSON，key 名固定为 OPENAI_API_KEY，值填你的第三方中转站 API Key。

⚠️ 此文件等同于密码文件，请勿提交到 Git 仓库或分享给他人。建议设置 chmod 600 限制读取权限。

💡 写入 auth.json 后直接运行 codex 即可，无需执行 codex login 或 export 环境变量。Codex 会自动读取该文件中的 Key 进行认证。

4.3 模型选择

Codex 默认使用 gpt-5.4-codex 模型。你也可以手动指定其他模型：

[model_providers.myrelay]
name = "My API Relay"
base_url = "https://api.ffmx.online/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

[models]
model = "gpt-5.6-sol"

命令行临时指定模型：

codex --model gpt-5.6-sol "帮我写一个 Python 排序脚本"

五、常用命令

交互模式快捷操作

六、常见问题

Q1：安装提示 command not found

macOS：将 Codex 添加到 PATH：

echo 'export PATH="$HOME/.codex/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows：确认安装路径在系统 PATH 环境变量中。

Q2：登录后提示 Authentication failed

• 检查网络是否需要代理
• 确认 API Key 是否有效
• 尝试重新登录：codex logout && codex login

Q3：连接超时 / 网络问题

如果你在中国大陆使用，可能需要配置代理：

export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
codex

Windows PowerShell：

$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY = "http://127.0.0.1:7890"
codex

Q4：如何使用自定义中转站 API

在 ~/.codex/config.toml 中配置：

model_provider = "myrelay"

[model_providers.myrelay]
name = "My Relay"
base_url = "https://api.ffmx.online/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

然后设置环境变量：

export OPENAI_API_KEY="sk-你的中转站key"
codex

Q5：Windows 下沙箱功能不可用

Windows 的文件系统沙箱需要 WSL2 支持。推荐在 WSL2 Ubuntu 中运行 Codex：

wsl --install

重启后进入 WSL 终端安装 Codex 即可获得完整功能。

七、总结

安装完成后运行 codex 即可开始使用。如果有 ChatGPT Plus 订阅，建议用 codex login 直接登录，无需额外配置 API Key。#codex #教程 #OpenAI