欢迎使用 ModelSet 原版代理服务！本指南将帮助你在 Linux 系统上配置 Codex CLI。ModelSet 订阅可在 Claude Code、Codex、Cursor 等多款官方工具客户端间通用。

前置要求

  • 主流 Linux 发行版（Ubuntu、Debian、CentOS、Fedora 等）
  • Node.js 环境（版本 18 或更高）
  • 有效的 ModelSet API 密钥

步骤 1：安装 Node.js 环境

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

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

Ubuntu/Debian 系统：

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

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

CentOS/RHEL/Fedora 系统：

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

# 安装 Node.js
sudo dnf install -y nodejs

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

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

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

# CentOS/RHEL/Fedora
sudo dnf install nodejs npm

# Arch Linux
sudo pacman -S nodejs npm

验证 Node.js 安装

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

bash 
node --version
npm --version

Linux 注意事项：某些发行版可能需要安装额外的依赖（如 build-essential）；如果遇到权限问题，使用 sudo 命令；确保你的用户在 npm 的全局目录有写权限。

步骤 2：安装 Codex CLI

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

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

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

bash 
sudo npm install -g @openai/codex

这个命令会从 npm 官方仓库下载并安装最新版本的 Codex CLI。安装完成后验证：

bash 
codex -V

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

如果 codex 命令未找到，可能需要重新加载 shell 配置或重启终端；某些发行版需要手动添加 npm 全局 bin 目录到 PATH。

步骤 3：获取 ModelSet API 密钥

登录 ModelSet 控制台，进入「API 密钥」页面，创建专属有效密钥，用于后续环境变量配置。添加完令牌后会得到一串 sk- 开头的密钥，点击复制：

在 ModelSet 控制台创建 API 密钥 复制生成的 sk- 开头密钥

添加 key 时请选择对应的分组，不要选择 default，否则生成的 key 没法用。建议非订阅用户选择 codex-normal 分组；订阅用户自动升级为 codex-vip 分组，创建 key 时选择 codex-vip 分组。

步骤 4：创建配置目录

在终端中运行以下命令创建 Codex 配置目录：

bash 
# 删除旧的配置目录（如果存在）
rm -rf ~/.codex

# 创建新的配置目录
mkdir ~/.codex

步骤 5：创建 auth.json 配置文件

在终端中运行以下命令创建认证配置文件：

bash 
# 创建 auth.json 文件
cat > ~/.codex/auth.json << 'EOF'
{
  "OPENAI_API_KEY": "你的API密钥"
}
EOF

记得将 你的API密钥 替换为在上方 API Keys 标签页中创建的实际密钥。

手动创建方式：

bash 
# 使用 nano 编辑器
nano ~/.codex/auth.json

# 或使用 vim 编辑器
vim ~/.codex/auth.json

输入以下内容：

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

保存文件后退出编辑器（nano: Ctrl+O 保存，Ctrl+X 退出；vim: 按 ESC，输入 :wq 保存并退出）。

步骤 6：创建 config.toml 配置文件

在终端中运行以下命令创建配置文件：

bash 
# 创建 config.toml 文件
cat > ~/.codex/config.toml << 'EOF'
model_provider = "ModelSet"
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.ModelSet]
name = "ModelSet"
base_url = "https://ai.modelset.top/v1"
wire_api = "responses"
requires_openai_auth = true
EOF

手动创建方式：

bash 
# 使用 nano 编辑器
nano ~/.codex/config.toml

# 或使用 vim 编辑器
vim ~/.codex/config.toml

输入以下内容：

toml 
model_provider = "ModelSet"
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.ModelSet]
name = "ModelSet"
base_url = "https://ai.modelset.top/v1"
wire_api = "responses"
requires_openai_auth = true

保存文件后退出编辑器。

验证配置

可以通过以下命令验证配置文件是否创建成功：

bash 
# 查看配置目录内容
ls -la ~/.codex

# 查看 auth.json 内容
cat ~/.codex/auth.json

# 查看 config.toml 内容
cat ~/.codex/config.toml

预期输出：应该能看到 auth.json 和 config.toml 两个文件，内容与上面设置的一致。

步骤 7：开始使用 Codex

现在你可以开始使用 Codex CLI 了！

bash 
# 启动 Codex
codex

# 在特定项目中使用
cd /path/to/your/project
codex

配置推理预算（可选）

Codex 支持不同的推理预算级别，你可以在 config.toml 中修改 model_reasoning_effort 参数。修改后保存文件，重启 Codex 即可生效。

可用模型（ModelSet）

你可以在 config.toml 的 model 字段中填写模型 ID。如需切换模型，只需修改 model = "..." 后重启 Codex CLI。

Linux 常见问题解决

1. 安装时提示权限错误

方法一：使用 sudo

bash 
sudo npm install -g @openai/codex

方法二：配置 npm 使用用户目录

bash 
# 创建全局安装目录
mkdir -p ~/.npm-global

# 配置 npm 使用新目录
npm config set prefix ~/.npm-global

# 将路径添加到 shell 配置文件
# 对于 Bash
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 对于 Zsh
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 对于 Fish
echo 'set -x PATH ~/.npm-global/bin $PATH' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

2. 缺少依赖库

某些 Linux 发行版需要安装额外依赖：

bash 
# Ubuntu/Debian
sudo apt install build-essential

# CentOS/RHEL
sudo dnf groupinstall "Development Tools"

# Arch Linux
sudo pacman -S base-devel

3. 配置文件权限问题

bash 
# 确保配置文件权限正确
chmod 600 ~/.codex/auth.json
chmod 644 ~/.codex/config.toml

# 确保目录权限正确
chmod 755 ~/.codex

4. 找不到 .codex 目录

Linux 默认隐藏以点开头的文件夹。在终端中直接访问：

bash 
# 进入配置目录
cd ~/.codex

# 列出隐藏文件
ls -la ~/

# 或直接编辑文件
nano ~/.codex/auth.json

在文件管理器中按 Ctrl + H 切换显示/隐藏文件（适用于大多数文件管理器）。

5. codex 命令未找到

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

# 确保该路径的 bin 目录在 PATH 中
echo $PATH

# 如果不在，添加到 PATH
# 对于 Bash
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 对于 Zsh
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 对于 Fish
echo 'set -x PATH (npm config get prefix)/bin $PATH' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

6. Codex 无法连接到服务

确保：API 密钥正确无误；config.toml 中的 base_url 配置正确；网络连接正常；防火墙未阻止 Codex 访问网络。检查防火墙设置：

bash 
# Ubuntu/Debian (UFW)
sudo ufw status

# CentOS/RHEL (firewalld)
sudo firewall-cmd --list-all

# 如果需要，允许出站 HTTPS 连接
sudo ufw allow out 443/tcp  # Ubuntu/Debian

7. SELinux 权限问题（CentOS/RHEL）

bash 
# 检查 SELinux 状态
getenforce

# 临时关闭 SELinux
sudo setenforce 0

# 或者永久关闭（不推荐，建议配置正确的 SELinux 策略）
sudo vi /etc/selinux/config
# 将 SELINUX=enforcing 改为 SELINUX=permissive

8. WSL（Windows Subsystem for Linux）注意事项

如果在 WSL 中使用 Codex CLI：

  • 确保 WSL 版本为 WSL2（性能更好）
  • 配置文件路径为 Linux 风格：~/.codex/
  • 可能需要配置 Windows 防火墙允许 WSL 访问网络
  • 推荐将项目文件存放在 Linux 文件系统中（性能更好）
powershell 
# 检查 WSL 版本
wsl -l -v

# 查看当前发行版
cat /etc/os-release

技术支持

安装配置过程中遇到任何问题，可扫码添加官方客服微信，获取一对一技术支持。

官方客服微信二维码

🎉 配置完成！至此你已成功部署 Codex CLI，可自由切换各大 AI 模型，享受高效 AI 编程辅助体验。

Codex Linux 安装配置

免费获取 API Key

非订阅用户选 codex-normal，订阅用户选 codex-vip

前往控制台