Ubuntu 20.04 安装 Codex CLI：npm、镜像与二进制包

上周有位朋友在群里抱怨说他想在公司那台跑着 Ubuntu 20.04 的旧开发机上装个Codex CLI试试结果一条npm install -g卡了四十分钟最后超时换成官方二进制包下载又总是断在最后几兆折腾一晚上连命令行都跑不起来。这个场景太典型了——Ubuntu 20.04 本身是个极其好用的 LTS 系统但它的默认软件栈停留在 2020 年的水平Node 版本老、glibc 版本低再加上官方包分发节点的网络状况直接照着官网文档抄命令大概率会踩坑。这篇就把我前后在四五台不同配置的 20.04 机器上装 Codex CLI 的经验整理出来把官方安装路径和国内镜像加速安装路径都走一遍包括版本体检、npm 镜像源配置、二进制包手动落地、配置文件调优以及那些报错信息看起来毫不相关但根因都在同一个地方的疑难杂症。不管你是刚接触命令行 AI 编码工具的新手还是已经用过其他同类工具想换个轮子的老手照着这篇的顺序走一遍应该都能落地。1. 先想清楚为什么 Ubuntu 20.04 装 Codex CLI 会额外费劲1.1 Codex CLI 到底是个什么东西值不值得装先把概念理清楚免得装完发现不是自己要的东西。Codex CLI 是一个跑在终端里的编码智能体coding agent核心定位不是代码补全插件而是能在你的项目目录里自己读文件、改文件、跑命令的命令行助手。你给它一句自然语言需求它会自己去grep找相关文件、读上下文、生成补丁、执行测试遇到需要确认的危险操作会先问你。这个交互模型和 IDE 里的行内补全完全不同——后者是被动等你敲字前者是主动干活。它用 Rust 重写过所以最终产物是个原生二进制启动快、内存占用低这点在 2C4G 的小型云主机上体感特别明显。安装形态有三条路npm 全局包、系统包管理器macOS 上是 HomebrewLinux 上一般走 npm 或者直接拿二进制、以及从发布页直接下载预编译好的压缩包。这三种形态背后其实是同一份 Rust 产物只是分发渠道不一样理解这一点非常关键——后面很多装不上的问题本质都不是软件本身的问题而是分发渠道在你这个特定系统上不匹配。什么人适合用我觉得是三类一是经常在远程服务器上改代码、不方便开图形 IDE 的人二是有大量重复性重构、批量改配置、写脚本需求的人三是想在自己的自动化流水线里塞一个读需求→改代码→跑验证环节的人。反过来如果你只是想要个 Tab 补全那这东西对你的价值有限学习成本还不低。1.2 三个硬门槛Node 版本、glibc 版本、网络可达性Ubuntu 20.04 装不上或者装完跑不起来九成以上的原因集中在这三处我按踩坑概率从高到低排。第一是Node.js 版本。20.04 官方 apt 源里的nodejs包停在 10.19 左右而 Codex CLI 的 npm 包声明的最低要求通常在 Node 18 以上部分版本要求 20 或 22。你在这种环境下敲npm install -g运气好只是抛一堆engine警告然后装出一个跑不起来的空壳运气差直接EBADENGINE硬失败。我见过最迷惑的情况是装是装上了codex --version也能输出但一进交互模式就崩回头看日志才发现是 Node 太老导致某个语法特性不支持。第二是glibc 版本。20.04 搭载的是 glibc 2.31而部分在更新的发行版上编译出来的二进制会依赖 2.32 甚至 2.34 才引入的符号。表现是二进制文件明明有执行权限、file命令看也是正常的 ELF但一执行就报version GLIBC_2.xx not found。这个问题最恶心的地方在于它看起来像是文件损坏很多人会反复重新下载其实换一个链接目标类型就能解决——后面会讲怎么选 musl 版本规避。第三是网络可达性。npm 官方 registry 和 GitHub 的发布包下载节点从国内访问的体验时好时坏大包体Codex CLI 的二进制压缩包动辄几十兆在慢速链路上很容易在中途断掉而 npm 的失败重试机制有时候会给你留下一个半残的node_modules缓存导致后续重装反复失败。提示这三件事的排查顺序建议固定为先看 Node再看 glibc最后怀疑网络。因为前两个是确定性的一条命令就能证伪网络问题是不确定性的最容易让人陷入反复重试的泥潭。1.3 三条安装路线的取舍我个人的推荐顺序把路线摊开对比一下方便你按自己的环境选。路线前置依赖优点主要风险适用场景npm 全局安装Node 18、npm升级方便一条命令搞定依赖树重、缓存易脏、受 registry 网络影响有 Node 环境、需要频繁升降版本官方预编译二进制仅需基础运行库无运行时依赖、启动最快、可控性最强需要手动配 PATH、手动管理升级服务器环境、CI 容器、追求干净国内镜像加速视具体方式而定下载速度快、失败率低镜像同步可能有延迟、需校验完整性官方源长期拉不动的环境我的默认推荐是手上有 Node 18 就直接 npm 装省事没有 Node 或者不想为了一个工具污染全局 Node 环境就走二进制包。第二种情况在服务器上特别常见——你为了装个 CLI 去升级系统 Node可能把别的依赖 Node 10 的老服务搞挂这个代价太大了。国内镜像不是一条独立路线它是给前两条路线加速的手段可以叠加使用但要注意镜像源的同步延迟问题。2. 环境体检动手之前先把版本号摸清楚2.1 三行命令确认系统底子别急着敲安装命令先花三十秒把环境信息抓一遍后面出问题时这些数字就是判断依据。# 系统版本与架构 lsb_release -a uname -m # glibc 版本 ldd --version | head -n 1 # 现有的 node / npm node -v 2/dev/null || echo node not found npm -v 2/dev/null || echo npm not founduname -m的输出决定了你后面下哪个架构的包x86_64对应 amd64aarch64对应 arm64。这个别搞错下错了会得到一个格式错误的报错bash: ./codex: cannot execute binary file: Exec format error看起来像权限问题其实是架构不匹配。ldd --version第一行末尾通常带(Ubuntu GLIBC 2.31-0ubuntu9.x)这样的字样。如果是 2.31那你后面选二进制包时要优先考虑 musl 变体如果你之前手动升级过 libc不推荐但确实有人干过版本号会不一样注意别把系统搞成半坏状态。Node 那一行如果输出node not found恭喜你直接跳到二进制包路线最省事不用折腾版本管理。如果输出了但版本是 10.x那你就得决定是升级还是绕开。2.2 装 Node 的两种做法nvm 和 NodeSource 源如果你确定要走 npm 路线Node 的安装方式有两种主流选择各有取舍。做法一nvm 版本管理器。优点是装在用户目录下不污染系统包随时切版本卸载干净。缺点是每次新开 shell 要加载一次脚本在某些非交互式环境比如 cron、某些 CI 的 ssh 执行模式里可能加载不到需要手动 source。安装脚本的下载地址在国内访问可能慢如果卡住可以换个时间重试或者用镜像源。# 下载并执行 nvm 安装脚本版本号以官方最新为准 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装 LTS 版本 nvm install --lts nvm use --lts nvm alias default lts/*nvm alias default这一步很关键不设的话新开终端会回到系统默认 Node你会莫名其妙发现刚才明明装好了怎么又不行了。做法二NodeSource 官方源。优点是全局生效、对所有用户可用、不依赖 shell 配置。缺点是会和系统包管理器产生绑定关系将来想换版本要重新跑一遍添加源的脚本。添加源之前确保装了curl、gnupg、ca-certificates、software-properties-common这几个前置包否则脚本会在签名验证环节失败。sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg # 添加 NodeSource 源并安装以 20.x 为例 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs node -v npm -v装完记得验证一下版本如果node -v还是老版本说明 PATH 里有别的 node 优先级更高用which -a node看看有几份。注意不要为了图快用apt install nodejs npm装 Ubuntu 自带源里的那套。npm 的官方npm包和nodejs包在某些发行版上会互相打架导致全局安装路径混乱后面排查起来非常难受。2.3 npm 全局目录权限一个几乎人人都会撞的坑Ubuntu 上直接用sudo npm install -g是个坏习惯会产生 root 所有的文件导致后续非 root 用户升级时报EACCES。更麻烦的是有些包在 postinstall 阶段会写~/.cache用 sudo 跑会写成 root 的 cache然后普通用户跑的时候读不到报一些莫名其妙的权限错误。正确做法是把全局目录改到用户 home 下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global # 把 bin 目录加进 PATH写进 ~/.bashrc echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc # 验证 npm config get prefix配完之后npm install -g就不需要 sudo 了装出来的可执行文件落在~/.npm-global/bin和你手动放的二进制可以放在同一个路径下管理很清爽。这个配置我建议所有 Ubuntu 用户都做一遍不只是为了装 Codex CLI是通用的好习惯。3. 路线一走官方 npm 渠道把 Codex CLI 装起来3.1 安装命令与它背后发生了什么环境就绪之后安装本身只有一行npm install -g openai/codex但这行命令背后干的事比看起来多。npm 会先去 registry 拉这个包的元数据看看它有没有 postinstall 脚本然后根据你的平台架构决定要不要再下载一个平台专属的二进制包作为可选依赖。Codex CLI 的 npm 包本质上是一个很薄的启动器真正执行的是它为各平台预编译好的原生二进制。理解这一点能解释两个现象一是为什么安装包体这么大几十兆二是为什么有时候 npm 显示安装成功但实际跑不起来——因为二进制那部分没下全。安装过程中如果卡在某个包上很久可以加--verbose看它到底卡在哪一步npm install -g openai/codex --verbose 21 | tail -n 40输出里会显示当前在拉哪个 tarball、从哪个地址拉、速度多少。如果看到某个https://registry.npmjs.org/...的请求长时间没有进展那就是网络问题直接跳到第 4 章换镜像源。装完之后建议顺手看一下全局目录的产物结构能帮你理解后面排查的方向ls -la ~/.npm-global/lib/node_modules/openai/codex/ which codex正常情况下which codex应该指向~/.npm-global/bin/codex。如果指向/usr/bin/codex或者什么都不输出说明 PATH 顺序有问题或者刚才的 prefix 配置没生效。3.2 首次启动与结果校验装完别急着进交互模式先做三步校验。# 第一步版本号能打出来吗 codex --version # 第二步帮助信息完整吗 codex --help | head -n 30 # 第三步非交互模式跑一个最小任务 codex exec print the current directory name三步失败的位置不同指向的问题也不同。第一步就失败通常是二进制没下全或者架构不对去看~/.npm-global/lib/node_modules/openai/codex/下面有没有对应平台的二进制文件。第二步失败但第一步成功可能是 npm 包里的包装脚本和二进制版本不匹配重装一遍通常能好。第三步失败那基本就是认证或网络的问题了跟安装本身无关。我特别建议保留第三步这个验证动作。很多人装完codex --version正常就以为万事大吉结果第一次真正干活的时候才发现连不上服务白折腾。codex exec是最轻量的端到端测试几十秒就能把链路跑通验证一遍。3.3 登录方式与凭据管理Codex CLI 有两种认证方式选一种就行。方式一环境变量。把 API Key 塞进OPENAI_API_KEY这是最通用的做法也最容易在 CI 里用。缺点是密钥会出现在环境变量里进程能读到多用户机器上不太安全。export OPENAI_API_KEY你的密钥 # 想持久化就写进 ~/.bashrc但要注意文件权限 echo export OPENAI_API_KEY你的密钥 ~/.bashrc chmod 600 ~/.bashrc方式二登录流程。跑一次codex login它会引导你完成一次授权把凭据落到~/.codex/auth.json。这个文件生成后权限默认是 600比环境变量稍微可控一点因为不会被子进程继承。缺点是换机器要重新走一遍流程。codex login # 完成后确认凭据文件存在 ls -l ~/.codex/auth.json注意~/.codex/这个目录会被写进不少东西包括凭据、历史会话、配置。往代码仓库里提交时千万记得把它加进.gitignore我见过不止一次有人把auth.json连带项目一起推上去了。4. 路线二用国内镜像加速把下载这道坎绕过去4.1 npm registry 换源改、验、回滚三件套这是最省事也最通用的加速手段。npm 的 registry 地址是可配置的换成国内公共镜像站之后元数据查询和 tarball 下载都会走就近的节点速度提升非常明显。# 查看当前源 npm config get registry # 临时使用镜像源安装不修改全局配置 npm install -g openai/codex --registry镜像站地址 # 或者持久化修改 npm config set registry 镜像站地址我推荐先用--registry参数做一次性尝试确认能装上再决定要不要持久化。因为持久化改源之后将来某些包的元数据拉取可能有同步延迟——新发布的版本在镜像站上往往要等几分钟到几十分钟才出现这时候你会遇到明明官方文档说最新版是 X我这儿装出来是 X-1的情况容易误判。验证换源是否生效npm config get registry npm view openai/codex version --registry镜像站地址第二条命令能快速确认镜像站上有没有你要的那个版本。如果返回的版本号比官方发布页上的旧说明镜像还没同步完等一会儿或者临时切回官方源装。回滚很简单把 registry 设回默认值npm config set registry https://registry.npmjs.org/ npm config delete registry # 或者直接删掉这个配置项4.2 二进制包手动落地最干净也最可控的方式npm 渠道的各种缓存问题让我有点烦所以在服务器上我基本都走这条路直接拿预编译好的压缩包解压放路径改个软链。整个过程不到一分钟产物清清爽爽升级就是把软链指向新文件回滚就是把软链指回去。第一步选对包的类型。这里有个关键决策点优先选musl变体而不是gnu变体。musl 是静态链接的 libc 实现打出来的二进制不依赖宿主系统的 glibc 版本在 Ubuntu 20.04 这种 glibc 偏老的系统上兼容性最好。文件名里通常带musl或unknown-linux-musl字样架构部分对应x86_64或aarch64。第二步下载。如果发布页直连下载慢可以用国内公开的镜像服务做前缀加速很多镜像站支持对发布包地址做转发。下载完务必核验完整性。# 下载地址以实际发布页为准 curl -fL -o codex.tar.gz 发布包地址 # 核验对比官方提供的校验值 sha256sum codex.tar.gz # 与发布页上对应文件的 sha256 逐字符比对必须完全一致这一步别省。半截下载的压缩包有时候tar能解开因为 gzip 流被截断但前面部分有效解出来的二进制跑起来行为诡异你会往完全错误的方向排查。第三步解压并安装到标准位置。mkdir -p ~/.local/bin tar -xzf codex.tar.gz chmod x codex mv codex ~/.local/bin/codex # 确保 PATH 包含 ~/.local/bin echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc第四步做多版本管理。我的习惯是把二进制按版本号命名放进一个目录再用软链指向当前使用的版本升级和回滚都变成一次软链操作。mkdir -p ~/.local/opt/codex mv ~/.local/bin/codex ~/.local/opt/codex/codex-版本号 ln -sf ~/.local/opt/codex/codex-版本号 ~/.local/bin/codex codex --version4.3 用镜像时容易忽略的几个副作用镜像加速好用但它不是透明的用了就得接受几个副作用提前知道能少走弯路。同步延迟。这是最常见的。镜像站不是实时同步的新版本刚发布那几小时你从镜像拉到的可能是旧版。判断方法很简单npm view 包名 versions --registry镜像和官方源对比一下末尾几个版本号。如果你追新功能那就绕开镜像直接用官方源装那一次。镜像站的可信度。公共镜像站是第三方服务理论上存在内容被篡改的可能。所以凡是走镜像拉下来的二进制包sha256 校验这一步必须做而且校验值要从官方发布页取不能从镜像站取。npm 包相对安全一些因为 npm 本身有完整性校验机制但也不是绝对。换源后其他项目的连带影响。全局改 registry 会影响所有 npm 操作包括你其他项目里的npm ci。有些老项目锁定的 lockfile 里记录了官方源的完整 URL 和 integrity 值换源之后npm ci可能报EINTEGRITY或者走不通。所以我的建议是别全局改源用--registry参数按需使用或者给某个项目单独写一个.npmrc。镜像地址的可用性会变。公共镜像服务不是永久承诺有的会停服、有的会限速。建议在自己机器上记两三个备选地址一个不行换下一个别在一棵树上吊死。5. 配置文件调优让 Codex CLI 真正顺手5.1 配置文件的组织方式与核心参数装完只是能跑要用得舒服还得改配置。配置文件在~/.codex/config.tomlTOML 格式改完不用重启下次启动生效。# ~/.codex/config.toml model gpt-5-codex approval_policy on-request sandbox_mode workspace-write # 会话与历史相关 [history] persistence save-all # 项目级覆盖示例在具体项目里允许更宽的权限 [projects./home/你的用户名/work/某个项目] trust_level trusted三个核心参数值得单独说一下取舍逻辑。model决定用哪个模型。这里没有绝对最优解代码类任务和通用任务适合的模型不一样。我的做法是准备两套配置一套日常用一套重活时切通过注释切换比反复改配置省心。approval_policy决定它什么时候停下来问你确认。选项大致从每一步都问到从不问分布。刚开始用建议选中间档让它对危险操作比如删文件、跑git push、执行网络请求停下来问你对读文件、跑测试这类安全操作放行。用熟之后再往宽松的方向调。sandbox_mode决定文件系统访问范围。read-only最安全它只能看不能改适合帮我分析一下这个项目这类场景。workspace-write是日常用的能改当前工作目录但碰不到外面的东西。还有一个全开放的档位除非你在一次性的容器里跑否则我不建议开。5.2 接入兼容接口的自建服务或第三方服务Codex CLI 支持配置自定义的模型提供方这对有内部推理服务或者使用第三方兼容接口的团队很有用。配置方式是在config.toml里定义一个 provider 段落然后在顶层用model_provider引用它。model 某个模型名 model_provider my_provider [model_providers.my_provider] name My Provider base_url https://你的服务地址/v1 env_key MY_PROVIDER_API_KEY wire_api chatbase_url指向服务的 API 根路径注意结尾的/v1之类的前缀要和服务端要求一致多一个斜杠少一个斜杠都可能 404。env_key指定从哪个环境变量读密钥这样密钥不落在配置文件里。wire_api指定协议风格大部分兼容实现用的是 chat 风格个别用 responses 风格填错会报参数不识别。# 环境变量里放密钥 export MY_PROVIDER_API_KEY你的密钥 codex exec 列出当前目录的文件这套配置的实际价值在于你可以在内网部署的推理服务上跑 Codex CLI代码不用出内网对数据敏感的场景很关键。代价是不同兼容实现的细节差异不小工具调用格式、流式返回、token 统计这些地方都可能对不上需要逐个试。5.3 权限策略与沙箱的实际取舍经验用了几个月下来我对这两个参数的理解是它们不是安全等级滑块而是信任边界声明。在自己本机的个人项目里我基本把sandbox_mode设成workspace-write、approval_policy设得比较宽松。因为这些代码本来就在 git 里改坏了大不了git checkout而且频繁弹确认会把交互节奏打碎体验很差。这种情况下效率优先。在共享服务器或者有生产配置的仓库里我反过来sandbox_mode收紧到read-only让它只分析不改动需要改的时候我手动复制它给的补丁。听起来麻烦但一次误改配置文件引发的线上问题排查成本远超这点麻烦。在容器里跑批量任务时反而是最宽松的配置最合适因为整个容器就是一次性沙箱坏了直接重建这时候任何确认弹窗都是在浪费自动化流程的时间。注意不管哪种策略第一次在一个新项目里跑之前先git status确认工作区是干净的。这样万一它改了什么你不满意的东西一条git checkout .就能全撤销。这习惯救过我两次。6. 常见问题与排查实录6.1 安装阶段的高频报错速查报错关键词根因处理办法EBADENGINE/Unsupported engineNode 版本低于要求升级 Node 到 18 或改用二进制包EACCES: permission denied全局目录权限问题配npm config set prefix ~/.npm-globalETIMEDOUT/ECONNRESETregistry 下载超时或中断换镜像源或改走二进制包路线EINTEGRITY缓存中的包校验失败npm cache clean --force后重装GLIBC_2.xx not found二进制依赖的 glibc 版本高于系统换 musl 变体的发布包cannot execute binary file: Exec format error架构不匹配确认uname -m后下对应架构包No such file or directory但文件明明存在动态链接器路径不对用file和ldd看依赖换静态链接版本GLIBC_2.xx not found和No such file or directory这两条特别容易被误判因为它们字面上都不像版本或架构问题。前者明明说找不到符号后者明明文件就在那儿。遇到这两条别急着删了重装先用两条命令定位真实原因file ./codex # 看它是静态链接还是动态链接、什么架构 ldd ./codex # 看它依赖哪些共享库缺哪个一目了然ldd输出里出现not found的那一行就是缺的库。如果整个二进制是静态链接的file输出里带statically linked那ldd会告诉你not a dynamic executable这种情况就不用查依赖了问题一定在别处。6.2 运行阶段的典型故障与排查思路装完之后跑起来的问题我整理了几类最高频的。启动即退出无任何输出。先用codex --version试试能出版本号说明二进制本身没问题问题在启动后的初始化逻辑。再看~/.codex/目录下有没有日志文件翻最后几十行。最常见的原因是配置文件语法错误——TOML 格式对引号和方括号很严格少一个引号整份配置就解析失败而错误提示可能被吞掉了。能启动但一执行任务就超时。分开验证两件事网络能不能通、密钥有没有效。先用最简单的codex exec say hi试试再检查echo $OPENAI_API_KEY是否有值、值是否正确注意别把带换行符的内容粘进去这个坑我踩过。如果用的是自建的兼容服务用curl直接打一下base_url的/models端点确认服务本身活着。交互模式里中文显示成方块或者乱码。这是终端 locale 的问题不是工具的问题。echo $LANG看一下如果不是en_US.UTF-8或zh_CN.UTF-8之类装一下语言包并设好环境变量sudo apt-get install -y locales sudo locale-gen en_US.UTF-8 export LANGen_US.UTF-8 export LC_ALLen_US.UTF-8执行命令时权限报错。检查sandbox_mode的设置read-only模式下它想写文件会被拦报错信息里通常带sandbox字样。改配置或者临时用更高权限跑一次。改了配置不生效。确认你改的是~/.codex/config.toml而不是项目目录下的同名文件。项目级的配置优先级更高如果你之前为了某个项目建过./.codex/config.toml那全局配置会被覆盖这个逻辑一定要清楚。6.3 一套可以直接照抄的排查顺序最后把我自己的排查流程固化下来遇到问题按顺序走基本十分钟内能定位。第一步确认二进制本身健康file看架构和链接方式--version看能否执行。这一步排除掉文件本身是坏的。第二步确认依赖环境ldd看共享库是否齐、node -v看 Node 版本npm 安装的情况下。这一步排除掉环境不匹配。第三步确认配置语法把~/.codex/config.toml临时改名为.bak跑一次不带配置的启动。如果这样能跑那问题就在配置里一行一行往回加。第四步确认网络与认证用codex exec跑一个最小任务出错就curl直连服务端验证连通性和密钥有效性。这一步排除掉外部依赖。第五步看日志~/.codex/下的日志文件按时间翻最后几十行大部分问题这里都有明确答案只是很多人不看。这套顺序的核心思路是从内往外排查先确认软件本身再确认环境最后才怀疑外部服务。反过来排查最痛苦因为网络问题和配置问题都会表现为跑不起来你很难分清。我在实际使用中最大的体会是装这类工具真正花时间的从来不是那条安装命令而是环境适配和后续调优。Ubuntu 20.04 这类偏老的 LTS 系统尤其如此它的软件栈和当前主流工具链之间有几年的落差这个落差不是靠一条命令能抹平的。所以我现在的习惯是拿到一台新机器先把 Node 版本管理、PATH、npm prefix 这三件事一次性配好配完之后再装任何命令行工具都是几分钟的事一劳永逸。另外一个小技巧分享给经常在多个环境之间切换的人把自己调好的~/.codex/config.toml存一份到私有仓库里换机器直接拷过去比每次重新查参数省太多时间。最后提醒一句镜像加速只是手段无论走哪条路二进制包的完整性和来源可信度永远要自己把关图省事跳过校验这一步迟早要吃一次亏。