跳到主要内容

Codex Linux 使用指南

(一) 安装 Node.js 环境​

Codex 需要 Node.js 环境才能运行。

Linux 安装方法​

方法一：使用官方仓库（推荐）

# 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

# 安装 Node.js
sudo apt-get install -y nodejs

方法二：使用系统包管理器

虽然版本可能不是最新的，但对于基本使用已经足够：

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# CentOS/RHEL/Fedora
sudo dnf install nodejs npm
Linux 注意事项
  • 某些发行版可能需要安装额外的依赖
  • 如果遇到权限问题，使用 sudo
  • 确保你的用户在 npm 的全局目录有写权限

验证安装是否成功​

安装完成后，打开终端，输入以下命令：

node --version
npm --version

如果显示版本号，说明安装成功了！

(二) 安装 Codex​

安装 Codex​

打开终端，运行以下命令：

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

如果遇到权限问题，可以使用 sudo：

sudo npm install -g @openai/codex

验证 Codex 安装​

安装完成后，输入以下命令检查是否安装成功：

codex --version

如果显示版本号，恭喜你！Codex 已经成功安装了。

(三) 配置 Codex​

方法一（推荐）：通过配置文件设置​

在 ~/.codex 目录下创建配置文件（如果目录不存在则创建）。

创建 config.toml 文件，添加以下内容：

disable_response_storage = true
model = "gpt-5.2"
model_reasoning_effort = "high"
model_provider = "bytecatcode"

[model_providers.bytecatcode]
base_url = "https://bytecatcode.org/v1"
name = "bytecatcode"
requires_openai_auth = true
wire_api = "responses"

创建 auth.json 文件，添加以下内容：

{
  "OPENAI_API_KEY": "你的API密钥"
}

方法二：通过环境变量设置​

临时设置（当前会话）

export OPENAI_BASE_URL="https://bytecatcode.org/v1"
export OPENAI_API_KEY="你的API密钥"

永久设置

对于 bash（默认）：

echo 'export OPENAI_BASE_URL="https://bytecatcode.org/v1"' >> ~/.bashrc
echo 'export OPENAI_API_KEY="你的API密钥"' >> ~/.bashrc
source ~/.bashrc

对于 zsh：

echo 'export OPENAI_BASE_URL="https://bytecatcode.org/v1"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="你的API密钥"' >> ~/.zshrc
source ~/.zshrc

验证环境变量​

echo $OPENAI_BASE_URL
echo $OPENAI_API_KEY

(四) 开始使用 Codex​

启动 Codex​

配置完成后，在终端中输入以下命令启动 Codex：

codex

首次启动时，Codex 会进行初始化配置。

基本使用​

  • 交互模式：直接输入 codex 进入交互式对话
  • 指定项目：在项目目录下运行 codex，Codex 会自动识别项目上下文
  • 退出程序：输入 exit 或按 Ctrl+C 退出

(五) 常见问题解决​

1. 命令未找到错误​

问题：运行 codex 时提示 "command not found"

解决方法：

# 检查 npm 全局安装路径
npm config get prefix

# 确保该路径在 PATH 中
echo $PATH

# 如果不在，添加到配置文件
# 对于 bash
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 对于 zsh
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. 权限问题​

问题：安装时提示权限不足

解决方法：

# 方法一：使用 sudo 安装
sudo npm install -g @openai/codex

# 方法二：配置 npm 使用用户目录（推荐）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 然后重新安装
npm install -g @openai/codex

3. API 连接失败​

问题：Codex 无法连接到 API 服务

解决方法：

# 检查环境变量是否正确设置
echo $OPENAI_BASE_URL
echo $OPENAI_API_KEY

# 测试网络连接
curl -I https://bytecatcode.org

# 重新设置环境变量
export OPENAI_BASE_URL="https://bytecatcode.org/v1"
export OPENAI_API_KEY="你的API密钥"

4. 更新 Codex​

问题：如何更新到最新版本

解决方法：

# 更新 Codex
npm update -g @openai/codex

# 或者重新安装
npm install -g @openai/codex

5. Node.js 版本过低​

问题：提示 Node.js 版本不兼容

解决方法：

# Ubuntu/Debian 更新 Node.js
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# CentOS/RHEL/Fedora 更新 Node.js
sudo dnf module install nodejs:lts

# 验证版本（需要 18 或更高版本）
node --version

6. 依赖缺失问题​

问题：运行时提示缺少依赖

解决方法：

# Ubuntu/Debian
sudo apt-get install build-essential

# CentOS/RHEL/Fedora
sudo dnf groupinstall "Development Tools"

# 然后重新安装 Codex
npm install -g @openai/codex