Codex CLI 安装教程｜Windows、macOS、Linux

1. 安装前准备

可以运行 PowerShell 或 shell 的本地终端。
稳定的网络连接和当前用户目录写入权限。
准备一个代码项目目录；建议先使用带有版本控制的测试项目。

独立安装器是当前优先方式。npm 安装可以作为已经配置 Node.js 环境时的备选方案。

先确认命令来源安装命令会下载并执行脚本。运行前核对命令中的域名和完整内容，不要使用来源不明的修改版安装命令。

2. Windows 原生安装

打开 PowerShell，执行当前 Windows 安装命令：

PowerShell

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

安装结束后关闭并重新打开终端，让新的 PATH 设置生效。Windows 11 是更合适的原生环境；需要完整 Linux 工具链时使用 WSL2，并在 WSL 内执行 Linux 安装命令。

WSL 项目目录在 WSL2 中建议把项目放在 ~/code 等 Linux 文件系统目录，而不是 /mnt/c，可减少文件监听和权限差异。

3. macOS 与 Linux 安装

在终端运行独立安装器：

shell

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

已经安装 Node.js 和 npm 时，也可以选择：

npm

npm install -g @openai/codex

同一台设备尽量只保留一种安装渠道，避免 PATH 中存在多个版本。

4. 验证版本与运行环境

依次检查版本和环境诊断：

Terminal

codex --version
codex doctor --summary

codex doctor --summary 会检查安装、配置、认证、运行时、Git 和终端环境。排查问题时先保留诊断结果中不包含凭据的部分。

5. 登录并启动第一个项目

默认登录会打开浏览器：

Terminal

codex login
codex login status

无浏览器或本地回调受限时，可以使用设备授权：

Terminal

codex login --device-auth

进入自己的项目目录后启动：

Terminal

cd YOUR_PROJECT
codex

首次使用时先让 Codex 阅读项目结构、运行测试或解释一段代码，再逐步扩大任务范围。执行文件修改和命令前查看待执行操作。

6. 配置 island AI Coding 模型提供方

当前 Codex CLI 支持在 ~/.codex/config.toml 中定义 OpenAI 兼容模型提供方。本站接入使用 Responses API，因此应先确认 API Key 分组和目标模型支持 /v1/responses。

把 MODEL_ID 替换为创建密钥页面中适用于 Codex 的真实模型代号：

~/.codex/config.toml

model = "MODEL_ID"
model_provider = "island"

[model_providers.island]
name = "island AI Coding"
base_url = "https://www.codex789.com/v1"
env_key = "ISLAND_API_KEY"
wire_api = "responses"
requires_openai_auth = false

在当前终端会话设置密钥后启动 Codex：

PowerShell

$env:ISLAND_API_KEY = "YOUR_API_KEY"
codex

macOS / Linux

export ISLAND_API_KEY="YOUR_API_KEY"
codex

配置与聊天接口不同Codex CLI 使用 Responses API 协议，不能只根据普通 /chat/completions 请求成功就判断 Codex 配置一定可用。实际支持模型以创建密钥页面和控制台说明为准。

7. 更新 Codex CLI

支持自更新的发行版可以执行：

Terminal

codex update

如果当前安装渠道不支持自更新，重新执行对应安装命令；npm 安装则使用：

npm

npm install -g @openai/codex

更新后再次运行 codex --version 和 codex doctor --summary。

8. 常见安装与运行问题

现象	处理方法
找不到 `codex`	关闭并重开终端，检查 PATH；确认安装过程没有提前失败
更新后版本没有变化	检查是否同时存在独立版和 npm 版，PATH 顺序决定实际运行文件
浏览器登录回调失败	改用 `codex login --device-auth`
Windows 工具链不兼容	先运行诊断；确实依赖 Linux 工具时再使用 WSL2
本站模型请求失败	核对 Responses API 支持、模型代号、分组、环境变量和 Base URL
配置文件解析失败	检查 TOML 引号、节名和重复字段，先恢复到最小配置