帮助中心 返回首页
最近更新：2025年12月15日 12:15

Codex CLI 完整配置指南

适用场景:专为 OpenAI GPT 模型优化的命令行工具,适合需要在终端使用 GPT 的开发者。

配置要点:

  • Node.js 版本:≥18(推荐 v20 或 v22)
  • Base URL:https://www.nextai-code.com/v1(必须包含 /v1 后缀)
  • 推荐模型:gpt-5-codex(代码专用)

与其他 CLI 的区别:Codex 使用 OpenAI 原生协议,因此 Base URL 必须添加 /v1 路径。

1. 环境准备

Node.js 环境 (需要 Node.js 18+)

推荐使用命令行工具安装 Node.js,以便于版本管理:

  • macOS (使用 Homebrew):

    brew install node

  • 使用 nvm (推荐跨平台):

    # 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
# 安装并使用最新 LTS 版本
nvm install --lts
nvm use --lts

  • Windows: 推荐使用 nvm-windows 或 winget:

    winget install OpenJS.NodeJS.LTS

如果以上方式均无法使用,可前往 Node.js 官网 下载安装包。

2. 配置认证

2.1 什么是 cc-switch?

cc-switch 是一个可视化的配置管理工具,用于管理 AI CLI 工具的环境变量配置。

支持的 CLI 工具:

  • Claude Code CLI
  • Codex CLI
  • Gemini CLI

主要作用:

  • 可视化配置 API Key 和 Base URL
  • 自动管理环境变量
  • 支持多个配置快速切换

2.2 安装 cc-switch

访问 GitHub Releases 下载对应版本:

  • macOS: .dmg 文件
  • Windows: .exe 安装包
  • Linux: .AppImage 或 .deb

2.3 配置令牌

  1. 访问 NextAI Code 控制台 - 令牌管理 页面。

  2. 点击 添加令牌,参照下图进行配置:

    • 名称:随意填写(例如 codex)
    • 令牌分组:选择 OpenAI 分组 (或其他 OpenAI 相关分组)
    • 过期时间:建议选择 永不过期
    • 新建数量:1

    令牌基本信息

  3. 额度与限制设置:

    • 额度:建议开启 无限额度
    • 访问限制:留空(不建议启用模型限制)
    • IP白名单:留空(不建议填写)

    额度与限制

  4. 提交后,复制生成的 sk- 开头的令牌。

2.4 使用 cc-switch 配置 API

  1. 打开 cc-switch,选择 Codex,点击 + 按钮。

    添加供应商

  2. 填写配置:

    • 选择 自定义配置
    • API Key: 你的 NextAI Code 令牌 (sk-...)
    • 请求地址: https://www.nextai-code.com/v1 (必须包含 /v1)
    • 模型: 建议不写,用默认即可

    添加配置

  3. 保存并确保状态为 已启用。

重要: GPT 使用 OpenAI 兼容协议,Base URL 必须包含 /v1 后缀

2.5 手动配置环境变量 (可选)

如果不使用 cc-switch,也可以手动配置环境变量:

export OPENAI_API_KEY="sk-..." # 你的 NextAI Code 令牌
export OPENAI_BASE_URL="https://www.nextai-code.com/v1"

注意: /v1 后缀是必需的!

3. 安装和验证 CLI

3.1 安装 Codex CLI

npm install -g @openai/codex

3.2 验证配置

安装完成后,立即测试配置是否成功:

codex --version

如果显示版本号,说明安装成功。然后测试 API 连接:

codex "写一个hello world"

如果收到代码回复,说明配置成功!

4. 常见命令与功能

模型选择

Codex CLI 支持指定模型。NextAI Code 支持最新的 OpenAI 模型:

  • gpt-5-codex (代码专用,推荐)
  • gpt-5 (通用模型)
  • gpt-5-chat (对话优化)
  • gpt-5-codex-high (高精度)
codex "复杂算法实现" --model gpt-5-codex

5. 故障排查

cc-switch 配置后 Codex 无法连接?
  1. 检查 cc-switch 状态:确保配置状态为 已启用
  2. 检查 Base URL:Codex 必须为 https://www.nextai-code.com/v1,必须包含 /v1
  3. 验证令牌:确认复制的令牌完整,格式为 sk- 开头
  4. 重启终端:配置环境变量后需要重启终端
Node.js 版本过低?

Codex CLI 需要 Node.js 18 或更高版本:

  1. 运行 node --version 查看当前版本
  2. 如果版本低于 18,使用 nvm 升级:nvm install --lts && nvm use --lts
  3. 重新安装 Codex CLI
额度不足
登录 NextAI Code 控制台 检查余额,必要时充值。
提示模型不存在?

可以在 cc-switch 的模型字段中尝试指定以下模型:

  • gpt-5-codex (代码专用,推荐)
  • gpt-5 (通用模型)
  • gpt-5-chat (对话优化)
  • gpt-5-codex-high (高精度)