Ubuntu 安装 OpenAI Codex CLI 完整指南

Codex CLI 是 OpenAI 推出的轻量级终端编程代理。它直接在终端中运行，能读取你的代码库、执行 Shell 命令、编辑文件、运行测试、调试问题——全部通过自然语言对话完成。可以把它想象成 ChatGPT 原生集成到了你的终端工作流中。

本文覆盖 Ubuntu 下的所有安装方式，从零基础到进阶用户都适用。

1. 环境要求

开始之前，确认你的系统满足以下条件：

要求	最低配置
Ubuntu	20.04 及以上
内存	4 GB+（推荐 8 GB+）
处理器	x64 或 ARM64
网络	需要互联网连接
Node.js	18.0+（仅 npm 安装方式需要）
账户	OpenAI 账户（ChatGPT Plus/Pro/Team/Enterprise）或 API Key

2. 安装方式

方式一：官方安装脚本（推荐）

OpenAI 提供了一键安装脚本，能自动检测操作系统和 CPU 架构，下载对应的二进制文件并放入 PATH。

curl -fsSL https://chatgpt.com/codex/install.sh | sh

脚本执行完毕后即安装完成。启动 Codex CLI：

codex

提示： 想先看看脚本内容？可以先 pipe 到 less 预览：
curl -fsSL https://chatgpt.com/codex/install.sh | less

方式二：npm

如果你已经有 Node.js 环境，npm 是最灵活的方式：

# 如果还没有 Node.js 18+，先安装（以 Node.js 22.x 为例）
# curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
# sudo apt install -y nodejs

# 全局安装 Codex CLI
npm install -g @openai/codex

# 验证安装
codex --version

后续升级：

npm install -g @openai/codex@latest

⚠️ 不要用 npm update -g——它会遵循原始安装时的 semver 范围，可能不会拉到最新版本。

方式三：二进制下载（无需 Node.js）

如果你想用一个独立的、不带任何运行时依赖的二进制文件，可以直接从 GitHub Releases 下载：

x86_64 系统：

wget https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
sudo mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex
sudo chmod +x /usr/local/bin/codex

ARM64 系统：

wget https://github.com/openai/codex/releases/latest/download/codex-aarch64-unknown-linux-musl.tar.gz
tar -xzf codex-aarch64-unknown-linux-musl.tar.gz
sudo mv codex-aarch64-unknown-linux-musl /usr/local/bin/codex
sudo chmod +x /usr/local/bin/codex

方式四：Homebrew

如果你在 Linux 上使用 Homebrew：

brew install --cask codex

3. 认证登录

首次运行时，Codex CLI 需要认证。有两种方式：

ChatGPT 登录（推荐给订阅用户）

codex login

浏览器会自动打开 OpenAI 登录页面，登录后使用额度将计入你的 ChatGPT 订阅（Plus、Pro、Team、Edu 或 Enterprise）。无需 API Key。

API Key

如果你使用 API Key：

export OPENAI_API_KEY="sk-proj-..."

# 写入 shell 配置文件持久化
echo 'export OPENAI_API_KEY="sk-proj-..."' >> ~/.bashrc
source ~/.bashrc

然后启动：

codex

4. 初次使用

进入项目目录后启动：

cd ~/my-project
codex

Codex CLI 会自动扫描代码库，然后进入交互界面。试试这些指令：

配置文件

Codex CLI 的配置存放在 ~/.codex/config.toml，可以自定义默认模型、审批模式和 MCP 服务器等设置。

5. 升级更新

安装方式	升级命令
一键脚本	重新运行安装脚本（自动获取最新版）
npm	`npm install -g @openai/codex@latest`
二进制	下载新版压缩包并替换二进制文件
Homebrew	`brew upgrade codex`

6. 卸载

安装方式	卸载命令
一键脚本	`sudo rm -f /usr/local/bin/codex ~/.local/bin/codex`
npm	`npm uninstall -g @openai/codex`
二进制	`sudo rm -f /usr/local/bin/codex`
Homebrew	`brew uninstall codex`

如需同时清理配置文件：

rm -rf ~/.codex

7. 常见问题

“codex: command not found”

一键脚本 / 二进制安装： 检查 /usr/local/bin 是否在 PATH 中：echo $PATH。如果没有，将 export PATH="/usr/local/bin:$PATH" 添加到 ~/.bashrc。
npm： 运行 npm list -g --depth=0 | grep codex 确认全局包已安装。
尝试打开新终端或运行 hash -r 刷新命令缓存。

认证失败

确认 OpenAI 账户有有效订阅（Plus、Pro、Team、Edu、Enterprise），或 API Key 有效且有余额。
尝试 codex logout 然后 codex login 重新认证。

Linux 权限错误

如果使用 npm 全局安装时遇到 EACCES 错误：

# 方案一：使用 nvm 管理 Node.js（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 22
nvm use 22
npm install -g @openai/codex

# 方案二：修复 npm 权限
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex

Codex 启动但无法读取文件

Codex 需要文件系统的读写权限。确保当前目录属于你的用户且有读写权限。在远程服务器上，确认文件系统没有被挂载为只读。

总结

安装方式	适合人群	需要 Node.js	自动更新
一键脚本	大多数用户，简单快捷	❌	❌（手动重跑）
npm	Node.js 开发者	✅	❌
二进制	追求最小依赖	❌	❌
Homebrew	Homebrew 用户	❌	❌

对于大多数 Ubuntu 用户，官方一键安装脚本是最简单的选择——一条命令搞定，无需管理依赖，自动检测架构。

Codex CLI 是开源项目（GitHub，Apache-2.0 协议），目前已有超过 94,000 Star，仍在积极开发中。无论是调试遗留代码库、生成样板代码，还是探索一个新仓库，它都是你终端工具箱中的得力助手。

1. 环境要求#

2. 安装方式#

方式一：官方安装脚本（推荐）#

方式二：npm#

方式三：二进制下载（无需 Node.js）#

方式四：Homebrew#

3. 认证登录#

ChatGPT 登录（推荐给订阅用户）#

API Key#

4. 初次使用#

配置文件#

5. 升级更新#

6. 卸载#

7. 常见问题#

“codex: command not found”#

认证失败#

Linux 权限错误#

Codex 启动但无法读取文件#

总结#