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

前置要求

  • macOS 10.15 (Catalina) 或更高版本
  • Node.js 环境（版本 18 或更高）
  • 有效的 ModelSet API 密钥

步骤 1：安装 Node.js 环境

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

方法一：使用 Homebrew（推荐）

如果你已经安装了 Homebrew，使用它安装 Node.js 会更方便：

bash 
# 更新 Homebrew
brew update

# 安装 Node.js
brew install node

如果尚未安装 Homebrew：访问 https://brew.sh/ 或在终端运行以下命令安装：

bash 
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

方法二：官网下载

  1. 访问 https://nodejs.org/
  2. 点击 "LTS" 版本进行下载（推荐长期支持版本）
  3. 下载完成后打开 .pkg 文件
  4. 按照安装向导完成安装，保持默认设置即可

验证 Node.js 安装

安装完成后，打开终端（Terminal 或 iTerm2），输入以下命令：

bash 
node --version
npm --version

macOS 注意事项：如果遇到权限问题，可能需要使用 sudo 命令；首次运行某些命令时，系统可能会提示安全设置；推荐使用 Terminal 或 iTerm2 作为终端工具。

步骤 2：安装 Codex CLI

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

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

# 遇到权限问题时提权安装
sudo npm install -g @openai/codex

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

bash 
codex -V

如果显示版本号，恭喜你！Codex CLI 已经成功安装了。如果提示找不到命令，尝试重新打开终端窗口；某些情况下可能需要重新加载 shell 配置文件。

步骤 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 
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

bash 
# 直接启动
codex

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

配置推理预算（可选）

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

可用模型（ModelSet）

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

macOS 常见问题解决

1. 安装时提示 "permission denied" 错误

方法一：使用 sudo

bash 
sudo npm install -g @openai/codex

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

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

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

# 将路径添加到 shell 配置文件
# 确定你使用的 shell
echo $SHELL

# 如果是 zsh（macOS Catalina 及以上）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 如果是 bash（早期版本 macOS）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bash_profile
source ~/.bash_profile

2. macOS 安全设置阻止运行

如果系统提示「无法打开，因为无法验证开发者」：

  1. 打开系统偏好设置 → 安全性与隐私
  2. 在「通用」标签下，点击「仍要打开」或「允许」

或者在终端中运行（用完建议恢复）：

bash 
# 临时允许所有来源（不推荐）
sudo spctl --master-disable

# 使用完后建议恢复
sudo spctl --master-enable

3. 配置文件权限问题

如果遇到配置文件无法读取的问题：

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

4. 找不到 .codex 目录

macOS 默认隐藏以点开头的文件夹。方法一：在 Finder 中按 Command + Shift + . 切换显示/隐藏文件；方法二：在终端中直接访问：

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

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

5. Codex 无法连接到服务

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

6. Homebrew 安装缓慢或失败

如果 Homebrew 安装很慢，可以使用国内镜像：

bash 
# 使用清华大学镜像
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"

Apple Silicon 芯片注意事项

如果你使用的是搭载 Apple Silicon（M1/M2/M3/M4）的 Mac：

  • Node.js 和 Codex CLI 都已完全支持 Apple Silicon
  • 如果遇到兼容性问题，可以尝试使用 Rosetta 2
  • 某些第三方包可能需要额外配置
bash 
# 查看系统架构
uname -m
# arm64 表示 Apple Silicon，x86_64 表示 Intel

技术支持

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

官方客服微信二维码

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

Codex macOS 安装配置

免费获取 API Key

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

前往控制台