← Back to learning path
Chapter · Published

Install Codex CLI

Install Codex CLI, choose ChatGPT or API-key authentication, check the version, and prepare a read-only first run.

Source: start/10-cli-installation.md快速上手 (original language)
Chapter progress 0%Learning path progress 0% · 0/46 chapters completedContinue learning path →

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.

CheckGuidance
GitRecommended for repository context, diffs, and rollback points
Node.js and npmNeeded only for the npm installation path
WorkspaceUse 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

Reference screenshot

Reference screenshot

Reference screenshot

Reference screenshot

  • /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 读取测试配置

Further reading

KnowledgeAI Agents: From Core Concepts to ProductionKnowledgeRAG for Enterprise Knowledge: Architecture and PracticeKnowledgeProduction Prompt Engineering: From Instructions to Measurable Contracts
Product Hub Demo · V0.3