Linux 服务器安装 Codex CLI：Node.js 与 npm 环境配置
本文面向 Ubuntu 或 Debian Linux 服务器，说明如何准备 Node.js 与 npm 环境、安装 Codex CLI、完成登录并进行基本验证。示例默认使用普通用户操作，服务器已有 sudo 权限和稳定的出站网络。
安装前检查
先确认系统版本、当前用户和已有的 Node.js 环境：
cat /etc/os-release
whoami
node --version
npm --version
如果 node 或 npm 尚未安装，或者 Node.js 主版本低于 20，继续执行下面的环境安装步骤。已经满足版本要求时，可以直接跳到配置 npm 全局安装目录。
安装 Node.js 与 npm
使用系统软件源
在 Ubuntu 或 Debian 上，先尝试系统软件源：
sudo apt-get update
sudo apt-get install -y nodejs npm
安装后再次检查版本：
node --version
npm --version
Codex CLI 建议使用 Node.js 20 或更高版本的 LTS 发行版。如果系统软件源提供的版本过旧，不要混用多个 Node.js 安装方式，改用下面的 LTS 软件源方案。
使用 LTS 软件源
下面示例安装 Node.js 22 LTS。执行前应根据服务器发行版和组织软件源策略确认版本；Node.js 安装包会一并提供 npm：
sudo apt-get update
sudo apt-get install -y ca-certificates curl
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
验证环境：
node --version
npm --version
which node
which npm
如果服务器无法访问外部软件源，应使用组织内部镜像或操作系统维护的软件包，不要把安装脚本内容复制到文章或提交记录中。
配置 npm 全局安装目录
不要为了安装 CLI 长期使用 root 用户，也不要直接用 sudo npm install -g 覆盖系统目录。为当前用户设置 npm 全局目录：
mkdir -p "$HOME/.local"
npm config set prefix "$HOME/.local"
printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$HOME/.profile"
. "$HOME/.profile"
确认 npm 使用了新的目录：
npm config get prefix
printf '%s\n' "$PATH"
如果服务器使用其他 shell，应把 PATH 配置放入该 shell 的登录配置文件，并重新打开会话后再安装 CLI。
安装 Codex CLI
使用 npm 全局安装 Codex CLI：
npm install --global @openai/codex
验证命令是否可用：
codex --version
codex --help
如果出现 EACCES，先检查 npm config get prefix 和 PATH 是否指向当前用户的全局目录。不要通过扩大整个系统目录权限来绕过问题。
完成认证
在服务器上执行：
codex login
按照终端提示完成认证。服务器没有图形浏览器时，先查看当前版本支持的认证方式：
codex login --help
再按帮助信息选择设备授权或其他非图形流程。不同版本和组织策略可能提供不同的登录选项，因此不要在脚本、文章、shell 历史或仓库中写入访问令牌、API 密钥、Cookie 或完整认证日志。
基本验证
登录完成后，在目标项目目录中运行交互式 CLI：
cd project
codex
也可以先查看可用子命令和参数：
codex --help
首次验证建议使用只读任务，例如让 Codex 解释项目结构或检查配置，不要一开始就执行删除文件、修改部署配置或访问生产凭据的操作。
服务器使用建议
- 使用专门的普通用户运行 Codex CLI，不要使用 root 账号处理项目文件。
- 为项目目录设置最小必要权限，并在服务器防火墙和网络策略中限制不必要的出站访问。
- 将认证信息交给官方登录流程或受控的环境变量管理系统，不要把敏感值写入命令行参数。
- 使用
tmux或其他会话管理工具保持 SSH 断开后的终端状态，但仍应确认会话中的任务和权限范围。 - 升级前先查看当前版本和变更说明，再执行
npm update --global @openai/codex。
常见问题
codex: command not found
检查 npm 全局目录和 PATH：
npm config get prefix
command -v codex
printf '%s\n' "$PATH"
如果全局目录不在 PATH 中，重新加载当前用户的 shell 配置文件，或在当前会话中临时导出正确的 PATH。
Node.js 版本过低
使用 node --version 确认主版本。如果低于 20，先升级到受支持的 LTS 版本，再重新安装 Codex CLI，避免在旧运行时上反复重试 npm 安装。
npm 报权限错误
确认当前用户拥有 $HOME/.local 的写权限，并检查 npm prefix 是否指向该目录。不要把 npm 全局目录改成一个所有用户都可写的系统目录。
SSH 会话中无法打开浏览器
在服务器上运行 codex login --help，按照当前版本列出的非图形认证流程操作。不要把认证链接、一次性代码或令牌粘贴到公开文档、工单或终端截图中。