Tip · Last checked
CLI installation and authentication guidance was checked on 2026-10-12. See the Codex CLI documentation, authentication, and Windows WSL guide.
Install Codex CLI
Before installation
Codex CLI runs on macOS, Linux, and Windows. Windows can run it natively; WSL2 remains useful when the project and toolchain already live in Linux.
| Check | Guidance |
|---|---|
| Git | Recommended for repository context, diffs, and rollback points |
| Node.js and npm | Needed only for the npm installation path |
| Workspace | Use a folder where a small test change can be reverted |
git --version
node -v
npm -v
Install and update
On macOS or Linux, use the official installer:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
With Node.js, install the package from npm:
npm install -g @openai/codex
npm install -g @openai/codex@latest
On macOS, Homebrew is another documented option:
brew install --cask codex
Check the installed version:
codex --version
Authentication
You can sign in with a ChatGPT account or provide an OpenAI API key. They are different account and billing paths; availability still depends on the workspace and plan.
codex login
For an API-key session, follow the current CLI authentication instructions rather than placing a key in a shell history or repository file.
First read-only task
Change to a project folder and ask Codex to inspect the repository without editing it. Confirm the output, permissions, and test command before allowing a write.
Troubleshooting
Separate network, package, sign-in, and permission errors. Check the official documentation and the installed version before trying a different installer.
Next step
Continue with your first Codex CLI task.
Code examples
npm install -g @openai/codex
npm install -g @openai/codex@latest
printenv OPENAI_API_KEY | codex login --with-api-key
cd path/to/your/project
codex
请先阅读这个仓库的目录结构、README、包管理器配置和测试配置。不要修改文件。请总结:
1. 项目用途
2. 主要技术栈
3. 如何安装依赖和运行测试
4. 你建议我下一步交给你的 3 个低风险任务
Reference screenshots




Source and internal links
- /start/01-what-is-codex.md
Reference tables
| Projects | 说明 |
|---|---|
| 操作系统 | 支持 macOS、Linux 和 Windows;Windows 可以原生运行,也可以按需使用 WSL2 |
| Git | 推荐安装,方便 Codex 读取仓库、检查差异和创建回退点 |
| Node.js 与 npm | 只有选择 npm 安装方式时才需要 |
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
codex 命令找不到 | 安装目录未进入 PATH,或安装尚未完成 | 先确认使用的是独立脚本、npm 还是 Homebrew,再检查对应安装目录和 shell PATH |
| 登录后仍提示无权限 | 登录方式、账号计划、工作区策略或会话状态问题 | 运行 codex login 重新登录,并确认使用的是 ChatGPT 账号还是 API Key |
| Windows 原生运行异常 | Windows sandbox、终端或本地工具链不满足项目需要 | 先检查原生环境;需要 Linux 工具链时再改用 WSL2,并把仓库放在 Linux 主目录下 |
| 仓库命令跑不起来 | 项目依赖未安装或本地环境缺失 | 先安装项目依赖,再让 Codex 读取测试配置 |
