1. Ubuntu 20.04 装 Codex CLI 到底卡在哪
OpenAI Codex CLI 是一个跑在终端里的代码智能体，能直接读你当前目录的工程、改文件、跑命令，适合 ROS、Python、C++、前端这类本地项目做代码分析和批量修改。它跟网页版最大的区别是：工作目录就是你的项目目录，改完还能用/diff看它动了哪些文件，可控性比复制粘贴强很多。
但 Ubuntu 20.04 这个版本有点尴尬。它自带的 Node.js 往往是 10.x，而 Codex CLI 要求 Node.js >= 16，推荐 20。于是很多人第一步npm install -g @openai/codex就直接报Unsupported engine。第二个坑是官方那条curl ... | sh的安装脚本，在国内网络下经常下到一半连接被掐断，报transfer closed with xxxx bytes remaining to read。第三个坑是权限，直接sudo npm install -g会把包装到系统目录，后面升级、卸载都别扭。
所以这篇我按两条路径写：一条是官方脚本安装，一条是 npm + 国内镜像安装（推荐）。同时把 Node.js 环境用 nvm 管起来，最后用 TaoToken 统一 Key 和 API 通道接进去，这样你不用在多个平台之间来回切 Key。整套流程在 Ubuntu 20.04 上实测可跑通，命令都能直接复制。
2. 前置准备：nvm 与 Node.js 20 环境
Ubuntu 20.04 自带的 Node.js 太旧，别去动系统自带的，用 nvm 装一个用户级的 Node.js 20，全局包目录会落在~/.nvm下，天然不需要 sudo。
2.1 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash source ~/.bashrc nvm --version如果nvm --version能打印出版本号（比如0.40.3），说明装好了。这里如果 raw.githubusercontent.com 拉不动，可以多试两次，或者换用 gitee 上的 nvm 镜像仓库，命令结构一样，把 URL 换掉即可。
2.2 安装并锁定 Node.js 20
nvm install 20 nvm use 20 nvm alias default 20 node -v npm -v正常应该看到v20.x.x和10.x.x。nvm alias default 20这步别省，它保证你新开一个终端时默认还是 Node 20，不然下次开终端又回到旧版本，Codex 又跑不起来。
2.3 清掉可能存在的 npm prefix
如果你之前手动配过 npm 全局目录，先删掉，避免和 nvm 冲突：
npm config delete prefix npm config get prefix返回的路径应该长这样：/home/你的用户名/.nvm/versions/node/v20.x.x。只要在~/.nvm下面就是对的。
3. 两条安装路径：官方脚本 vs npm 镜像
3.1 官方脚本安装（网络好时可用）
官方给 Linux/macOS 的一键命令是：
curl -fsSL https://chatgpt.com/codex/install.sh | sh装完验证：
codex --version输出类似codex-cli 0.142.5就成功了。这条路径的优点是省事，缺点是它要下载二进制文件，国内网络下经常卡在Downloading Codex CLI或者中途断流。如果你遇到curl: (18) transfer closed with xxxx bytes remaining to read，别硬刚，直接走下面的 npm 路径。
3.2 npm 国内镜像安装（推荐）
先把 npm 源切到国内镜像：
npm config set registry https://registry.npmmirror.com npm config get registry返回https://registry.npmmirror.com就对了。这个配置写进~/.npmrc，之后所有npm install默认走镜像。
然后安装 Codex CLI，注意不要加 sudo：
npm install -g @openai/codex如果网络还是抖，加上重试参数：
npm install -g @openai/codex \ --fetch-timeout=120000 \ --fetch-retries=5 \ --fetch-retry-mintimeout=20000 \ --fetch-retry-maxtimeout=120000装完验证：
codex --version想切回官方源的话：npm config set registry https://registry.npmjs.org/。
4. 用 TaoToken 统一 Key 与 API 通道
Codex CLI 第一次启动会要求登录或配 API Key。如果你手上有多个模型的 Key，来回切换很烦。我一般用 TaoToken 做统一入口，一个 Key 走多个模型通道，配置集中在一个文件里。
4.1 拿 Key
去控制台创建 API Key：
https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite创建后复制那串 Key，别贴到聊天记录里。
4.2 config.toml 骨架
Codex CLI 的配置放在~/.codex/config.toml。先建目录再写文件：
mkdir -p ~/.codex nano ~/.codex/config.toml写入下面这个骨架：
# ~/.codex/config.toml model = "gpt-4o" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" wire_api = "chat"然后把 Key 写进环境变量，别硬编码在 toml 里：
echo 'export TAOTOKEN_API_KEY="你的Key"' >> ~/.bashrc source ~/.bashrcbase_url用https://taotoken.net/api，注意这里不带任何查询参数。wire_api = "chat"表示走 chat completions 协议，Codex CLI 兼容这个格式。
4.3 验证连通性
先确认环境变量读到了：
echo $TAOTOKEN_API_KEY然后直接发一个最小请求，确认通道通：
curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 10 }'返回里带choices字段就说明 Key 和通道都正常。这一步过了，再启动 Codex 就不会卡在鉴权上。
5. 启动 Codex 并跑通第一个任务
5.1 在项目目录下启动
别在主目录~下启动，Codex 会把当前目录当工作目录，在主目录下它可能扫到一堆无关文件。先进项目：
cd ~/catkin_ws/src/your_ros_package codex或者普通项目：
cd ~/your_project codex启动后能看到类似model: ...和directory: ...的界面。
5.2 第一次让它只读分析
先别让它改文件，用只读指令探路：
请先阅读当前项目结构，不要修改任何文件。请总结每个主要文件的作用，并告诉我这个项目应该如何运行。ROS 项目可以更具体：
请先阅读当前 ROS 包，不要修改任何文件。请重点分析 launch 文件、src 文件夹、CMakeLists.txt 和 package.xml，并总结节点结构、话题接口和运行流程。确认它理解对了，再让它改代码，并且限定范围：
请只修改 src/node_main.py，不要修改其他文件。修改完成后告诉我改了哪些内容。5.3 常用交互命令
| 命令 | 作用 |
|---|---|
/status | 查看当前会话状态 |
/model | 切换模型 |
/diff | 查看当前改了哪些文件 |
/review | 让 Codex 检查当前改动 |
/exit | 退出 |
/diff和/review这两个建议养成习惯，改完先看一眼再决定要不要保留。
6. 本篇常见报错排查
6.1 Unsupported engine
报错长这样：
Unsupported engine for @openai/codex wanted: {"node":">=16"} current: {"node":"10.19.0","npm":"6.14.4"}原因就是 Node.js 太旧。解决：
nvm install 20 nvm use 20 nvm alias default 20 npm install -g @openai/codex6.2 EACCES 权限拒绝
npm ERR! code EACCES npm ERR! Error: EACCES: permission denied, access '/usr/local/lib'说明你在往系统目录装全局包。别用sudo npm install -g，正确做法是回到 nvm 环境：
npm config delete prefix npm config get prefix确认 prefix 在~/.nvm下，再重装。
6.3 下载慢或卡住
先切镜像，再加重试参数：
npm config set registry https://registry.npmmirror.com npm install -g @openai/codex \ --fetch-timeout=120000 \ --fetch-retries=56.4 启动后鉴权失败
如果 Codex 启动后提示鉴权错误，先回到第 4.3 节用 curl 单独测一次通道。curl 通、Codex 不通，多半是config.toml里env_key名字和实际环境变量对不上，或者base_url多写了/v1。base_url只写到https://taotoken.net/api，路径由 Codex 自己拼。
6.5 模型名不识别
model字段要填通道支持的模型名。填错会报 model not found。不确定的话，可以先去模型对话页面确认可用模型：
https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite7. 长期编码与接入文档
如果你只是偶尔用 Codex 改改脚本，上面这套配置够了。但如果你打算把它当日常编码助手，或者接进 Agent 工作流长期跑，建议看一下 Coding Plan，额度和通道策略会更适合高频场景：
https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite接入细节、参数说明和更多客户端配置，都在接入文档里：
https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite另外，如果你用的是 Claude Code 那套 Anthropic 协议的工具，TaoToken 也有对应的接入说明：
https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code&utm_campaign=rewrite最后提醒一句：Codex CLI 是终端里的代码助手，不是编辑器替代品。它的价值在于批量读改和命令执行，改完记得用/diff过一遍，重要项目先 commit 再让它动手，这个习惯能省掉很多回滚的麻烦。
