如何安装 Codex CLI：在 macOS、Windows 和 Linux 上开始使用 OpenAI 编码代理

摘要

Codex CLI 是一个在终端中运行 OpenAI 编码代理的工具。过去 npm install -g @openai/codex仅仅解释一下就足够了，但现在选项已经扩展到包括官方安装脚本、Homebrew cask、npm 和 GitHub Release 二进制文件。在本文中，我们总结了截至 2026 年 6 月的 Codex CLI 安装方法和登录方法，以及经常出现的安装/身份验证/终端问题。

目录

• 背景
• 安装前检查
• 如何安装 Codex CLI
• 登录和身份验证方法
• 基本用法
• 故障案例及解决方案
• 最佳实践
• 常见错误
• 结论
• 参考资料

背景

当你搜索安装Codex CLI时，你仍然会发现很多旧文章。尤其是 Node.js 22 이상 필요, codex --login 실행, brew install codex像这样，存在根据当前标准不准确或可能根据环境而不同运行的内容的混合物。

根据目前官方的README，Codex CLI可以安装在macOS、Linux和Windows上，并且有多种安装方法。最简单的方法是使用官方安装脚本，如果你是已经使用npm的开发人员， @openai/codex 您也可以将其安装为软件包。

重要的是安装命令 使用什么身份验证方法, 在我的终端中 codex 命令真的被捕获了吗？, 检查公司/学校/代理环境中网络是否被阻止。是的。事实上，大部分的堵塞都来自这里。

安装前检查

首先，检查您当前的环境。

node -v
npm -v
which node
which npm
uname -m

使用 npm 安装时，npm 包 engines 现在的标准是 node >=16是的。不过实际使用中，还是使用最新的LTS系列Node.js比较安全。已经 nvm, fnm, volta 如果您使用相同的 Node 版本管理器，您还应该检查全局 npm 安装位置在哪里。

npm config get prefix
which codex

在 Windows 上，建议安装 PowerShell 或 Windows Terminal，并提前决定开发工作是在 WSL2 还是 Windows 本机中完成。两者的 PATH 和身份验证文件位置可能不同。

如何安装 Codex CLI

方法一、使用官方安装脚本安装

在 macOS 或 Linux 上，官方自述文件将指导您完成以下命令。

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

在 Windows PowerShell 中，使用以下命令：

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

如果您是第一次安装，此方法是最简单的。但是，在由于公司安全策略而限制远程脚本执行的环境中，首先检查脚本内容或使用 npm/Homebrew/GitHub Release 方法可能更合适。

方法2.使用npm安装

如果您已经在使用 Node.js 和 npm，您还可以全局安装 npm。

npm install -g @openai/codex

安装后检查。

codex --version
which codex

截至2026年6月16日检查，npm @openai/codex 最新版本是 0.140.0是的。 npm 全局安装很简单， nvm在使用 的环境中，如果更改 Node 版本，全局包可能会安装在不同的位置。在这种情况下 which codex 如果结果不符合预期，您应该首先检查您的 PATH。

方法3.使用Homebrew安装

macOS 还提供了 Homebrew cask 方法。

brew install --cask codex

经常在现有的文章中看到 brew install codex请小心，因为可能会有所不同。官方自述文件是 --cask 我们指导您完成安装。

方法 4. 使用 GitHub Release 二进制文件安装

如果您发现使用包管理器有困难，您可以从 GitHub Release 获取适合您平台的二进制文件。

• Apple Silicon Mac: codex-aarch64-apple-darwin.tar.gz
• Intel Mac: codex-x86_64-apple-darwin.tar.gz
• Linux x86_64: codex-x86_64-unknown-linux-musl.tar.gz
• Linux arm64: codex-aarch64-unknown-linux-musl.tar.gz

解压后，将可执行文件名改为 codex只需将其更改为并将其移动到 PATH 中的某个位置即可。

chmod +x codex
sudo mv codex /usr/local/bin/codex
codex --version

登录和身份验证方法

当您第一次运行 Codex CLI 时，它通常以登录流程开始。

codex

根据官方README， 使用您的 ChatGPT 帐户登录这是推荐的方法。这是因为 Codex 使用权限可以链接到 Plus、Pro、Business、Edu 和 Enterprise 计划。

它也可以用作 API 密钥，但在这种情况下需要单独设置。就像之前的帖子一样 OPENAI_API_KEY您不应认为导出后所有身份验证问题都已解决。这可能会有所不同，具体取决于组织策略、帐户权限、模型访问权限以及 Codex 的设置方式。

使用环境变量时，不要将实际密钥直接留在帖子或配置文件中。

export OPENAI_API_KEY="****"

在PowerShell中，你可以这样设置：

$env:OPENAI_API_KEY = "****"

基本用法

最基本的是交互式执行。

codex

从项目文件夹运行时，Codex 根据当前目录中的文件进行工作。

cd my-project
codex

安装和身份验证完成后，首先通过简单的请求检查操作。

이 프로젝트 구조를 요약해줘.

从面向读取的请求开始比立即修改文件更安全。

故障案例及解决方案

案例1。 codex: command not found什么时候出来

安装已完成，但终端中可能会出现此消息。

codex: command not found

首先，检查可执行文件的安装位置。

npm config get prefix
which codex

我全局安装了npm。 which codex如果为空，则 npm 全局 bin 路径很可能不在您的 PATH 中。

npm bin -g

还要检查您正在使用哪个外壳。

echo $SHELL

如果你使用zsh ~/.zshrc，如果你使用 bash ~/.bashrc 或者 ~/.bash_profile 查看您的路径设置。在使用 nvm 的环境中，更改 Node 版本后全局包可能会消失，因此使用当前 Node 版本重新安装也是一种选择。

npm install -g @openai/codex

情况2. 与Homebrew一起安装时，但命令引导不同

一些文章提供如下指导。

brew install codex

然而，根据官方自述文件，安装说明是：

brew install --cask codex

自制啤酒配方和木桶有不同的安装对象和管理方法。如果安装失败，首先检查官方README中的最新命令，如果有已经安装错误的包，请清理并重新安装。

brew list | grep -i codex
brew uninstall codex
brew install --cask codex

取决于环境 brew uninstall codex可能无法找到该项目。在这种情况下，实际安装的项目名称是 brew list --cask用 确认。

brew list --cask | grep -i codex

情况3、登录后由于权限或计划问题无法使用

Codex CLI 不是一个简单的安装工具；它与帐户权限相关。如果登录后仍无法使用 ChatGPT，请先检查以下内容。

• 您的 ChatGPT 帐户正确吗？
• 您的个人帐户和工作/学校工作空间是否混合在一起？
• 该计划是否被授权使用 Codex？
• 如果使用API Key方式，项目/组织/付款设置是否正确？

这种情况下，与其盲目重装，不如先注销/重新登录、切换账户、检查权限。这可能会令人困惑，尤其是当您在同一台计算机上有多个 OpenAI 帐户时。

案例4.企业网络中重复出现WebSocket重连消息

GitHub 问题报告了 Codex CLI 尝试 WebSocket 连接并在超时或策略终止后回退到 HTTPS 的情况。用户 Reconnecting..., Request timed out 您将看到相同的消息。

首先，尝试在不同的网络上运行相同的命令。

codex

在具有企业 VPN、代理、安全网关和 SSL 检查的环境中，WebSocket 可能会被阻止。官方表示，这并不是一个在所有环境下都有相同解决方案的问题，因此在这种情况下，按以下顺序检查会更安全：

1. 将 Codex CLI 更新到最新版本
2. 检查它是否在关闭公司 VPN 或在其他网络上重现
3. 在代理/防火墙中 chatgpt.com 并检查 OpenAI 相关连接是否被阻止
4. 如果问题仍然存在，请检查 GitHub Issue 是否有相同版本的案例。

如果是npm安装，则更新如下。

npm install -g @openai/codex@latest
codex --version

案例 5. 当环境变量在 Codex 中不可见时

在某些情况下，我觉得 Codex 在执行命令时没有完全捕获用户的终端环境。例如，在终端中它看起来像 SENTRY_API_TOKEN, OPENAI_API_KEY 相同的值在Codex执行环境中不可见，等等。

首先检查常规航站楼。

printenv OPENAI_API_KEY

接下来，检查 Codex 中执行的命令是否看到相同的环境。不要按原样打印敏感信息；只检查是否存在。

printenv OPENAI_API_KEY >/dev/null && echo "set" || echo "missing"

解决方案因环境而异。最安全的方向是显式设置项目所需的环境变量，以及秘密值 .env没有上传到Git。您应该避免在 Codex 配置文件或项目文档中写入实际的密钥。

案例6. 助手工具因macOS安全策略被屏蔽

macOS 上的 GitHub 问题 rg 还报告了同一个辅助可执行文件被安全策略阻止的情况。虽然这看起来像是 Codex 自己安装的问题，但实际上可能是由 macOS Gatekeeper、隔离属性或安全设置引起的。

首先，检查 Codex 版本和诊断信息。

codex --version
codex doctor

codex doctor如果版本可用，请检查诊断结果以查看哪个可执行文件被阻止。与其盲目扩大权限，不如先检查更新到最新版本后是否再次出现同样的问题。

npm install -g @openai/codex@latest

最佳实践

第一次使用 Codex CLI 时，最好先专注于阅读和解释，而不是依赖自动纠正。

이 저장소의 구조를 설명해줘.
테스트 실행 방법을 찾아줘.
이 에러 로그의 원인을 후보별로 정리해줘.

请求修改文件时，请先确保您的 Git 状态为 clean。

git status

修改后，不要只依赖Codex中的解释，而要自己测试一下。

npm test
npm run build

在公司代码或敏感项目中使用时，还应该检查安全策略。我们建议您避免将 API 密钥、客户数据、操作密码和内部令牌直接粘贴到 Codex 提示符或配置文件中。

常见错误

仅通过查看 Node 版本来确定安装问题

当前的 npm 包标准是 node >=16是的。与 Node 版本相比，问题更多是由 nvm 转换导致的 npm 全局安装路径、PATH 和全局包位置的差异引起的。

只需按照旧的安装命令即可

Codex CLI 是一个快速变化的工具。在博客文章中的安装说明之前，您应该查看官方 README 和 GitHub Release 以获取最新信息。

了解 API Key 方法和 ChatGPT 登录方法的混合

官方 README 建议登录您的 ChatGPT 帐户。 API Key方法也是可以的，但可能需要单独的设置和权限确认。将身份验证问题误认为是安装问题可能会花费您大量时间。

Codex不验证修改结果

Codex 允许代码修改，但修改的结果可能并不总是符合项目的意图。测试、构建和差异检查必须由用户完成。

结论

安装 Codex CLI 本身并不困难。对于 macOS 和 Linux，您可以使用官方安装脚本、npm 或 Homebrew cask，对于 Windows，您可以使用 PowerShell 安装脚本。

但真正占用时间的部分并不是安装命令，而是PATH、认证、账户权限、网络、终端环境的差异。因此 Codex CLI 文章不仅仅是一个简单的安装过程。 command not found，一起看失败案例要实用得多，比如登录权限问题、WebSocket/代理问题、环境变量问题。

如果您是第一次安装，请按照以下步骤操作。

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

如果您已经组织好 npm 环境，那么以下方法就足够了：

npm install -g @openai/codex@latest
codex --version
codex

参考资料

• OpenAI Codex GitHub README: https://github.com/openai/codex
• Codex CLI npm 包：https://www.npmjs.com/package/@openai/codex
• Codex 最新 GitHub 版本：https://github.com/openai/codex/releases/latest
• OpenAI Codex认证文档：https://developers.openai.com/codex/auth
• OpenAI Codex CLI 功能文档：https://developers.openai.com/codex/cli/features
• OpenAI Codex配置文档：https://developers.openai.com/codex/config-basic
• GitHub 问题：WebSocket 超时/回退示例：https://github.com/openai/codex/issues/28503
• GitHub 问题：在 macOS 上 rg 阻止案例：https://github.com/openai/codex/issues/28190
• GitHub问题：环境变量继承相关案例：https://github.com/openai/codex/issues/3064

相关文章

• Claude Code 与 OpenAI Codex：AI 编程代理计费为什么可能正在分化？: https://daily-it.duckdns.org/zh/2026/06/19/ai-coding-agent-pricing-claude-code-openai-codex-zh/