最近给一台 Ubuntu 服务器搭 AI 编码环境要把 Codex CLI 和 Claude Code 都装上。初见以为就是两条npm install -g的事实际跑下来才发现光是一个 “unable to locate the codex cli binary” 就牵扯出 PATH 配置、Node 版本、Electron 应用环境继承一堆问题。Codex CLI 和 Claude Code 是目前终端里两种典型的 AI 编码代理工具前者来自 OpenAI后者来自 Anthropic它们能直接在命令行里接管“读代码—改代码—跑命令”这条链路很多做开发和运维的同事已经把它们放进日常工具箱了。这篇文章就把从零开始部署的过程、要避开的坑以及最常见的二进制文件定位错误排查一次讲清楚。1. 先搞清楚 Codex CLI 和 Claude Code 各自的定位1.1 两者在终端里到底帮你做什么很多人第一次听说这两个工具会误以为它们只是某个模型的命令行外壳其实不是。它们更像是一个驻留在终端里的“编码代理”你看代码、提需求它去理解项目结构、修改文件、执行命令、跑测试然后把结果反馈给你你再继续提要求就这样一轮一轮迭代下去。Codex CLI 是 OpenAI 推出的开源工具底层默认走 ChatGPT 那套账号体系。你给它一个任务比如“帮我修复 CI 里报错的单元测试”它会先分析项目列出它准备怎么改然后请求权限去修改文件、运行命令。整个过程在终端里完成不需要切到网页端也不需要写一堆 prompt 去复制粘贴代码。Claude Code 是 Anthropic 出的同类工具底层走 Claude 的模型。它同样能理解项目代码、操作文件系统、执行 shell 命令。两者在功能形态上很像但模型能力和交互风格有差异具体哪个好用取决于任务类型和个人习惯。打个比方你等于在终端里雇了一位结对编程的同事。这位同事不是只帮你生成代码片段而是真的坐在你的项目里能自己看文件、自己动手改、自己跑命令验证。正因为它有执行能力所以安装时的权限配置、路径配置才不能随便糊弄。1.2 为什么推荐在 Linux 服务器上同时部署我把两个工具装在同一台服务器上不是因为“小孩子才做选择”而是实际场景确实需要。第一服务器环境通常更接近生产环境。你在自己笔记本上改代码和在一台干净的 Linux 服务器上跑项目涉及的系统库、路径、权限完全不一样。直接在服务器上让 AI 代理处理问题它看到的就是真实环境改出来的东西更有参考价值。第二模型需要对比。同一个 bugCodex CLI 和 Claude Code 给的修复思路可能完全不同。一个偏保守一个偏激进实际验证下来差异很大。同一台机器上同时装着切换成本几乎为零哪个思路合理就用哪个。第三很多项目本身就跑在服务器上尤其嵌入式、后端服务、数据处理的场景。ssh 进去直接操作比在本地搞一套远程开发环境轻量得多。配合 tmux 在服务器上挂一个长期会话AI 代理跑任务的时候你完全可以断开终端过一会儿再回来看结果。2. Linux 安装前的环境准备2.1 Node.js 版本与 npm 的坑Codex CLI 和 Claude Code 都通过 npm 分发所以环境准备的核心就是 Node.js 和 npm。Claude Code 明确要求 Node.js 18 以上Codex CLI 同样需要现代版本建议直接用 20 或 22 的 LTS 版本。这里有个经典坑直接用系统的包管理器装 Node版本往往非常旧。比如 Ubuntu 20.04 上执行apt install nodejs npm装完一看node 是 v10 或 v12npm 也老得不像话。这时候执行 Claude Code 的安装命令可能装都装不上或者装上了运行时各种报错。所以第一步先检查版本node -v npm -v如果版本低于 18不要犹豫别去折腾老版本兼容直接换新。与其去跟包管理器较劲不如用 nvm 做用户级安装一劳永逸。2.2 用 nvm 避免全局权限地狱nvm 是我在 Linux 上装 Node 的首选方式没有之一。它的好处是不需要 root 权限不会污染系统目录切换 Node 版本非常灵活最重要的是避免了npm install -g时最常见的 EACCES 权限报错。安装 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完之后重新登录或手动加载环境变量export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh然后安装 LTS 版本 Nodenvm install --lts nvm alias default lts/* node -v npm -vnvm alias default这步很多人会漏掉。不设置默认别名新开一个终端窗口node 可能又找不到了。设置完默认别名每次登录 shell 都会自动加载当前默认版本。用 nvm 还有一个隐藏好处全局安装的 npm 包会放在~/.nvm/versions/node/v22.x.x/lib/node_modules下面对应的可执行文件在~/.nvm/versions/node/v22.x.x/bin。这个路径归当前用户所有不需要 sudo后续维护和删除都非常干净。2.3 PATH 环境变量对后续排错的意义聊到这里必须把 PATH 这个概念掰开揉碎讲清楚因为后面那个“找不到 codex cli 二进制文件”的错误十有八九就是 PATH 问题。PATH 是 shell 用来查找可执行文件的目录列表。你在终端输入codexshell 会依次去 PATH 里的每个目录找有没有叫codex的文件找到了就执行找不到就报“command not found”。nvm 在加载时会自动把当前 Node 版本的 bin 目录加到 PATH 里所以正常情况下你装完 nvm 后which codex应该能直接找到路径。但如果你用的是系统自带的 Node或者后面切换了 Node 版本这个路径就可能导致问题。安装之前先记录一下当前环境的关键信息方便后面排查检查项命令期望结果Node 版本node -vv18 及以上npm 版本npm -v9 及以上npm 全局目录npm config get prefixnvm 下的 node 目录PATH 内容echo $PATH包含 npm 全局 bin 目录npm config get prefix这个命令特别有用。它直接告诉你 npm 全局安装的可执行文件会被放到哪个目录。如果这个目录不在 PATH 里那你装多少全局包都白搭。3. Codex CLI 的安装与认证3.1 npm 全局安装命令与验证环境准备好之后安装 Codex CLI 就是一条命令npm install -g openai/codex安装完成后验证codex --version如果能看到版本号说明安装成功。如果提示 command not found别急着重装先用npm config get prefix查一下全局目录然后看这个目录在不在 PATH 里。大概率是 PATH 的问题不是包本身的问题。除了 npmCodex CLI 在 Linux 上也有其他安装方式比如 Homebrew 和 Cargo。但 npm 方式跨发行版一致性最好对 Ubuntu、Debian、CentOS 一视同仁我推荐直接用 npm。如果之前装过旧版本升级也一样npm update -g openai/codex3.2 登录认证与权限模型安装完成后直接运行codex首次运行会输出一个链接让你用 ChatGPT 账号完成浏览器授权。授权成功后token 会保存在~/.codex/auth.json之后再启动就不会重复要求登录了。这里有一个很多人容易忽略的点Codex CLI 不是一个纯粹的代码生成工具它可以执行 shell 命令、修改文件、应用补丁。因此它有一套权限模型。默认情况下执行关键操作前它会询问你允许运行这个命令吗允许修改这个文件吗你可以在~/.codex/config.toml里配置模型和权限。比如model gpt-4.1 model_provider openai权限相关的配置也在同一目录。我的建议是刚上手时保持默认的询问机制每次操作都看一眼再给权限等熟悉了它的大致行为模式再考虑放宽。3.3 遇到 “chatgpt failed to start” 的典型原因这里多提一句很多人其实不是在纯终端里用 Codex而是在 ChatGPT 桌面版或 VS Code 扩展里调用。这时候如果弹出 “chatgpt failed to start. unable to locate the codex cli binary. set codex cli path or ensure the electron app can access the binary”别慌问题通常不是 Codex 本身坏了而是外层应用启动时找不到 codex 这个可执行文件。典型原因有三个命令行里能用 codex但桌面应用继承的环境变量里没有 nvm 的 PATH 配置。codex 根本没装进当前用户的环境装到了别的用户或系统目录。安装后的 Node 版本和当前运行的 Node 版本不一致导致模块加载异常。这个问题的完整排查链路我放在第 5 章专门展开因为它值得单独占一个章节。4. Claude Code 安装与登录流程4.1 npm 安装与版本检查Claude Code 的安装方式和 Codex CLI 几乎一样npm install -g anthropic-ai/claude-code验证claude --version如果想不全局安装、临时体验一下也可以用npx anthropic-ai/claude-codenpx方式适合在别人机器上临时跑一次不留下全局包但日常使用还是建议全局安装响应更快版本也更好管理。4.2 Claude 订阅/API Key 两种登录方式Claude Code 支持两种认证方式理解它们的区别很重要。第一种是交互式登录适合有 Claude 订阅账号的用户。直接运行claude它会输出一个链接在浏览器里完成授权后终端会自动进入对话界面。token 会存在本地配置里之后不用重复登录。第二种是 API Key 方式适合用 Anthropic API 付费或者通过其他兼容接口访问的用户。设置环境变量export ANTHROPIC_API_KEYsk-ant-xxxxxxxx也可以把 Key 写进配置文件~/.claude/settings.json{ env: { ANTHROPIC_API_KEY: sk-ant-xxxxxxxx } }两种方式的优先级要注意环境变量通常优先于配置文件。如果你同时设置了环境变量和交互登录的 token可能走的还是环境变量那个通道。所以排查认证问题时先看一下环境变量里有没有ANTHROPIC_API_KEY在捣乱。4.3 处理“组织已禁用 Claude 订阅访问”问题实际部署时碰到过一个很具体的报错your organization has disabled claude subscription access for claude code这个错误的意思是你当前登录的 Claude 账号被所在组织限制不允许通过 Claude Code 使用订阅权限。常见于企业托管的 Claude 账号或者用团队版账号登录的情况。解决办法有两个方向改用个人 Claude 账号完成交互登录。改用 API Key 方式不依赖订阅权限。如果切换账号还不行再看一下是不是网络环境的问题。有些服务器访问外网接口不稳定登录流程走到一半就断了表面上看是权限报错实际是网络超时。先把网络连通性确认好再排查账号权限。5. “unable to locate the codex cli binary” 的完整排查链路5.1 错误信息出现的场景这个错误值得单独开一章因为它的出现频率太高了。完整报错一般是这样的chatgpt failed to start. unable to locate the codex cli binary. set codex cli path or ensure the electron app can access the binary出现的场景集中在两类一类是 VS Code 里装了 ChatGPT 或 Codex 相关扩展启动面板时触发另一类是 ChatGPT 桌面应用Electron内置的 Codex 功能触发。核心机制一样外层应用是一个 GUI 程序它需要调用codex这个命令行的可执行文件但它在自己的进程环境里找不到。5.2 先从命令行确认二进制文件是否真的存在排查的第一步永远是在终端手动确认codex到底能不能用。执行which codex type -a codex codex --version npm ls -g openai/codexwhich codex能找到路径说明命令行环境正常。type -a codex能看到所有匹配的路径防止有多个版本互相干扰。codex --version能打印版本说明二进制能正常运行。npm ls -g openai/codex确认 npm 层面的安装状态。如果这一步就卡住了什么都找不到那是安装本身或 PATH 的问题。重新执行安装然后确认 nvm 是否被正确加载echo $PATH | grep nvm如果 PATH 里完全没有 nvm 相关路径那说明你的.bashrc或.zshrc里没加载 nvm。回头检查~/.bashrc里有没有 nvm 初始化那几行。5.3 GUI 应用找不到二进制的根因环境继承这是我这次部署踩得最深的一个坑值得单独写清楚。terminal 里用得好好的 codex桌面应用却找不到根因在于环境变量的继承机制。通过 SSH 登录服务器shell 会加载.bashrc、.zshrcnvm 就是这时候被加载进 PATH 的。但 Linux 桌面环境里的 GUI 应用不是通过你的 shell 启动的它是通过桌面会话直接拉起的进程继承的是系统级环境变量根本不会读你的.bashrc。所以在终端里which codex有结果不代表 VS Code 或 Electron 应用也看得到。想解决有三种思路按推荐程度排方案 A给系统目录做一个软链接。这是最省事、最通用的方式sudo ln -s ~/.nvm/versions/node/v22.14.0/bin/codex /usr/local/bin/codex软链接做出来之后任何进程都能在/usr/local/bin下找到 codex不依赖 shell 环境。注意把v22.14.0换成你实际的 Node 版本目录可以用which codex先确认完整路径再粘贴进去。方案 B在应用的配置里手动指定 codex 路径。VS Code 用户可以在 settings.json 里加chatgpt.codex.cli.path: /home/yourname/.nvm/versions/node/v22.14.0/bin/codex不同版本的扩展配置项名称可能从chatgpt.codex.cli.path变成codex.path最靠谱的做法是打开设置面板直接搜索 “codex”把看到的路径配置项填进去。方案 C把 npm 全局目录写进系统级环境变量。sudo nano /etc/environment在文件末尾加上PATH/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/yourname/.nvm/versions/node/v22.14.0/bin改完需要注销重新登录甚至重启一下桌面会话才生效比较重。三种方案里我最推荐方案 A也就是软链接。它简单直接不影响系统其他配置即使以后 nvm 版本变了重新指一下就完事。5.4 完整排查链路速查表症状先查什么修复方向终端codexcommand not foundnpm ls -g openai/codex重装检查 nvm 是否加载终端能用GUI 找不到which codex、npm config get prefix软链接到 /usr/local/binGUI 能识别路径但启动失败codex --version检查 Node 版本是否匹配报错提到 authcat ~/.codex/auth.json重新运行codex登录6. 接入其他 LLMOllama 与 CC Switch 配合6.1 为什么要在终端里接本地模型官方工具默认连的是 OpenAI 和 Anthropic 的云端服务但很多场景下你不想把所有代码都发到云端。比如在本地处理敏感项目、在离线内网环境搞开发或者单纯想省点订阅费这时候就需要把 Codex CLI 和 Claude Code 的模型通道切到本地模型上。好消息是这两个 CLI 工具在设计上都考虑到了自定义接入。通过 OpenAI-compatible 的接口协议本地模型也能被当作后端模型调用。6.2 Ollama 的安装与基本使用Ollama 是我在 Linux 上最常用的本地模型运行工具安装非常简单curl -fsSL https://ollama.com/install.sh | sh安装后再启动一个编码模型我用得比较多的是 Qwen2.5 Coder 系列ollama run qwen2.5-coder:7bOllama 默认监听在本地的 11434 端口并且提供了一个 OpenAI-compatible 的接口路径http://127.0.0.1:11434/v1。你的本地模型只要跑起来这个接口就能被外部工具调用。6.3 CC Switch 的定位与使用思路不少人在 Claude Code 上折腾多套配置这里推荐了解一下 CC Switch。它是一个管理 Claude Code 多重配置的社区工具核心作用是帮你快速切换不同的模型后端、API 地址和账户配置。它的底层原理并不神秘Claude Code 的配置存放在~/.claude/settings.json等文件里CC Switch 就是帮你管理这些配置文件的“切换器”。你可以预先定义好几套环境比如“官方 Claude 订阅”“Anthropic API Key”“本地 Ollama 模型”需要哪个就一键切到哪个。我自己在服务器上同时维护三套配置官方模型用于正式开发任务API Key 用于自动化脚本调用本地模型主要用于离线排查和快速实验。如果没有 CC Switch每次手动改 settings.json 反反复复很容易改错。切换前最好先备份一下原始配置cp -r ~/.claude ~/.claude.bak6.4 Codex CLI 接入自定义模型的方式Codex CLI 同样支持自定义模型。它的配置文件是~/.codex/config.toml可以通过model_provider指定一个兼容 OpenAI 接口的服务端。model qwen2.5-coder:7b model_provider ollama [model_providers.ollama] name Ollama Local base_url http://127.0.0.1:11434/v1 env_key LOCAL_API_KEY实际配置时env_key对应的环境变量可以设置一个占位值本地服务一般不做严格校验。如果你用的不是 Ollama而是其他兼容 OpenAI 协议的服务同样能把base_url换成对应地址。注意一点本地模型的能力上限和 GPT 系列差距还是明显的尤其复杂项目的多文件修改本地小模型经常理解不到位。我一般只把本地模型用于简单任务、离线环境或者敏感代码处理真要干大活还是切回官方模型。7. 几个日常使用的实在建议7.1 长期任务用 tmux 托管Codex CLI 和 Claude Code 在执行长任务时如果你直接在前台跑一旦 ssh 断掉任务就断了。这个问题用 tmux 解决最干净tmux new -s codex codex需要离开时按Ctrlb然后按d分离会话。回来继续用tmux attach -t codex。会话里的 codex 进程不会因为 ssh 断开而终止。这个习惯对服务器开发特别重要尤其是让 AI 代理在后台跑测试、构建或者批量改文件的时候你完全可以关掉终端去干别的事过一阵子再回来收结果。7.2 更新与版本锁定策略AI 编程工具迭代极快基本上一两周就会发新版本。更新命令很简单npm update -g openai/codex anthropic-ai/claude-code但频繁更新有风险。新功能往往伴随配置格式调整有时候一个晚上没看文档第二天升级完配置就不兼容了。我现在的策略是日常小任务用当前版本不变遇到重要功能或 bug 确实需要修复时再手动更新。如果想锁定版本npm 本身支持精确安装npm install -g openai/codex0.2.0版本号可以按你自己验证过的稳定版写。锁定版本后记得确认codex --version和claude --version的输出版本避免被自动更新悄悄改动。7.3 安全和权限最小化的经验最后说一个很多人会忽略的点这类 CLI 工具具有执行能力。Codex CLI 能改文件、跑命令Claude Code 也一样本质上它们操作的是你的真实环境。强烈建议不要用 root 用户跑这两个工具。单独建一个普通用户放到属于自己的项目目录里操作即使 AI 代理误操作影响面也有限。刚开始使用时权限审批弹窗不要一路回车。看清楚它要执行什么命令再决定是否允许。配置文件和数据目录注意备份。~/.codex和~/.claude这两个目录存着你的登录态和配置换机器的时候把它们一起拷走新机器恢复成本会非常低。多留意终端里面命令的 diff 输出。AI 代理改完代码后的 diff 是最该看的东西确认改动合理之后再让它继续下一步。我在部署过程中最大的感受是装这两个工具本身不难难的是理解它们运行的上下文。PATH 配置、环境变量继承、Node 版本一致性这些基础问题不搞清楚遇到报错就得靠盲猜。只要把底层的执行机制理顺了Codex CLI 和 Claude Code 在 Linux 上其实非常稳定能真正帮你在终端里扛起一堆琐碎的开发杂活。