如何安装 Codex CLI（2026）：安装、登录与首次运行
This post is also available in English.
Codex CLI 是 OpenAI 的开源终端编程 Agent：读取你的项目，在沙箱里修改代码并执行命令，由你决定它能在多大程度上自主操作。它是一个 Rust 二进制文件，安装很快。真正容易出问题的是另外几件事：哪些 ChatGPT 套餐包含 CLI、没有浏览器的服务器怎么登录、沙箱默认会拦截什么。本文按 2026 年 10 月的情况逐一说明。
开始之前
OpenAI 的安装文档列出的系统要求是 macOS 12 及以上、Ubuntu 20.04+ 或 Debian 10+，以及通过 WSL2 使用的 Windows 11；另外也提供 Windows 原生 PowerShell 安装脚本。内存至少 4 GB（建议 8 GB），建议安装 Git 2.23+ 以使用内置的 PR 辅助功能。只有选择 npm 方式时才需要 Node.js。
安装前先确认套餐：CLI 包含在 ChatGPT Plus、Pro、Business 和 Enterprise 中。 Free 和 Go 套餐只在 ChatGPT 桌面应用中包含 Codex，不含 CLI。另一种方式是使用按 token 计费的 OpenAI API Key。
第 1 步：选择安装方式
独立安装脚本是 OpenAI 的默认方式。
# macOS、Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh# Windows
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"安装脚本默认从 releases.openai.com 下载，失败时会自动改用 GitHub Releases。如果你的网络屏蔽了其中一个，可以设置 CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false，直接从 GitHub 下载。
包管理器安装的是同一个二进制：
npm install -g @openai/codex
brew install --cask codex也可以直接下载发布版二进制。 GitHub 最新发布页 提供 codex-aarch64-apple-darwin.tar.gz（Apple Silicon）、codex-x86_64-unknown-linux-musl.tar.gz（Linux）等压缩包，每个包里只有一个带平台名的文件，重命名为 codex 并放到 PATH 中即可。
第 2 步：验证安装
新开一个终端，然后运行：
codex --version
codex doctorcodex --version 会输出 codex-cli 和版本号。codex doctor 值得运行一次：它会检查登录凭证、磁盘空间、安装一致性、内置搜索工具、git 和网络连通性，并告诉你该怎么修。
测试机上全新安装后的真实输出，2026 年 10 月 12 日。doctor 输出只保留了摘要行。
全新安装时，doctor 唯一的失败项应该是 auth，下一步登录后就会解决。
第 3 步：登录
运行 codex（或 codex login），选择登录方式：
首次运行界面。使用 ChatGPT 登录时，用量包含在 Plus、Pro、Business 和 Enterprise 套餐中。
- Sign in with ChatGPT：打开浏览器登录，凭证会自动回传给 CLI，这是默认方式。
- Sign in with Device Code：适合没有浏览器的机器，比如通过 SSH 连接的远程服务器。你会拿到一个一次性代码，在另一台设备上输入。
- Provide your own API key：按量付费的 API 计费。也可以从环境变量直接传入 Key：
登录方式也决定了适用哪套数据策略：用 ChatGPT 登录时遵循 ChatGPT 工作区的权限和数据保留设置，用 API Key 时遵循 API 组织的设置。
第 4 步：运行第一个任务
cd my-project
codex让它介绍一下项目，或者做一个小而明确的修改。动手前先提交一次代码，方便回滚。Codex 默认使用 Auto 预设：可以在工作目录内读取文件、修改代码和执行命令；要访问工作目录之外的内容或使用网络时，必须先征求你的同意。网络访问默认关闭。如果只想让它做规划，可以用 /permissions 切换到只读模式。
两个设置建议：在仓库根目录添加 AGENTS.md，写上构建、测试和代码风格规则，Codex 每次会话都会读取，其他很多 Agent 也会读。如果你在 ~/.codex/config.toml 里固定了模型，请检查一下：GPT-5.5 将于 2026 年 10 月 14 日从 Codex 下线，请用 /model 或 codex --model gpt-6-sol 换成 gpt-6-sol。
排错
codex: command not found。 新开一个终端让新的 PATH 生效，然后运行 which codex。用 npm 安装的，确认 npm 全局 bin 目录在 PATH 中；用发布版二进制的，确认已重命名为 codex 并赋予执行权限（chmod +x codex）。
npm 报 EACCES 权限错误。 不要用 sudo npm。改用独立安装脚本，或者把 npm 的全局目录设到用户自己的目录。
在服务器上登录卡住。 使用 Sign in with Device Code，或用 --with-api-key 通过 API Key 登录。
登录后仍显示「Not logged in」。 运行 codex login status。如果你自定义了 CODEX_HOME，确保每个 shell 的设置一致，因为凭证保存在那里。
公司网络。 如果 codex doctor 提示 Responses WebSocket 连接失败，CLI 通常会自动退回 HTTPS。如果请求仍然失败，请检查代理、VPN 和自定义 CA 设置。
更新与卸载
运行 codex update，或重新运行独立安装脚本即可原地更新。npm 用户再次运行 npm install -g @openai/codex，Homebrew 用户运行 brew upgrade --cask codex。
卸载时，npm 用 npm uninstall -g @openai/codex，Homebrew 用 brew uninstall --cask codex。独立安装脚本或发布版二进制，删除 which codex 指向的文件即可。设置和会话保存在 ~/.codex，想彻底清理的话也把这个目录删掉。
不用终端：OpenAgents Launcher
OpenAgents Launcher 可以在「Agents」页一键安装 Codex CLI 并保持更新，和 Claude Code、Gemini CLI 等放在一起管理。把电脑与 OpenAgents Workspace 配对后，Codex 会加入共享线程，团队成员可以用 @ 提及给它派活，比如 @codex-cli 编写集成测试，并在任意设备上跟进进度。
还在比较 Agent？可以看看 Codex vs Claude Code（2026）、我们的 Claude Code 安装教程，或者 Codex CLI 和 Claude Code 的 Agent 页面。
常见问题
怎么安装 Codex CLI？
macOS 或 Linux 上运行 curl -fsSL https://chatgpt.com/codex/install.sh | sh，Windows 上运行 PowerShell 安装脚本。也可以用 npm install -g @openai/codex 或 brew install --cask codex。安装后运行 codex 登录。
Codex CLI 免费吗？ CLI 开源（Apache-2.0）且免费安装。使用时需要 ChatGPT Plus、Pro、Business 或 Enterprise 套餐，或按 token 计费的 OpenAI API Key。Free 和 Go 套餐只在桌面应用中包含 Codex。
Codex CLI 支持 Windows 吗？ 支持。有原生 PowerShell 安装脚本；OpenAI 的安装文档列出的是通过 WSL2 使用的 Windows 11，这也是测试最充分的方式。
没有浏览器怎么登录 Codex CLI？
选择「Sign in with Device Code」，在另一台设备上输入一次性代码；或者用 printenv OPENAI_API_KEY | codex login --with-api-key 传入 API Key。
怎么更新 Codex CLI？
运行 codex update，或重新运行独立安装脚本。npm 和 Homebrew 用户分别重新安装或运行 brew upgrade --cask codex。
Codex CLI 的设置保存在哪里？
保存在 ~/.codex，包括 config.toml、登录凭证和会话记录。可以通过设置 CODEX_HOME 更改位置。