在 Ubuntu 20.04 上装 OpenAI Codex CLI最容易卡住的地方通常出现在你敲完npm install -g openai/codex之后此时终端甩出一屏红字而不是跑起来的那一刻。我前后在四台 20.04 的机器上装过这个工具——有云主机、有本地工作站、还有一个 WSL 环境踩的坑几乎不重样有的卡在 Node 版本有的卡在 global 目录权限有的卡在依赖包下载到一半超时。所以这篇不讲复制粘贴一行命令就完事的理想流程而是把官方安装和走国内镜像源安装这两条路各自的完整链路、判定标准和排错方法摊开讲清楚。Codex CLI 是一个跑在终端里的 AI 编程助手能读你当前仓库的代码、执行命令、改文件适合已经习惯命令行工作流的开发者在本地项目里做代码理解、批量重构和脚本编写。下面这一套流程你在任何一台干净的 Ubuntu 20.04 上照着走基本能一次到位。1. Codex CLI 装在 Ubuntu 20.04 上的三个隐性前提1.1 它不是一个自包含的二进制而是一个需要运行时的 npm 包很多人对 CLI 工具的默认印象是下载一个可执行文件chmod x就能用。Codex CLI 的早期形态不是这样它是通过 npm 全局安装的包装完之后在PATH里注册一个codex命令。这意味着你的机器上必须先有一套能正常工作的 Node.js 运行时和 npm 包管理器而且版本不能太低。这个设计带来的连锁反应是安装失败的原因绝大多数不在 Codex CLI 本身而在它下面那层运行时。我在一台只有系统自带 apt 包的 20.04 上试过node -v打出来是v10.19.0这是 Ubuntu 20.04 官方源里锁死的版本看着能用实际上现代 npm 包的一堆语法和 API 在这个版本上根本走不通。你如果直接在这个环境下装报错信息往往是SyntaxError: Unexpected token或者engine unsupported之类跟 Codex 一点关系都没有。所以正确的思考顺序应该是先确认运行时版本达标再谈装包。这也是为什么我把环境体检放在整篇的最前面——省下的时间比你想象的多。1.2 Node 版本这道坎为什么 20.04 默认版本一定不够Codex CLI 对 Node 的要求随着版本迭代抬过几次。我实际接触到的情况是较新的发行版普遍要求 Node 22 及以上部分中间版本要求 Node 18 以上。不管具体数字怎么变有一点是确定的Ubuntu 20.04 apt 源里的 Node 永远满足不了要求因为 20.04 已经停止标准支持周期它的软件源里不会再有新版本的 Node。判断方法很简单装之前先跑node -v npm -v which node如果node -v输出小于 v18那就先把运行时换掉别急着装 Codex。which node这一条也别省——有些机器上同时存在/usr/bin/node和/usr/local/bin/node你以为升级了实际跑的还是老的那一个这种看着升了其实没升的情况我遇到不止一次。1.3 架构与系统库x86_64 之外要多留个心眼Ubuntu 20.04 上跑 Codexx86_64 是最省心的组合。如果你用的是 ARM 机器比如某些云厂商的 ARM 实例或者树莓派上的 64 位系统需要额外确认两件事一是 Node 的 ARM64 构建是否完整安装node -p process.arch应该输出arm64二是 npm 包内如果有预编译的原生模块是否提供了对应的 ARM 制品。我碰到过一次在 ARM 实例上装到一半报No matching binding的情况根因就是某个间接依赖只发布了 x64 的二进制。另外Ubuntu 20.04 的 glibc 版本是 2.31这个版本对绝大多数现代工具是够用的。真正需要注意的是系统的构建工具链是否齐全——有些 npm 包在没有预编译包时会走源码编译这时候缺build-essential和python3就会直接失败。保险起见动手前先补上sudo apt update sudo apt install -y build-essential python3 curl git这几样东西加起来占用不大但能挡掉一大票莫名其妙的编译错误。2. 环境体检与 Node 运行时的三条铺装路线2.1 三条路线怎么选apt 直装、官方二进制源、版本管理器在 Ubuntu 20.04 上搞到一个够新的 Node常见有三条路各有明确的适用场景我把它们的取舍列在下面这张表里路线典型操作优点主要代价适合谁apt 直装apt install nodejs npm一条命令系统统一管理版本停留在 10.x完全不达标不推荐用于本场景官方二进制源添加发行方提供的源后 apt 安装版本较新apt 统一升级需要额外配置源与签名希望系统级统一管理的人版本管理器用 nvm 之类工具安装可多版本共存、随时切换需要处理 shell 初始化需要多项目多版本的人我自己在服务器上倾向第二条因为在自动化脚本里它最稳定不需要处理 shell 的source顺序问题在个人开发机上倾向第三条因为随时能切版本。你在纯本地开发、只跑一个项目的话两条都行看你习惯。关键在于无论走哪条装完之后一定要用which node确认生效路径别让老的/usr/bin/node抢在前面。2.2 nvm 安装时把下载地址切到镜像省掉一半等待用 nvm 的好处是版本隔离干净坏处是它默认从境外节点拉 Node 二进制包在网络抖动的时候经常下到一半断掉然后你重来一遍。nvm 支持通过环境变量指定下载源这个能力很多人不知道。标准做法是先装 nvm然后在~/.bashrc里加两个变量把 Node 二进制和 npm 包的分发地址都指向国内镜像export NVM_NODEJS_ORG_MIRRORhttps://npmmirror.com/mirrors/node export NVM_NPM_MIRRORhttps://registry.npmmirror.com加完之后source ~/.bashrc再执行安装nvm install 22 nvm use 22 nvm alias default 22nvm alias default 22这一步别漏否则新开一个终端窗口又回到没有 Node 的状态你会以为是装坏了。我第一回就漏了这一步折腾了半小时才发现是 shell 会话问题。nvm install 22执行完用node -v和npm -v双确认输出应该是 v22.x.x 和 10.x.x 这一档。到这里运行时就算铺好了。2.3 不用版本管理器的话二进制解压法也很干净如果你不想引入 nvm还有一种很朴素但可靠性极高的办法直接从镜像站下载 Node 的官方二进制压缩包解压到/usr/local然后建软链接。整个过程不碰系统包管理器卸载的时候删目录就行残留极少。大致思路是下载node-v22.x.x-linux-x64.tar.xz解压到/usr/local/lib/nodejs/然后把bin/node、bin/npm、bin/npx三个可执行文件软链到/usr/local/bin/。因为/usr/local/bin在 PATH 里的优先级通常高于/usr/bin所以老的 apt 版 Node 不会被误调用。这条路的好处是可控性极强坏处是升级要手动重来一遍。如果你追求装一次就不管那还是用版本管理器更省事。3. 官方源安装的完整链路与三道验证3.1 全局安装到底做了什么运行时准备好之后官方安装就是一条命令npm install -g openai/codex但我想让你理解这条命令背后的动作因为理解了它后面排错才有方向。-g表示全局安装npm 会把包下载下来解压到全局的node_modules目录然后在全局bin目录里创建一个名为codex的可执行入口Windows 上是.cmdLinux 上是一个软链接或 shell 包装脚本。全局目录的位置由npm prefix -g决定。用 nvm 装的 Node全局目录在~/.nvm/versions/node/v22.x.x/下面权限天然是当前用户不会出现权限报错。用 apt 装的 Node全局目录是/usr/lib/node_modules普通用户没有写权限这就是下一节要讲的EACCES的来源。安装过程中 npm 会做几件事解析依赖树、下载各个包、校验完整性、执行包定义的安装钩子。整个过程耗时取决于网络和你本地缓存的状态干净环境下通常几十秒到几分钟。如果卡在某一步超过两三分钟没动静基本可以判定是下载环节出问题了这时候就该考虑第四节讲的镜像方案。3.2 装完不等于装好三条验证缺一不可很多人npm install结束看到没有红字就以为成功了然后直接敲codex发现 command not found。所以我习惯装完立刻做三件事。第一条确认命令是否在 PATH 里which codex输出应该是一个具体路径。如果什么都没输出说明全局 bin 目录不在 PATH 中需要手动加。用 nvm 的话通常不会有这个问题用二进制解压法或者自定义 prefix 的话就要检查了。第二条确认版本能正常打出来codex --version这一条比which更有价值因为它会真正加载可执行文件。如果文件存在但依赖缺失或者架构不匹配这里就会崩。我碰到过一次which codex有输出、codex --version报cannot execute binary file的情况最后查出来是下载的制品架构不对重装解决。第三条看帮助信息是否完整codex --help帮助能正常输出说明 CLI 的核心模块加载链路是通的可以进入下一阶段。这三条做完安装环节才算真正结束。3.3 EACCES 权限报错的根因与两种收敛方案EACCES: permission denied是在 Ubuntu 上用 apt 版 Node 装全局包时最常见的报错。它的成因很单纯npm 想往/usr/lib/node_modules写文件但这个目录属于 root你的当前用户没有写权限。网上流传最广的解法是sudo npm install -g我强烈不建议。理由是用 sudo 装包会让包文件的所有者变成 root后续升级、卸载、以及 npm 缓存的管理都会出现权限错乱越用越乱。而且工具本身在运行时也会往用户目录写配置sudo 装完之后普通用户跑起来还是可能出问题。我推荐两条收敛方案。第一条是改全局 prefix 到用户目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc改完之后所有全局包都装在自己家目录下永远不会再有权限问题卸载就是删目录。第二条更彻底就是前面说的换成 nvm 管理 Node从根上把全局目录放进用户空间。两条方案的效果一样选哪条看你机器上还有没有别的工具依赖系统级 Node。有的话用第一条没有的话第二条更省心。4. 走国内镜像源安装配置范围与回滚策略4.1 npm registry 镜像能解决什么、不能解决什么先把边界说清楚省得白折腾。把 npm 的 registry 指向国内镜像解决的是包元数据查询和 tarball 下载慢这个问题。它不会改变 Node 运行时本身的版本也不会影响包安装完之后运行时的任何行为——因为镜像站同步的是上游 registry 的同一份制品包的完整性校验值是对得上的。不能解决的部分也很明确如果某个包在镜像站上还没同步到最新版本这种情况在新版本刚发布时偶有发生你拉到的可能是旧版本codex --version打出来的号会让你以为装了个假包。所以镜像方案的一个必要配套动作是装完之后用npm view openai/codex version和codex --version对一下两个数字应该一致。配置方式有三种粒度按影响范围从小到大排粒度命令写法影响范围适用场景单次命令npm install -g openai/codex --registry...仅本次临时装一次不想动全局配置项目级项目根目录.npmrc写 registry仅该项目CI 环境、团队统一全局npm config set registry ...当前用户所有 npm 操作长期在国内网络环境工作4.2 单次命令带镜像最不影响其他配置的写法如果你只是想快一点把 Codex 装上不想改任何持久配置直接在安装命令后面挂--registry参数就行npm install -g openai/codex --registryhttps://registry.npmmirror.com这个写法的好处是零副作用你的~/.npmrc一个字符都没变其他项目的依赖解析行为完全不受影响。坏处是每次装都得记得带上这个参数。我在给别人的机器做一次性安装时基本都用这个写法装完就走不留下任何配置痕迹。如果那台机器以后要长期用我才会建议改成全局配置。需要注意的是镜像地址的写法。带不带结尾斜杠、用 http 还是 https都会影响 npm 的解析尽量用标准形式https://registry.npmmirror.com别自己拼。4.3 全局切换镜像后的验证、异常处理与回滚如果你决定长期使用镜像配置命令是npm config set registry https://registry.npmmirror.com npm config get registry第二条命令用来确认写入生效。之后正常执行npm install -g openai/codex即可。这里有个细节值得提全局切换 registry 之后npm的缓存目录里会同时存在官方源和镜像源的包缓存。大多数情况下 npm 是靠完整性哈希来区分不会有问题但如果你之前装过某个包的旧版本切换源后有时会拿到缓存里的旧制品表现为明明镜像上有新版装出来还是老版。这时候清一下缓存再装npm cache verify npm cache clean --forcenpm cache verify是温和做法它只做校验和清理无效条目正常情况下用这个就够了。--force是全清会把所有缓存都丢掉下次装任何包都得重新下载非必要不用。回滚很简单npm config delete registry执行完再npm config get registry应该回落到官方默认地址。这一步我建议你装在装完之后就记下来因为有些企业内部网络环境对特定 registry 有额外要求切换久了你自己都会忘。5. 从认证到第一次真正跑通一次任务5.1 登录方式的选择与凭据存放位置装好之后第一次执行codex它会引导你完成认证。目前主要有两条路径一是通过账号授权走浏览器登录流程二是在命令行直接以 API key 方式登录。对于无图形界面的服务器浏览器流程会给你一个链接让你在另一台有浏览器的机器上打开并完成授权然后把回调结果贴回来。这个流程在纯终端环境下能走通但操作起来比较绕。我的经验是在有桌面的机器上用浏览器授权在服务器上直接用 key 登录各自用最顺手的方式。以 key 方式登录的一般形式是codex login --api-key 你的密钥密钥不应该写进 shell 历史。两个办法避免一是在命令前加一个空格需要你的 shell 配置了HISTCONTROLignorespace二是干脆用环境变量的方式让 CLI 自己去读。配置文件默认放在~/.codex/目录下这个目录的权限建议设成700chmod 700 ~/.codex这一步看着多余但凭据文件放在一个所有用户都可读的目录里在任何多人共用的机器上都是隐患。5.2 config.toml 里值得动手改的几个字段Codex 的主配置文件是~/.codex/config.toml。默认生成的配置能用但有几个字段值得根据你的使用习惯调一下。我列的是通用思路具体字段名以你装的版本codex --help和实际生成的配置文件为准版本之间会有差异。第一个是模型选择。不同模型的取舍在于速度和能力的平衡日常的代码解释、小范围改动用轻量一点的模型响应更快涉及跨文件重构、复杂逻辑推理换能力更强的模型更划算。这个没有标准答案看你当天在干什么。第二个是审批策略。这个字段决定 CLI 在执行命令前要不要停下来问你。选项大致分布在每步都问到完全放行之间。我的建议是第一次跑一定选最保守的那一档先用一个小仓库试看清楚它到底会执行哪些命令、改哪些文件心里有数之后再逐步放宽。第三个是沙箱模式。它控制 CLI 能碰到的文件范围从只读、到只能改当前工作目录、到完全放开是一个明显的能力阶梯。理解这个阶梯的最简单类比是只读模式像给你看但不给你笔工作区模式像给你笔但只准在这张纸上画完全放开就是整个桌面随你动。默认建议停在工作区模式绝大多数日常开发够用风险也可控。改配置的时候有个坑要提醒config.toml是 TOML 格式字符串要加引号布尔值是小写true/false写错了 CLI 启动时会直接报解析错误。我见过有人把布尔值写成True结果排查了半天以为是安装问题。改完统一用codex --help试一下能正常输出就说明配置解析通过了。5.3 第一次任务的推荐姿势小仓库、明确指令、盯住输出装完之后别急着在主力项目上跑。找一个几百行代码的小仓库或者干脆新建一个空目录放两三个文件用它来建立对工具行为的基本认知。第一次可以试试这类明确边界的任务让它在当前目录下读某个文件并解释逻辑或者让它写一个独立的脚本文件。这类任务的特点是输入明确、输出可验证、影响范围局限跑完你能立刻判断它做的对不对。观察的重点有三个它读了哪些文件说明它对上下文的理解范围、它执行了哪些命令说明它的动作边界、它改了哪些文件说明它的写权限实际用到了哪里。这三点摸清楚之后你对这个工具的能力和风险就有了直观认识再放到真实项目里就有底了。我在第一次用的时候犯过一个错没注意当前目录是家目录结果它扫了一大堆无关文件上下文被塞满输出质量很差。后来养成习惯跑之前先pwd看一眼确认在项目根目录下再启动。这个小动作能省掉很多困惑。6. 报错对照表与干净卸载重装的完整流程6.1 高频报错的现象、根因与处理动作下面这张表是我实际遇到和帮别人处理过的几类问题按出现频率排的现象根因判断处理动作codex: command not found全局 bin 不在 PATHnpm prefix -g查路径把它加进 PATH安装时报engine unsupportedNode 版本低于要求升级 Node 到 22 或以上重新确认which nodeEACCES: permission denied全局目录属 root改 prefix 到用户目录或用 nvm 重装下载卡住后超时registry 拉取不稳定加--registry参数走镜像源codex --version报二进制格式错误制品架构不匹配确认process.arch重装对应架构启动时报 TOML 解析错误配置文件语法问题检查引号与布尔值大小写或先备份后删除配置重生成装完版本号比预期旧缓存命中旧制品npm cache verify后重装用这张表的时候有个心法先分清是装的时候报错还是装完了跑不起来。前者九成在运行时、权限、网络这三件事上后者九成在 PATH、配置语法、凭据这三件事上。把问题归到这两大类里排查范围立刻缩小一半。还有一类比较隐蔽的情况命令能跑但行为诡异比如启动特别慢、或者读不到项目文件。这种情况往往不是安装问题而是工作目录不对或者配置文件里某个路径写成了绝对路径导致限制生效。先pwd确认位置再看配置里有没有硬编码路径。6.2 彻底卸载删干净才能装得干净排查到最后如果决定重装那就得卸干净。很多人只跑一句npm uninstall -g openai/codex然后重装发现还是老样子因为残留还在。完整的清理分三层。第一层是包本身npm uninstall -g openai/codex第二层是配置和凭据目录这个目录不会随卸载删除ls -la ~/.codex确认里面没有你还需要的内容之后再决定是否移除。我的习惯是先重命名备份而不是直接删mv ~/.codex ~/.codex.bak.$(date %s)这样万一重装后发现问题出在配置上还能把老配置拿出来对比。直接rm -rf的人出问题时就只能靠记忆重建。第三层是 npm 缓存。这一步不是必需的但如果怀疑是缓存里的坏制品导致的怪问题就做一次npm cache verify三层清理完which codex应该空空如也这时候再按第三节的流程重装环境就是干净的。6.3 版本升级与回退怎么锁定一个能用的版本工具迭代快的时候最新版不一定是最稳版。如果某个版本在你的项目上跑得好好的建议锁住它别每次重装都拉最新。锁定版本的写法是在包名后加版本号npm install -g openai/codex具体版本号查可用版本npm view openai/codex versions --json这个命令会输出一个数组从里面挑一个你验证过能用的号。用镜像源的时候如果发现版本列表比官方少说明镜像同步有延迟换个时间再查或者临时用官方地址查一次版本列表、再用镜像地址装指定版本——这个组合我经常用查版本走一个源、装包走另一个源两边的好处都拿到了。升级的流程和装新版本一样直接npm install -g openai/codex新版本号覆盖即可不用先卸载。覆盖安装之后记得重新跑codex --version确认生效因为有缓存的情况下偶尔会看到旧号这时候清缓存再装一次就好。回退也是同一条命令把版本号换成旧的就完事。真正需要小心的是配置文件格式跨大版本升级时字段名可能变旧配置在新版本上可能报解析错误。所以升级前把~/.codex/config.toml备份一份是我现在的固定动作花三秒钟能省掉半小时。最后分享一个我用了很久的小习惯在一台机器上第一次装好并验证通过之后把整个流程——包括 Node 版本、安装命令、镜像参数、配置改动——记成一个setup-notes.md放在家目录里。半年后换机器或者重装系统照着抄一遍十分钟搞定不用再从头回忆当初踩过哪些坑。这个习惯的价值只有在你第二次重装同一套环境的时候才真正体现出来。 
长河君 · 2026/11/4 14:16:17 · 阅读 1.2k Ubuntu 20.04 安装 Codex CLI：Node、镜像源与排错指南
在 Ubuntu 20.04 上装 OpenAI Codex CLI最容易卡住的地方通常出现在你敲完npm install -g openai/codex之后此时终端甩出一屏红字而不是跑起来的那一刻。我前后在四台 20.04 的机器上装过这个工具——有云主机、有本地工作站、还有一个 WSL 环境踩的坑几乎不重样有的卡在 Node 版本有的卡在 global 目录权限有的卡在依赖包下载到一半超时。所以这篇不讲复制粘贴一行命令就完事的理想流程而是把官方安装和走国内镜像源安装这两条路各自的完整链路、判定标准和排错方法摊开讲清楚。Codex CLI 是一个跑在终端里的 AI 编程助手能读你当前仓库的代码、执行命令、改文件适合已经习惯命令行工作流的开发者在本地项目里做代码理解、批量重构和脚本编写。下面这一套流程你在任何一台干净的 Ubuntu 20.04 上照着走基本能一次到位。1. Codex CLI 装在 Ubuntu 20.04 上的三个隐性前提1.1 它不是一个自包含的二进制而是一个需要运行时的 npm 包很多人对 CLI 工具的默认印象是下载一个可执行文件chmod x就能用。Codex CLI 的早期形态不是这样它是通过 npm 全局安装的包装完之后在PATH里注册一个codex命令。这意味着你的机器上必须先有一套能正常工作的 Node.js 运行时和 npm 包管理器而且版本不能太低。这个设计带来的连锁反应是安装失败的原因绝大多数不在 Codex CLI 本身而在它下面那层运行时。我在一台只有系统自带 apt 包的 20.04 上试过node -v打出来是v10.19.0这是 Ubuntu 20.04 官方源里锁死的版本看着能用实际上现代 npm 包的一堆语法和 API 在这个版本上根本走不通。你如果直接在这个环境下装报错信息往往是SyntaxError: Unexpected token或者engine unsupported之类跟 Codex 一点关系都没有。所以正确的思考顺序应该是先确认运行时版本达标再谈装包。这也是为什么我把环境体检放在整篇的最前面——省下的时间比你想象的多。1.2 Node 版本这道坎为什么 20.04 默认版本一定不够Codex CLI 对 Node 的要求随着版本迭代抬过几次。我实际接触到的情况是较新的发行版普遍要求 Node 22 及以上部分中间版本要求 Node 18 以上。不管具体数字怎么变有一点是确定的Ubuntu 20.04 apt 源里的 Node 永远满足不了要求因为 20.04 已经停止标准支持周期它的软件源里不会再有新版本的 Node。判断方法很简单装之前先跑node -v npm -v which node如果node -v输出小于 v18那就先把运行时换掉别急着装 Codex。which node这一条也别省——有些机器上同时存在/usr/bin/node和/usr/local/bin/node你以为升级了实际跑的还是老的那一个这种看着升了其实没升的情况我遇到不止一次。1.3 架构与系统库x86_64 之外要多留个心眼Ubuntu 20.04 上跑 Codexx86_64 是最省心的组合。如果你用的是 ARM 机器比如某些云厂商的 ARM 实例或者树莓派上的 64 位系统需要额外确认两件事一是 Node 的 ARM64 构建是否完整安装node -p process.arch应该输出arm64二是 npm 包内如果有预编译的原生模块是否提供了对应的 ARM 制品。我碰到过一次在 ARM 实例上装到一半报No matching binding的情况根因就是某个间接依赖只发布了 x64 的二进制。另外Ubuntu 20.04 的 glibc 版本是 2.31这个版本对绝大多数现代工具是够用的。真正需要注意的是系统的构建工具链是否齐全——有些 npm 包在没有预编译包时会走源码编译这时候缺build-essential和python3就会直接失败。保险起见动手前先补上sudo apt update sudo apt install -y build-essential python3 curl git这几样东西加起来占用不大但能挡掉一大票莫名其妙的编译错误。2. 环境体检与 Node 运行时的三条铺装路线2.1 三条路线怎么选apt 直装、官方二进制源、版本管理器在 Ubuntu 20.04 上搞到一个够新的 Node常见有三条路各有明确的适用场景我把它们的取舍列在下面这张表里路线典型操作优点主要代价适合谁apt 直装apt install nodejs npm一条命令系统统一管理版本停留在 10.x完全不达标不推荐用于本场景官方二进制源添加发行方提供的源后 apt 安装版本较新apt 统一升级需要额外配置源与签名希望系统级统一管理的人版本管理器用 nvm 之类工具安装可多版本共存、随时切换需要处理 shell 初始化需要多项目多版本的人我自己在服务器上倾向第二条因为在自动化脚本里它最稳定不需要处理 shell 的source顺序问题在个人开发机上倾向第三条因为随时能切版本。你在纯本地开发、只跑一个项目的话两条都行看你习惯。关键在于无论走哪条装完之后一定要用which node确认生效路径别让老的/usr/bin/node抢在前面。2.2 nvm 安装时把下载地址切到镜像省掉一半等待用 nvm 的好处是版本隔离干净坏处是它默认从境外节点拉 Node 二进制包在网络抖动的时候经常下到一半断掉然后你重来一遍。nvm 支持通过环境变量指定下载源这个能力很多人不知道。标准做法是先装 nvm然后在~/.bashrc里加两个变量把 Node 二进制和 npm 包的分发地址都指向国内镜像export NVM_NODEJS_ORG_MIRRORhttps://npmmirror.com/mirrors/node export NVM_NPM_MIRRORhttps://registry.npmmirror.com加完之后source ~/.bashrc再执行安装nvm install 22 nvm use 22 nvm alias default 22nvm alias default 22这一步别漏否则新开一个终端窗口又回到没有 Node 的状态你会以为是装坏了。我第一回就漏了这一步折腾了半小时才发现是 shell 会话问题。nvm install 22执行完用node -v和npm -v双确认输出应该是 v22.x.x 和 10.x.x 这一档。到这里运行时就算铺好了。2.3 不用版本管理器的话二进制解压法也很干净如果你不想引入 nvm还有一种很朴素但可靠性极高的办法直接从镜像站下载 Node 的官方二进制压缩包解压到/usr/local然后建软链接。整个过程不碰系统包管理器卸载的时候删目录就行残留极少。大致思路是下载node-v22.x.x-linux-x64.tar.xz解压到/usr/local/lib/nodejs/然后把bin/node、bin/npm、bin/npx三个可执行文件软链到/usr/local/bin/。因为/usr/local/bin在 PATH 里的优先级通常高于/usr/bin所以老的 apt 版 Node 不会被误调用。这条路的好处是可控性极强坏处是升级要手动重来一遍。如果你追求装一次就不管那还是用版本管理器更省事。3. 官方源安装的完整链路与三道验证3.1 全局安装到底做了什么运行时准备好之后官方安装就是一条命令npm install -g openai/codex但我想让你理解这条命令背后的动作因为理解了它后面排错才有方向。-g表示全局安装npm 会把包下载下来解压到全局的node_modules目录然后在全局bin目录里创建一个名为codex的可执行入口Windows 上是.cmdLinux 上是一个软链接或 shell 包装脚本。全局目录的位置由npm prefix -g决定。用 nvm 装的 Node全局目录在~/.nvm/versions/node/v22.x.x/下面权限天然是当前用户不会出现权限报错。用 apt 装的 Node全局目录是/usr/lib/node_modules普通用户没有写权限这就是下一节要讲的EACCES的来源。安装过程中 npm 会做几件事解析依赖树、下载各个包、校验完整性、执行包定义的安装钩子。整个过程耗时取决于网络和你本地缓存的状态干净环境下通常几十秒到几分钟。如果卡在某一步超过两三分钟没动静基本可以判定是下载环节出问题了这时候就该考虑第四节讲的镜像方案。3.2 装完不等于装好三条验证缺一不可很多人npm install结束看到没有红字就以为成功了然后直接敲codex发现 command not found。所以我习惯装完立刻做三件事。第一条确认命令是否在 PATH 里which codex输出应该是一个具体路径。如果什么都没输出说明全局 bin 目录不在 PATH 中需要手动加。用 nvm 的话通常不会有这个问题用二进制解压法或者自定义 prefix 的话就要检查了。第二条确认版本能正常打出来codex --version这一条比which更有价值因为它会真正加载可执行文件。如果文件存在但依赖缺失或者架构不匹配这里就会崩。我碰到过一次which codex有输出、codex --version报cannot execute binary file的情况最后查出来是下载的制品架构不对重装解决。第三条看帮助信息是否完整codex --help帮助能正常输出说明 CLI 的核心模块加载链路是通的可以进入下一阶段。这三条做完安装环节才算真正结束。3.3 EACCES 权限报错的根因与两种收敛方案EACCES: permission denied是在 Ubuntu 上用 apt 版 Node 装全局包时最常见的报错。它的成因很单纯npm 想往/usr/lib/node_modules写文件但这个目录属于 root你的当前用户没有写权限。网上流传最广的解法是sudo npm install -g我强烈不建议。理由是用 sudo 装包会让包文件的所有者变成 root后续升级、卸载、以及 npm 缓存的管理都会出现权限错乱越用越乱。而且工具本身在运行时也会往用户目录写配置sudo 装完之后普通用户跑起来还是可能出问题。我推荐两条收敛方案。第一条是改全局 prefix 到用户目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc改完之后所有全局包都装在自己家目录下永远不会再有权限问题卸载就是删目录。第二条更彻底就是前面说的换成 nvm 管理 Node从根上把全局目录放进用户空间。两条方案的效果一样选哪条看你机器上还有没有别的工具依赖系统级 Node。有的话用第一条没有的话第二条更省心。4. 走国内镜像源安装配置范围与回滚策略4.1 npm registry 镜像能解决什么、不能解决什么先把边界说清楚省得白折腾。把 npm 的 registry 指向国内镜像解决的是包元数据查询和 tarball 下载慢这个问题。它不会改变 Node 运行时本身的版本也不会影响包安装完之后运行时的任何行为——因为镜像站同步的是上游 registry 的同一份制品包的完整性校验值是对得上的。不能解决的部分也很明确如果某个包在镜像站上还没同步到最新版本这种情况在新版本刚发布时偶有发生你拉到的可能是旧版本codex --version打出来的号会让你以为装了个假包。所以镜像方案的一个必要配套动作是装完之后用npm view openai/codex version和codex --version对一下两个数字应该一致。配置方式有三种粒度按影响范围从小到大排粒度命令写法影响范围适用场景单次命令npm install -g openai/codex --registry...仅本次临时装一次不想动全局配置项目级项目根目录.npmrc写 registry仅该项目CI 环境、团队统一全局npm config set registry ...当前用户所有 npm 操作长期在国内网络环境工作4.2 单次命令带镜像最不影响其他配置的写法如果你只是想快一点把 Codex 装上不想改任何持久配置直接在安装命令后面挂--registry参数就行npm install -g openai/codex --registryhttps://registry.npmmirror.com这个写法的好处是零副作用你的~/.npmrc一个字符都没变其他项目的依赖解析行为完全不受影响。坏处是每次装都得记得带上这个参数。我在给别人的机器做一次性安装时基本都用这个写法装完就走不留下任何配置痕迹。如果那台机器以后要长期用我才会建议改成全局配置。需要注意的是镜像地址的写法。带不带结尾斜杠、用 http 还是 https都会影响 npm 的解析尽量用标准形式https://registry.npmmirror.com别自己拼。4.3 全局切换镜像后的验证、异常处理与回滚如果你决定长期使用镜像配置命令是npm config set registry https://registry.npmmirror.com npm config get registry第二条命令用来确认写入生效。之后正常执行npm install -g openai/codex即可。这里有个细节值得提全局切换 registry 之后npm的缓存目录里会同时存在官方源和镜像源的包缓存。大多数情况下 npm 是靠完整性哈希来区分不会有问题但如果你之前装过某个包的旧版本切换源后有时会拿到缓存里的旧制品表现为明明镜像上有新版装出来还是老版。这时候清一下缓存再装npm cache verify npm cache clean --forcenpm cache verify是温和做法它只做校验和清理无效条目正常情况下用这个就够了。--force是全清会把所有缓存都丢掉下次装任何包都得重新下载非必要不用。回滚很简单npm config delete registry执行完再npm config get registry应该回落到官方默认地址。这一步我建议你装在装完之后就记下来因为有些企业内部网络环境对特定 registry 有额外要求切换久了你自己都会忘。5. 从认证到第一次真正跑通一次任务5.1 登录方式的选择与凭据存放位置装好之后第一次执行codex它会引导你完成认证。目前主要有两条路径一是通过账号授权走浏览器登录流程二是在命令行直接以 API key 方式登录。对于无图形界面的服务器浏览器流程会给你一个链接让你在另一台有浏览器的机器上打开并完成授权然后把回调结果贴回来。这个流程在纯终端环境下能走通但操作起来比较绕。我的经验是在有桌面的机器上用浏览器授权在服务器上直接用 key 登录各自用最顺手的方式。以 key 方式登录的一般形式是codex login --api-key 你的密钥密钥不应该写进 shell 历史。两个办法避免一是在命令前加一个空格需要你的 shell 配置了HISTCONTROLignorespace二是干脆用环境变量的方式让 CLI 自己去读。配置文件默认放在~/.codex/目录下这个目录的权限建议设成700chmod 700 ~/.codex这一步看着多余但凭据文件放在一个所有用户都可读的目录里在任何多人共用的机器上都是隐患。5.2 config.toml 里值得动手改的几个字段Codex 的主配置文件是~/.codex/config.toml。默认生成的配置能用但有几个字段值得根据你的使用习惯调一下。我列的是通用思路具体字段名以你装的版本codex --help和实际生成的配置文件为准版本之间会有差异。第一个是模型选择。不同模型的取舍在于速度和能力的平衡日常的代码解释、小范围改动用轻量一点的模型响应更快涉及跨文件重构、复杂逻辑推理换能力更强的模型更划算。这个没有标准答案看你当天在干什么。第二个是审批策略。这个字段决定 CLI 在执行命令前要不要停下来问你。选项大致分布在每步都问到完全放行之间。我的建议是第一次跑一定选最保守的那一档先用一个小仓库试看清楚它到底会执行哪些命令、改哪些文件心里有数之后再逐步放宽。第三个是沙箱模式。它控制 CLI 能碰到的文件范围从只读、到只能改当前工作目录、到完全放开是一个明显的能力阶梯。理解这个阶梯的最简单类比是只读模式像给你看但不给你笔工作区模式像给你笔但只准在这张纸上画完全放开就是整个桌面随你动。默认建议停在工作区模式绝大多数日常开发够用风险也可控。改配置的时候有个坑要提醒config.toml是 TOML 格式字符串要加引号布尔值是小写true/false写错了 CLI 启动时会直接报解析错误。我见过有人把布尔值写成True结果排查了半天以为是安装问题。改完统一用codex --help试一下能正常输出就说明配置解析通过了。5.3 第一次任务的推荐姿势小仓库、明确指令、盯住输出装完之后别急着在主力项目上跑。找一个几百行代码的小仓库或者干脆新建一个空目录放两三个文件用它来建立对工具行为的基本认知。第一次可以试试这类明确边界的任务让它在当前目录下读某个文件并解释逻辑或者让它写一个独立的脚本文件。这类任务的特点是输入明确、输出可验证、影响范围局限跑完你能立刻判断它做的对不对。观察的重点有三个它读了哪些文件说明它对上下文的理解范围、它执行了哪些命令说明它的动作边界、它改了哪些文件说明它的写权限实际用到了哪里。这三点摸清楚之后你对这个工具的能力和风险就有了直观认识再放到真实项目里就有底了。我在第一次用的时候犯过一个错没注意当前目录是家目录结果它扫了一大堆无关文件上下文被塞满输出质量很差。后来养成习惯跑之前先pwd看一眼确认在项目根目录下再启动。这个小动作能省掉很多困惑。6. 报错对照表与干净卸载重装的完整流程6.1 高频报错的现象、根因与处理动作下面这张表是我实际遇到和帮别人处理过的几类问题按出现频率排的现象根因判断处理动作codex: command not found全局 bin 不在 PATHnpm prefix -g查路径把它加进 PATH安装时报engine unsupportedNode 版本低于要求升级 Node 到 22 或以上重新确认which nodeEACCES: permission denied全局目录属 root改 prefix 到用户目录或用 nvm 重装下载卡住后超时registry 拉取不稳定加--registry参数走镜像源codex --version报二进制格式错误制品架构不匹配确认process.arch重装对应架构启动时报 TOML 解析错误配置文件语法问题检查引号与布尔值大小写或先备份后删除配置重生成装完版本号比预期旧缓存命中旧制品npm cache verify后重装用这张表的时候有个心法先分清是装的时候报错还是装完了跑不起来。前者九成在运行时、权限、网络这三件事上后者九成在 PATH、配置语法、凭据这三件事上。把问题归到这两大类里排查范围立刻缩小一半。还有一类比较隐蔽的情况命令能跑但行为诡异比如启动特别慢、或者读不到项目文件。这种情况往往不是安装问题而是工作目录不对或者配置文件里某个路径写成了绝对路径导致限制生效。先pwd确认位置再看配置里有没有硬编码路径。6.2 彻底卸载删干净才能装得干净排查到最后如果决定重装那就得卸干净。很多人只跑一句npm uninstall -g openai/codex然后重装发现还是老样子因为残留还在。完整的清理分三层。第一层是包本身npm uninstall -g openai/codex第二层是配置和凭据目录这个目录不会随卸载删除ls -la ~/.codex确认里面没有你还需要的内容之后再决定是否移除。我的习惯是先重命名备份而不是直接删mv ~/.codex ~/.codex.bak.$(date %s)这样万一重装后发现问题出在配置上还能把老配置拿出来对比。直接rm -rf的人出问题时就只能靠记忆重建。第三层是 npm 缓存。这一步不是必需的但如果怀疑是缓存里的坏制品导致的怪问题就做一次npm cache verify三层清理完which codex应该空空如也这时候再按第三节的流程重装环境就是干净的。6.3 版本升级与回退怎么锁定一个能用的版本工具迭代快的时候最新版不一定是最稳版。如果某个版本在你的项目上跑得好好的建议锁住它别每次重装都拉最新。锁定版本的写法是在包名后加版本号npm install -g openai/codex具体版本号查可用版本npm view openai/codex versions --json这个命令会输出一个数组从里面挑一个你验证过能用的号。用镜像源的时候如果发现版本列表比官方少说明镜像同步有延迟换个时间再查或者临时用官方地址查一次版本列表、再用镜像地址装指定版本——这个组合我经常用查版本走一个源、装包走另一个源两边的好处都拿到了。升级的流程和装新版本一样直接npm install -g openai/codex新版本号覆盖即可不用先卸载。覆盖安装之后记得重新跑codex --version确认生效因为有缓存的情况下偶尔会看到旧号这时候清缓存再装一次就好。回退也是同一条命令把版本号换成旧的就完事。真正需要小心的是配置文件格式跨大版本升级时字段名可能变旧配置在新版本上可能报解析错误。所以升级前把~/.codex/config.toml备份一份是我现在的固定动作花三秒钟能省掉半小时。最后分享一个我用了很久的小习惯在一台机器上第一次装好并验证通过之后把整个流程——包括 Node 版本、安装命令、镜像参数、配置改动——记成一个setup-notes.md放在家目录里。半年后换机器或者重装系统照着抄一遍十分钟搞定不用再从头回忆当初踩过哪些坑。这个习惯的价值只有在你第二次重装同一套环境的时候才真正体现出来。