Codex CLI 安装教程：macOS、Linux、Windows 与登录配置

本教程完成四件事：安装 Codex CLI、登录账户、在项目中启动 Codex、验证本机工具链是否可用。

1. 安装前准备

建议先准备：

• 一个可登录的 ChatGPT 账户或可用的认证方式；
• Git；
• 你的项目运行环境，例如 Node.js、Python、Java、Flutter；
• 一个已经初始化 Git 的测试项目。

检查 Git：

git --version

Codex 会调用本机已有命令。它不会自动替你安装所有项目依赖，因此 Node、Java、Flutter 等环境仍需正常配置。

2. macOS 和 Linux 安装

官方提供独立安装脚本：

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

安装后检查：

codex --version

如果提示找不到命令，先重新打开终端，再检查 PATH：

echo $PATH
which codex

升级

再次执行安装脚本即可更新：

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

升级后再次确认版本：

codex --version

3. npm 安装方式

已经安装 Node.js 时，也可以使用 npm 安装：

npm install -g @openai/codex

检查安装位置：

npm prefix -g
which codex
codex --version

升级：

npm install -g @openai/codex@latest

npm 全局目录不在 PATH 时，常见现象是“安装成功但 codex 命令不存在”。需要把 npm 全局 bin 目录加入 Shell 配置。

4. Homebrew 安装

官方 CLI 页面可能会根据平台提供 Homebrew 入口。使用前先在官方页面核对当前命令，因为包形式可能调整。

安装后统一用下面命令验证：

codex --version

不要在同一台机器同时长期维护多个来源的 Codex，例如同时使用 npm 和独立安装器，否则可能出现版本与路径不一致。

检查实际执行的是哪个文件：

which -a codex

如果返回多个路径，应保留一种安装方式并删除其他重复版本。

5. Windows 安装建议

Windows 可以选择：

1. 原生 Windows 环境；
2. WSL2 环境。

如果项目主要部署到 Linux，或依赖大量 Linux Shell 工具，优先考虑 WSL2。如果项目是 .NET、Windows 桌面应用或依赖 Windows SDK，可以使用原生模式。

在 WSL2 中，可按 Linux 方法安装：

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

Linux 和 WSL2 的沙箱通常依赖 bubblewrap。Ubuntu/Debian 可安装：

sudo apt update
sudo apt install bubblewrap

原生 Windows 模式可在配置中设置推荐沙箱：

[windows]
sandbox = "elevated"

如果没有管理员权限或 elevated 初始化失败，再考虑：

[windows]
sandbox = "unelevated"

6. 第一次启动与登录

进入一个项目目录：

cd ~/code/my-project
codex

第一次启动时，按照界面选择登录方式。完成登录后，可以使用：

/status

查看当前任务、模型、上下文、权限或速率限制等状态信息。

也可以先输入：

Tell me about this project.

中文环境建议直接使用中文：

先不要修改代码，概括这个项目的用途、技术栈、启动命令和测试命令。

7. 建议先做的 Git 准备

Codex 直接修改代码前，先检查工作区：

git status

如果已有未提交修改，建议先处理：

git add -A
git commit -m "chore: checkpoint before codex"

或创建新分支：

git switch -c codex/first-task

对于并行任务，可以使用 worktree：

git worktree add ../my-project-codex -b codex/experiment
cd ../my-project-codex
codex

8. Shell 自动补全

Codex 支持生成 Shell completion。先查看帮助：

codex completion --help

根据你的 Shell 生成配置。例如 zsh 常见流程是将输出写入补全目录，然后重新加载 Shell。具体参数以当前版本 --help 为准。

确认当前 Shell：

echo $SHELL

9. 验证本机开发工具

Codex 使用本机命令，所以应主动检查工具是否可运行。

Node.js 项目：

node --version
npm --version

Python 项目：

python3 --version
pip3 --version

Flutter 项目：

flutter doctor

Java 项目：

java -version
./gradlew --version

然后让 Codex执行一个只读检查：

不要修改文件。识别本项目的包管理器、启动命令、Lint 命令和测试命令，并验证这些命令是否存在。

10. 常见安装问题

10.1 codex: command not found

检查：

which -a codex
echo $PATH

如果使用 npm：

npm prefix -g

将对应 bin 路径加入 ~/.zshrc 或 ~/.bashrc，然后：

source ~/.zshrc

10.2 版本不是刚安装的版本

通常是 PATH 中存在多个 Codex：

which -a codex

删除旧版本或调整 PATH 顺序。

10.3 登录完成后仍然要求登录

检查：

• 是否在多个系统用户下运行；
• CODEX_HOME 是否被修改；
• ~/.codex 是否可写；
• 企业代理或浏览器回调是否被阻断。

查看 Codex Home：

echo ${CODEX_HOME:-$HOME/.codex}
ls -la ${CODEX_HOME:-$HOME/.codex}

10.4 Linux 沙箱初始化失败

安装 bubblewrap：

sudo apt install bubblewrap

容器、受限服务器或特殊内核环境可能无法正常启用系统沙箱。不要直接使用 --yolo 解决，应先确认外层是否已经提供可靠隔离。

10.5 项目命令运行失败

Codex 已安装成功不代表项目依赖完整。先手工执行：

npm install
npm test

或项目对应的安装和测试命令，再把错误交给 Codex分析。

11. 完成安装后的推荐检查

在项目目录执行：

codex --version
git status
codex

进入 Codex 后依次使用：

/status
/permissions
/model

最后输入：

不要修改代码。读取项目并输出：
- 技术栈
- 启动命令
- 测试命令
- 核心目录
- 当前 Git 状态

如果 Codex 能正确读取目录、运行只读命令并输出项目结构，安装流程就完成了。

官方参考

• https://learn.chatgpt.com/docs/codex/cli
• https://learn.chatgpt.com/docs/developer-commands?surface=cli
• https://learn.chatgpt.com/docs/sandboxing
• https://learn.chatgpt.com/docs/config-file/environment-variables

资料核对日期：2026-07-14。安装方式和平台支持可能随版本更新，正式发布前应重新核对官方 CLI 页面。