CODEX

Codex 安装与接入 RootFlowAI

完整介绍 OpenAI Codex CLI、桌面 App 与 IDE 扩展的安装方法，以及通过 CC Switch 或配置文件接入 RootFlowAI 的步骤。

最后验证：2026-07-12

Codex 是 OpenAI 的编程代理，可通过 CLI、桌面 App 和 IDE 扩展使用。接入 RootFlowAI 时，API Base URL 必须填写 https://api.rootflowai.com/v1，其中 /v1 不能省略。

接入路线

路线适合场景配置位置
CC Switch希望用图形界面管理多个供应商CC Switch 的 Codex Provider
手动配置希望配置可审查、可迁移~/.codex/config.toml 与 ~/.codex/auth.json

无论选择哪条路线，都先在账户中心创建独立 API Key。不要复用生产项目的 Key，也不要把 Key 提交到 Git 仓库。

安装 Codex

CLI

macOS、Linux 和 Windows（推荐 WSL）可使用 npm 安装：

npm install -g @openai/codex
codex --version

macOS 也可使用 Homebrew：

brew install --cask codex

桌面 App 与 IDE 扩展

桌面 App 和官方 IDE 扩展请从 OpenAI Codex 官方页面获取。CLI、App 与 IDE 扩展共用 ~/.codex 下的本地配置，修改 Provider 后应完全退出并重新打开客户端。

用 CC Switch 配置

在 CC Switch 的 Codex 区域新增 Provider，填写：

配置项值
Provider NameRootFlowAI
Base URLhttps://api.rootflowai.com/v1
API Key账户中心创建的 sk-... 令牌
Model从模型价格页选择当前可用的 Codex 模型

保存并启用 Provider 后，重启 Codex。不要把 RootFlowAI 配置填到 Claude Code Provider：Claude Code 的 Base URL 规则不同。

手动配置

1. 保存 API Key

推荐让 auth.json 仅保存在本机：

{
  "OPENAI_API_KEY": "sk-你的RootFlowAI令牌"
}

文件路径：

  • macOS / Linux：~/.codex/auth.json
  • Windows：%USERPROFILE%\.codex\auth.json

2. 配置 Provider

编辑 ~/.codex/config.toml：

model = "gpt-5.5"
model_provider = "rootflowai"
model_reasoning_effort = "high"

[model_providers.rootflowai]
name = "RootFlowAI"
base_url = "https://api.rootflowai.com/v1"
wire_api = "responses"
requires_openai_auth = true

gpt-5.5 只是配置示例。模型会持续更新，请在模型价格页确认当前模型 ID 和可用分组后再填写。

验证接入

先验证 Key、地址和模型是否匹配。下面的请求只查询模型列表，不产生模型推理费用：

export ROOTFLOWAI_API_KEY="sk-你的RootFlowAI令牌"

curl https://api.rootflowai.com/v1/models \
  -H "Authorization: Bearer $ROOTFLOWAI_API_KEY"

确认列表中存在你配置的模型后，在项目目录启动：

cd /path/to/your-project
codex

进入 Codex 后先完成一个小型只读任务，例如让它解释项目目录结构。确认模型能响应，再授权修改文件或执行命令。

日常使用

项目规则

在仓库根目录添加 AGENTS.md，记录测试命令、目录边界、代码风格与禁止操作。Codex 会把它作为项目级协作规则读取。

权限与沙箱

保留默认审批和沙箱设置，按任务逐次授权。只有在隔离环境中并明确理解风险时，才使用绕过审批或扩大文件系统权限的模式。

多任务与分支

桌面 App 可同时管理多个任务。涉及并行实现时，为每个任务使用独立分支或 worktree，避免两个代理同时修改同一文件。

常见问题

返回 401 或提示登录 OpenAI

检查 ~/.codex/auth.json 是否存在 OPENAI_API_KEY，以及 requires_openai_auth = true 是否位于 [model_providers.rootflowai] 下。修改后重启 Codex。

返回 404

RootFlowAI 的 Codex Base URL 是 https://api.rootflowai.com/v1。遗漏 /v1、重复写成 /v1/v1，或把网页地址 rootflowai.com 当作 API 地址都会导致请求失败。

模型不可用

先查询 /v1/models，再检查 API Key 是否允许目标模型、账户分组是否匹配。模型 ID 必须完全一致。

配置修改后没有生效

完全退出 CLI、App 或 IDE 后重新打开。若使用 CC Switch，确认当前启用的是 RootFlowAI 的 Codex Provider，而不是另一个供应商。

下一步