Codex macOS / Linux 安装与更新：install.sh、npm、Homebrew 排查

先给结论：选一种主要安装来源，并一直用它更新

路线	适合谁	安装	更新
官方独立安装器	想按当前默认路线安装，不依赖 npm	`install.sh`	重新运行同一脚本
npm	已经用 npm 管理全局 CLI	`npm install -g @openai/codex`	重新运行同一命令
Homebrew	习惯用 brew cask 管理 macOS/Linux 工具	`brew install --cask codex`	`brew upgrade --cask codex`

不要同一天先跑 install.sh、再 npm、最后又 brew。多种来源可能都成功安装，但 shell 只执行 PATH 中最先命中的那一份，最终表现就是“更新成功、版本没变”。

路线一：官方独立 install.sh

OpenAI 当前 Codex CLI 页面把独立安装器列为 macOS / Linux 默认安装路线：

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

更新时重新运行同一命令。执行前确认域名是 chatgpt.com，并理解管道脚本会直接运行下载内容；企业设备应按组织的软件安装与审计策略处理，不要改用网盘或陌生镜像的所谓“免配置版本”。

官方来源：OpenAI Codex CLI（当前会重定向到 ChatGPT Learn）。

路线二：npm 全局安装

npm install -g @openai/codex

OpenAI 当前页面把同一命令同时列为 npm 安装和更新方式。此路线需要当前 shell 中的 Node.js 与 npm 正常，而且 npm 全局目录已经在 PATH 中。

如果出现 EACCES、全局目录不可写或不同 Node 版本下找不到包，不要立刻全盘 chmod -R 777。先检查 npm prefix、实际用户和 Node 版本来源；也可以选择独立安装器或 Homebrew，避免把一个包管理器权限问题扩大成系统权限问题。

路线三：Homebrew cask

brew install --cask codex
brew upgrade --cask codex

第一行用于安装，第二行用于更新。若 brew 显示已是当前版本，但 codex --version 仍旧，优先检查终端实际运行的是否是 Homebrew 那一份，而不是继续重复 brew upgrade。

安装或更新后，用三条命令确认结果

command -v codex
type -a codex
codex --version

command -v 显示当前 shell 会首先执行的路径；
type -a 尽量列出 PATH 中发现的所有同名命令；
codex --version 显示实际运行版本。

再打开一个全新的终端窗口复测。旧 shell 可能缓存过命令位置或还没读取更新后的启动文件；只有新终端也指向同一路径，才能证明当前 PATH 已经稳定。

codex: command not found 怎么排查

现象	更可能的原因	第一步
安装命令刚结束就找不到	新路径尚未进入当前 shell	新开终端，再运行 `command -v codex`
只有某个终端找不到	zsh、bash、fish 启动文件不同	确认当前 shell 与实际读取的配置文件
Local 能用，SSH / 容器不能用	不是同一 host 或用户	在实际运行环境单独安装并核对 PATH
IDE 终端找不到	IDE 启动时继承了旧环境	完全重启 IDE，并确认 Local / Remote 侧
`permission denied`	文件权限、挂载或 sandbox，不是命令不存在	进入权限专题
`exec format error`	二进制架构或平台不匹配	核对 `uname -m`、路径和安装来源

更新后仍是旧版本：清理“多份安装”而不是继续重装

保存 type -a codex 的全部路径。
确认每一份分别来自 install.sh、npm、Homebrew，还是旧的手动下载。
选择一个主要来源，之后只用该来源更新。
按原包管理器正常移除不再使用的副本，不要直接删除不认识的系统目录。
新开终端，再核对路径和版本。

自动更新、IDE 内置版本和系统终端也可能不是同一可执行文件。ChatGPT 桌面应用中的 Codex 与独立 CLI 属于不同入口；更新桌面应用不能证明 shell 中的 CLI 已更新，反过来也一样。

权限、架构与安全边界

npm EACCES：修复 npm 全局目录或 Node 管理方式，不对系统目录递归开放权限。
Apple Silicon / Intel：优先让官方安装器或包管理器选择平台构建，不从陌生镜像手动换二进制。
Linux：确认真实发行版、CPU 架构、shell 和用户；容器内安装不会自动出现在宿主机。
企业设备：软件安装、代理、证书和执行权限可能受组织策略控制，应保留完整错误交给管理员。
配置目录：正常更新不需要删除整个 ~/.codex，也不要公开 auth.json、Cookie、Session 或项目数据。

若 CLI 已能运行，但出现 failed to load configuration，进入config.toml 专题；只有安装阶段找不到命令时才继续处理 PATH。

安装完成后怎么登录，是否需要 API 余额

在项目目录运行：

codex

首次运行时，OpenAI 当前页面提示选择 Sign in with ChatGPT 或其他可用登录方式。ChatGPT 套餐中的 Codex 用量与 OpenAI Platform API 账单分开；不要因为 CLI 已安装就默认必须购买 API 余额，也不要因为有 Plus / Pro 就认为 API Key 调用免费。

登录出现浏览器回调、401、403 或组织策略错误，进入Codex 登录专题；套餐、Credits 与 API 区别见Codex 套餐说明。

Codex macOS / Linux 安装更新常见问题

Codex CLI 在 macOS 和 Linux 上怎么安装？

可使用官方 install.sh、npm 或 Homebrew。选择一种主要来源，并用同一来源更新。

Codex CLI 怎么更新到当前版本？

独立安装器重新运行脚本；npm 重新运行全局安装命令；Homebrew 使用 brew upgrade --cask codex。之后核对实际路径和版本。

安装后提示 codex: command not found 怎么办？

新开终端，用 command -v codex 检查 PATH，并确认安装发生在当前用户和当前 host。

Codex 更新后为什么还是旧版本？

通常是 PATH 先命中了另一份旧安装。用 type -a codex 列出同名命令，再统一安装来源。

安装 Codex 必须先安装 Node.js 吗？

只有 npm 路线依赖 Node.js 与 npm；独立安装器和 Homebrew 是其他路线。

macOS 应该用 install.sh、npm 还是 Homebrew？

按自己的软件管理方式选择即可。避免混装比选择哪一个更重要。

Apple Silicon 和 Intel Mac 可以使用同一个安装命令吗？

优先使用官方安装器或包管理器自动选择平台构建；架构错误时核对 uname -m 和实际路径。

npm 安装 Codex 出现 EACCES 权限错误怎么办？

检查 npm 全局目录与当前用户权限，或换用独立安装器/Homebrew；不要全盘 chmod 或默认 sudo。

更新 Codex 会删除 config.toml 和聊天吗？

正常更新 CLI 不应要求删除整个 ~/.codex。可以备份自己写的配置，但不要公开认证材料。

安装 Codex CLI 后还要购买 API 余额吗？

取决于登录方式。ChatGPT 登录使用套餐侧 Codex 用量，API Key 使用 Platform API 账单，两者分开。

来源与利益关系说明

本文由 Hi Codex 服务团队根据 OpenAI 当前 Codex CLI、认证、配置与 Changelog 文档整理。团队提供独立人工充值协助，与 ChatGPT / Codex 套餐主题存在商业利益关系；与 OpenAI 不存在隶属、代理或官方授权关系。

安装命令、客户端版本和支持平台可能变化，请以 OpenAI 当前页面为准。本文不提供陌生镜像、共享凭证、第三方 API 中转、地区绕过、全盘 chmod 或长期 Full Access 方案。