How to Install Codex CLI on Linux: A 15-Minute Tutorial

Codex CLI 是一类跑在终端里的编码代理：你在仓库目录下用自然语言描述任务，它自己去读文件、改代码、执行命令，但每一步改动都会先问你批准。它的实际价值在于省掉重复性的打字和跳转，而不是替你判断该怎么做。

这篇是在 Ubuntu 24.04 上跑了一个月之后整理出来的安装路径，包含依赖、鉴权、配置文件，以及几个我真正遇到过的报错和处理方式。全程大约十五分钟，大部分时间在等安装。

环境要求与前置依赖

它本身是一个 Node 包，所以真正需要的依赖只有一个是 Node.js 的较新版本。除此之外：

• Debian 或 Ubuntu 系统，22.04 及以上最稳。
• Node.js 20 或更新版本，建议直接用 22。
• 一个可用的模型 API Key。
• 有 sudo 权限，能全局安装 npm 包。
• 十五分钟左右的时间，大部分用于下载。

如果你用的是 Arch 或者 Fedora，安装路径基本一致，差别只在系统包管理器那一步。

第一步：安装 Node.js

先看当前版本。

node --version

如果输出低于 20，或者提示命令不存在，就装一个新版本。Ubuntu 上用 NodeSource 是最省事的：

curl -fsSL https://deb.nodesource.com/setup_22.x -o /tmp/nodesetup.sh
sudo -E bash /tmp/nodesetup.sh
sudo apt-get install -y nodejs

装完再执行一次 node --version，应该显示 22.x。如果还是旧版本，说明系统里的旧 Node 优先出现在 PATH 前面，用 which -a node 查一下真实路径，把旧的删掉或者调整 PATH 顺序。

第二步：全局安装 CLI

sudo npm install -g @openai/codex

-g 会把可执行文件放进全局 bin 目录，因此在任何项目下都能直接调用。验证一下：

codex --version

能打印出版本号就说明装好了。如果提示 command not found，通常是 npm 的全局 bin 目录没在 PATH 里，用 npm bin -g 找到路径再手动加进 shell 配置。

第三步：配置鉴权

这类工具从环境变量读 Key，不走登录表单。临时生效：

export OPENAI_API_KEY="sk-..."

要长期生效，就把这一行写进 ~/.bashrc 或者 ~/.zshrc，然后 source 一下。两点提醒：不要把 Key 写进会被提交到仓库的 dotfile；多人共用的机器上，用独立的受限 Key 而不是主账号 Key。

第四步：在项目里试跑

先进到一个仓库，再启动。

cd ~/projects/my-app
codex

建议第一次安排一个足够安全的任务，比如：

codex "给 src/app.js 的主函数加一段说明性注释"

它会先给出改动方案，再等你的批准。这个批准环节是设计上的核心，不要养成一路回车放行的习惯，尤其是涉及删除、重命名和依赖变更的操作。

第五步：写最小可用配置

配置文件默认在 ~/.codex/config.toml，一个够用的起步版本长这样：

model = "gpt-5-codex"
approval = "on-request"
sandbox = "workspace-write"

这几行的作用是把代理限制在项目目录内，并且强制在修改前请求批准。模型名按你 Key 实际支持的填，填错的话启动时会直接报模型不可用。

常见报错与排查

• EACCES 权限错误：说明全局目录权限不对。不要用 sudo 跑所有 npm 命令去绕过，正确做法是修好 npm 全局目录的归属，或者用 nvm 管理 Node。
• command not found：npm 全局 bin 不在 PATH，见第二步的排查方式。
• 401 或 403：Key 无效、过期，或者当前 Key 没有该模型的权限。先用 curl 打一次最小请求确认。
• 卡在等待网络：公司网络或代理拦截了请求，检查 HTTPS_PROXY 是否设置正确。
• 改动超出了预期范围：把 sandbox 保持在 workspace-write，别图省事改成无沙箱模式。

国产替代方案

如果你的团队在国内，或者日常工作主要用中文，可以考虑这几个方向：通义灵码，阿里的编码助手，中文语境支持好，和本地 IDE 集成顺畅；DeepSeek，推理能力强的开放模型，可以作为编辑器代理的后端；Trae，字节做的 AI 开发环境，免费额度比较宽松；以及各类基于开源权重自建的 CLI 代理。选择标准应该是你的技术栈和合规要求，而不是单纯的知名度。

采用建议

1. 先在一个无关紧要的临时仓库里装上试跑，跑三个小任务，观察它到底改了哪些文件。
2. 把 workspace-write 沙箱和审批模式一起打开，不要为了效率关掉。
3. Key 的管理要当生产凭证对待，写进 .env 并加进 .gitignore。
4. 模型名要跟 Key 实际权限对齐，不确定就先查一遍可用模型列表。
5. 确认工作流顺畅之后再接入真实项目，代理适合做重复劳动，不适合做架构决策。

常见问题

Linux 上跑这个需要显卡吗？ 不需要。模型在云端推理，本地只要有 Node.js 和网络连接即可。

它是免费的吗？ 命令行工具本身是开源免费的，但它调用的是付费模型，实际成本按请求量结算，因此需要你自己监控用量。

想用国产工具怎么办？ 通义灵码、DeepSeek 相关的编码工具、Trae 都是可行的替代方案，中文工作流下往往更顺手。

查看当前价格 →

声明：若通过我们的链接下单，TechMinds 可能获得小额佣金，不会增加您的成本。