Ubuntu 上安装 Codex CLI 与 Claude Code 的完整避坑指南

1. 为什么要在 Linux 上折腾这两个命令行工具如果你最近在关注 AI 辅助编程这个方向大概率已经反复看到两个名字Codex CLI 和 Claude Code。前者是 OpenAI 推出的终端编程助手后者是 Anthropic 出的同类产品两者都主打在命令行里直接和 AI 结对编程。我在自己的 Ubuntu 开发机上把这两个工具都装了一遍中间踩了不少坑也总结出一套相对稳妥的流程这篇就把完整过程和我个人的经验摊开讲。先说清楚这两个工具到底是什么、能干什么。Codex CLI 是一个跑在终端里的编程代理你可以把它理解成一个住在命令行里的结对程序员——它能读你当前项目的文件、理解代码结构、帮你改代码、跑命令、解释报错。Claude Code 定位几乎一样区别在于底层模型和交互风格。它们解决的共同痛点是不用离开终端、不用来回切换浏览器和编辑器直接在项目目录里用自然语言描述需求AI 就能动手改文件。适合谁来参考这篇内容三类人最合适。第一类是有一定 Linux 基础、日常在服务器或本地 Ubuntu 上写代码的开发者第二类是刚接触命令行 AI 工具、想尝鲜但被各种报错劝退的新手第三类是需要在多台机器上批量部署这类工具、想要一套可复现流程的运维同学。不管你属于哪一类下面的步骤都是可以直接抄作业的。需要提前说明的是这两个工具都依赖 Node.js 运行时而且对版本有要求。我实测下来Node 18 是底线Node 20 LTS 最稳。如果你机器上还是 Node 16 甚至更老后面一定会遇到各种莫名其妙的报错所以第一步永远是先把运行时环境理顺。另外这两个工具都需要联网调用云端模型网络环境的稳定性会直接影响使用体验这一点后面会专门讲。2. 装之前先把地基打牢Node 环境与包管理器选择2.1 Node.js 版本这道坎绕不过去很多人装这类 CLI 工具失败根子都在 Node 版本上。Codex CLI 和 Claude Code 都用了较新的 ESM 特性和一些原生模块Node 16 及以下基本跑不起来。我建议直接用 Node 20 LTS稳定性和兼容性都经过大量验证。在 Ubuntu 上装 Node 有好几种方式我踩过的坑值得说一下。用apt install nodejs装出来的版本往往很旧Ubuntu 22.04 默认源里是 Node 12 或 16直接就不达标。所以更推荐用 NodeSource 的源或者 nvm 来管理。用 nvm 的好处是可以在多个 Node 版本之间切换特别适合同时维护多个项目的开发者# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装并使用 Node 20 nvm install 20 nvm use 20 nvm alias default 20 # 验证 node -v npm -v如果你不想引入 nvm用 NodeSource 直接装系统级 Node 也行curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs提示装完之后一定要用node -v确认版本。我见过有人装完以为成功了结果which node指向的还是旧版本因为 PATH 里有多个 node 二进制。2.2 npm 全局目录的权限问题这是新手最容易卡住的地方。默认情况下npm install -g会往/usr/lib/node_modules或/usr/local/lib/node_modules写文件普通用户没权限于是要么报 EACCES 错误要么你就习惯性加 sudo。加 sudo 装全局包是个坏习惯会导致后续更新、卸载都出权限问题。正确做法是给当前用户配置一个独立的全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global # 把这一行加到 ~/.bashrc 或 ~/.zshrc export PATH~/.npm-global/bin:$PATH source ~/.bashrc这样以后所有npm install -g装的工具都落在你的家目录里不需要 sudo卸载也干净。这个配置一次做好后面装 Codex CLI 和 Claude Code 都会顺很多。2.3 确认网络与镜像源国内环境下 npm 官方源有时候会很慢装大包容易超时。可以临时切到国内镜像npm config set registry https://registry.npmmirror.com装完之后如果想让某些包走官方源可以再切回来。这个不是必须的但如果你遇到ETIMEDOUT或者卡在idealTree阶段很久换源通常能解决。3. Codex CLI 的安装与首次跑通3.1 安装命令与验证环境准备好之后Codex CLI 的安装本身很简单npm install -g openai/codex装完验证codex --version如果这一步报command not found八成是 PATH 没配好回去检查 2.2 里的全局目录配置。如果报的是unable to locate the codex cli binary or required runtime components这类错误通常意味着安装过程不完整或者 Node 版本不达标。我的处理办法是先卸载再重装npm uninstall -g openai/codex npm cache clean --force npm install -g openai/codex3.2 首次启动的认证流程第一次运行codex会引导你完成认证。它会打开浏览器或者给一个链接让你登录账号并授权。这里有个细节如果你是在没有图形界面的服务器上操作浏览器打不开需要用带--no-browser之类的参数或者手动复制终端里给出的链接到本地浏览器完成授权再把回调地址贴回去。认证信息一般会存在~/.codex/目录下。如果你在多台机器上使用注意不要把这个目录随便同步到公开的地方里面包含你的凭证。3.3 在项目里实际用起来认证完成后进入你的项目目录直接运行cd ~/projects/my-app codex它会以当前目录为工作区启动。你可以用自然语言让它做事比如帮我看看这个报错是什么原因把这个函数改成异步的给这个模块补上单元测试。Codex CLI 会读取相关文件、给出修改建议部分操作需要你确认后才会真正写入。我个人的使用习惯是先让它做只读的分析和解释确认它理解了上下文再让它动手改代码。直接让它大改容易失控尤其是它对你项目约定不熟悉的时候。注意Codex CLI 会实际读写你工作目录里的文件。第一次在重要项目里用之前强烈建议先git commit或者在一个测试分支上操作出问题能随时回滚。4. Claude Code 的安装与配置要点4.1 安装方式与版本确认Claude Code 同样通过 npm 分发npm install -g anthropic-ai/claude-code验证claude --version如果安装过程中报note: claude code might not be available in your country这类提示说明当前网络环境访问服务受限需要自行确认所在地区的服务可用性。这个不是安装本身的问题而是服务可达性的问题。4.2 认证与登录首次运行claude会引导登录。和 Codex CLI 类似它会给出一个授权链接。在服务器环境下同样需要手动处理回调。登录成功后凭证会保存在用户配置目录里。如果你同时装了 Codex CLI 和 Claude Code两者的配置目录是分开的互不干扰可以放心共存。4.3 在 VS Code 里配合使用很多人问能不能在 VS Code 里用这两个工具。答案是能但方式不太一样。Claude Code 有对应的编辑器集成方式可以在 VS Code 的集成终端里直接跑claude也可以配置任务或快捷键来调用。Codex CLI 同理本质都是在终端里运行VS Code 的终端就是终端。我的做法是在 VS Code 里开一个专门的终端面板跑这些工具和跑测试、跑构建的终端分开避免输出混在一起看不清。如果你经常用可以给它们配个快捷键或者 shell alias比如alias ccclaude alias cxcodex这样敲两个字母就能启动省事。4.4 卸载与清理如果装完发现不合适卸载也很直接npm uninstall -g anthropic-ai/claude-code npm uninstall -g openai/codex卸载后如果还想清理残留配置手动删掉对应的配置目录即可。注意别误删了其他工具的配置。5. 两个工具装完之后我踩过的那些坑5.1 权限与 PATH 类问题占了八成回顾我遇到的所有报错真正跟工具本身逻辑相关的很少绝大多数是环境问题。command not found、EACCES、permission denied、unable to locate binary这些几乎都能归到权限和 PATH 两类。所以我在 2.2 里反复强调全局目录配置这一步做对了后面能省掉一大半麻烦。排查这类问题的通用思路是先which codex看能不能找到二进制找不到就检查 PATH找到了但运行报错就node -v看版本版本没问题还报错就卸载重装并清缓存。5.2 网络波动导致的安装中断npm 装包过程中如果网络断了可能留下一个损坏的半成品表现为命令能跑但一执行就崩。这种情况npm cache clean --force加重新安装基本能解决。如果反复失败换镜像源或者换个时间段再试。5.3 多版本 Node 共存时的混乱如果你用 nvm 管理了多个 Node 版本注意全局包是跟着 Node 版本走的。你在 Node 18 下装的 codex切到 Node 20 之后可能就找不到了。解决办法是要么在每个用到的版本下都装一遍要么固定用一个版本作为日常开发版本。我个人的做法是固定 Node 20其他版本只在特定项目里临时切换。5.4 别在 root 下长期使用有些教程图省事让你全程 sudo 甚至直接用 root。短期应急可以长期这么干会带来一堆权限混乱而且这些工具会读写你的项目文件用 root 跑容易把文件属主改乱。老老实实配好用户级全局目录比什么都强。6. 让这两个工具真正融入日常开发流6.1 什么场景适合交给它们不是所有任务都适合丢给命令行 AI。我的经验是以下几类任务收益最高解释看不懂的报错和堆栈、给现有函数补测试、做重复性的代码改写比如批量改命名风格、快速理解一个陌生仓库的结构。而涉及核心业务逻辑设计、需要深度领域知识的改动还是自己把关更靠谱。6.2 和 Git 工作流配合用这类工具改代码一定要和 Git 配合好。我的习惯是每次让 AI 动手之前先确保工作区干净改完之后用git diff仔细看它到底改了什么。AI 改代码有时候会顺手改掉一些你没让它动的地方不看 diff 直接提交很容易埋雷。6.3 保持工具更新这两个工具迭代都很快新版本会修 bug、加功能。定期更新是个好习惯npm update -g openai/codex npm update -g anthropic-ai/claude-code更新完记得再跑一次--version确认偶尔会遇到更新后需要重新认证的情况。6.4 资源占用与终端体验这类工具在分析大项目时会读取不少文件内存和 CPU 会有一定占用。如果你在配置较低的机器或容器里跑注意观察资源情况。另外终端建议用支持真彩色和较好滚动的长时间交互体验会舒服很多。7. 一些零散但有用的实操心得装这两个工具的过程说到底就是把 Node 环境弄干净把权限配正确把网络搞稳定这三件事。我见过太多人卡在第一步就放弃了其实只要按顺序来半小时内两个都能跑起来。关于命令行的日常使用顺手补几个 Linux 上高频的命令配合这些工具用会经常碰到ls -la看目录详情、grep -r递归搜索、find按条件找文件、chmod改权限、ps aux看进程、df -h看磁盘、tail -f实时看日志。这些命令本身不难但在排查工具安装问题时特别有用比如用find ~/.npm-global -name codex*就能确认二进制到底装哪去了。最后分享一个我自己的小习惯每装一个新工具我都会在笔记里记下安装命令、版本号、配置目录位置和卸载方式。看起来啰嗦但等到几个月后要迁移机器或者清理环境时这几行记录能救命。工具会更新环境会变但一套清晰的记录能让你在任何时候都快速回到正轨。