主题
🐧 Linux 平台
💡 快速说明
这篇是 Codex 在 Linux 下的手动安装教程，适合想自己掌握安装、配置和排错过程的用户。
如果你想少折腾、尽快跑通，建议先看 《一键配置版》。
🐧 Linux 命令行教程
先装 Node.js 和 Codex
再配置 API 并完成首次启动
如果你是第一次接触 Codex，按“准备环境 → 安装 Codex → 写入 API 配置 → 启动测试”的顺序走就行。 整篇只保留真正会用到的步骤，尽量让新手能照着做，熟手也能快速翻到关键命令。
先记住主流程
安装 Node.js → 安装 Codex CLI → 写入 API 地址和密钥 → 启动并发一条测试消息
先把这条主流程跑通，再回来看细节和 FAQ，会更轻松。
0. 开始前先确认
🧰 你能打开终端
Ubuntu、Debian、CentOS、RHEL、Fedora 等常见发行版自带的终端都可以，不需要额外准备复杂工具。
🔑 你已经准备好 API Key
没有的话，先去看 创建／修改令牌，把密钥准备好再回来。
🧭 本页是手动配置
本页命令统一使用 https://api.aicy.pro/v1。如果你走的是一键配置向导，就按向导文档填写，不要混着抄。
🐚 默认按 bash 说明
大多数 Linux 环境默认用 bash。如果你用的是 zsh，下方也给了对应写法。
1. 安装 Node.js
方法一：NodeSource（推荐 Ubuntu / Debian）
如果你用的是 Ubuntu 或 Debian，优先用这条路线，通常更省事：
bash
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs方法二：系统包管理器
如果你习惯走系统自带包管理器，也可以直接用：
bash
# Ubuntu / Debian
sudo apt update
sudo apt install -y nodejs npm
# Fedora / CentOS / RHEL
sudo dnf install -y nodejs npm验证是否安装成功
bash
node -v
npm -v能看到版本号，就说明可以继续下一步。
小提示
如果后续安装 Codex 时提示 Node.js 版本过低，优先回到这里改用较新的 LTS 安装方式。
2. 安装 Codex CLI
在终端执行：
bash
npm install -g @openai/codex如果当前环境提示权限不足，再尝试：
bash
sudo npm install -g @openai/codex验证 Codex 是否已安装到命令行
bash
codex --version如果能看到版本号，说明命令已经可用。
小提示
如果你只关心“现在能不能用”，也可以继续做完下面的 API 配置，然后直接运行 codex 进行首次测试。
3. 配置 API 地址和密钥
本页走的是手动配置，命令里统一使用：
text
https://api.aicy.pro/v1先在当前终端临时设置
bash
export OPENAI_BASE_URL="https://api.aicy.pro/v1"
export OPENAI_API_KEY="你的API密钥"⚠️ 注意
OPENAI_API_KEY 填的是你在爱次元控制台创建的令牌。
如果你还没有，可以先看 《创建／修改令牌》。
想让以后每次打开终端都自动生效
大多数 Linux 环境默认是 bash，可以执行：
bash
echo 'export OPENAI_BASE_URL="https://api.aicy.pro/v1"' >> ~/.bashrc
echo 'export OPENAI_API_KEY="你的API密钥"' >> ~/.bashrc
source ~/.bashrc如果你用的是 zsh
把上面的 ~/.bashrc 改成 ~/.zshrc 即可：
bash
echo 'export OPENAI_BASE_URL="https://api.aicy.pro/v1"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="你的API密钥"' >> ~/.zshrc
source ~/.zshrc检查变量是否生效
bash
echo "$OPENAI_BASE_URL"
[ -n "$OPENAI_API_KEY" ] && echo "OPENAI_API_KEY 已设置"如果第一行输出 https://api.aicy.pro/v1，第二行显示 OPENAI_API_KEY 已设置，说明配置已经生效。
4. 启动 Codex 并做第一次测试
新开一个终端窗口，或者继续在当前终端执行：
bash
codex进入后，先发一条最简单的测试消息，例如：
text
你好，简单介绍一下你自己。如果你准备在某个项目里使用 Codex，建议先 cd 到项目目录，再运行 codex，这样它更容易识别当前上下文。
怎么判断已经成功
只要 Codex 能正常启动，并且你能 发出一条消息并收到返回，通常就说明安装、API 配置和基础使用都已经跑通了。
❓ 常见问题
1. 提示 command not found
通常是 codex 没有进入 PATH，或者当前终端还没刷新。
可以按这个顺序检查：
bash
command -v codex
npm config get prefix
echo "$PATH"如果刚安装完，最简单的处理方式通常是：关闭终端，重新打开，再执行 codex。
2. 安装时提示权限不足
先确认是不是 npm install -g @openai/codex 这一步报错。
如果是，再尝试：
bash
sudo npm install -g @openai/codex如果你不想长期依赖 sudo，也可以改用用户目录安装：
bash
mkdir -p ~/.npm-global
npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex3. API 连接失败或启动后不能用
先检查这 3 项最容易出错的地方：
OPENAI_BASE_URL是否写成了https://api.aicy.pro/v1OPENAI_API_KEY是否复制完整- 你是不是把“一键配置版”的地址写法和本页的手动配置写法混用了
可以重新执行：
bash
echo "$OPENAI_BASE_URL"
[ -n "$OPENAI_API_KEY" ] && echo "OPENAI_API_KEY 已设置"如果还是不行，建议带上报错截图联系人工支持。
4. Node.js 版本太低或依赖缺失怎么办
先看当前版本：
bash
node -v如果版本太低，最省事的做法通常是重新安装最新的 LTS 版本。
如果安装时还提示依赖缺失，可以补下面这些常见依赖：
bash
# Ubuntu / Debian
sudo apt-get install -y build-essential
# Fedora / CentOS / RHEL
sudo dnf groupinstall "Development Tools"