OpenAI Codex CLI
OpenAI Codex CLI 安装与配置教程 — 在 Windows、macOS、Linux 上安装终端 AI 编程助手，通过 OpenAI 兼容接口对接 AI Router。
项目介绍
Codex CLI 是一个来自 OpenAI 的编码代理，可在你的计算机上本地运行，在命令行中编辑代码、生成补丁并运行命令。
本页介绍如何把 Codex CLI 指向 AI Router（一个 OpenAI 兼容的统一 AI 网关/中转）。配置完成后，你只需一个 AI Router API Key + 一个 Base URL，即可在 Codex CLI 中调用 AI Router 上配置的多家模型。
Codex CLI 特性
| 功能分类 | 特性 |
|---|---|
| 终端式编码助手 | 基于终端的交互式编码助理，用于在命令行中编辑代码、生成补丁并运行命令。 |
| 工具驱动架构 | 提供 apply_patch、shell、update_plan 等工具，用于对仓库文件和操作进行可控修改。 |
| 原子补丁编辑 | 使用专门的补丁格式通过 apply_patch 原子地添加/更新/删除文件，便于审计与回滚。 |
| 沙箱与审批 | 支持沙箱策略（如 workspace-write、read-only）和审批模式（on-request、on-failure、never），控制写入与网络访问权限。 |
| 计划追踪 | update_plan 用于列出步骤并跟踪状态，始终只保留一个 in_progress 步骤以保持明确进度。 |
| 安全约束 | 遵循严格规则（不随意更改无关文件、不执行破坏性命令），敏感操作需要用户批准。 |
| 跨平台 | 支持 Windows（建议配合 WSL2）、macOS、Linux。 |
准备工作：获取 AI Router 接入信息
在配置 Codex CLI 之前，请先从你的 AI Router 控制台拿到以下两项信息：
Base URL（接入地址）
OpenAI 兼容接口地址，形如 https://ai.sammier.com/v1。请以你自己部署或使用的 AI Router 实例地址为准。
API Key（密钥）
形如 sk-... 的 AI Router 密钥。妥善保管，不要提交到代码仓库或公开分享。
使用前请确认
修改接口地址后，Codex CLI 调用的所有模型（包括其内置预设模型）都会走你配置的接入点。请仅使用你自己部署的 AI Router，或确认服务方具备合法上游授权与合规义务的 AI Router 服务，不要将来源不明的 API 地址或密钥接入生产环境。
安装 Codex CLI
在 Windows 上推荐使用 WSL2 以获得最佳体验。
安装 WSL2 并重启
在 PowerShell（建议以管理员身份运行）中执行：
wsl --install安装完成后重启计算机。
在 WSL 中安装 Node.js
打开 WSL：
wsl使用 nvm 安装 Node.js（版本要求以 Codex 官方说明为准）：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
nvm install 22全局安装 Codex CLI
npm i -g @openai/codexWindows 注意事项
- 建议使用 PowerShell 而不是 CMD
- 如果遇到权限问题，尝试以管理员身份运行
- 某些杀毒软件可能会误报，需要添加白名单
全局安装 Codex CLI
npm install -g @openai/codex如遇权限问题可使用 sudo：
sudo npm install -g @openai/codex验证安装
codex --version显示版本号即安装成功。
macOS 注意事项
- 如果遇到权限问题，可能需要使用
sudo - 建议使用 Terminal 或 iTerm2
- 若系统安全设置阻止运行，可在「系统设置 → 隐私与安全性」中选择「仍要打开/允许」
安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs全局安装 Codex CLI
npm install -g @openai/codex如遇权限问题可使用 sudo，或将 npm 全局目录设为用户目录：
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH验证安装
codex --version显示版本号即安装成功。
Linux 注意事项
- 某些发行版可能需要额外依赖：
sudo apt install build-essential（Ubuntu/Debian）或sudo dnf groupinstall "Development Tools"（CentOS/RHEL） - 确保你的用户对 npm 全局目录有写权限
配置 Codex CLI 对接 AI Router
Codex CLI 支持自定义 OpenAI 兼容的模型提供方。把提供方的 Base URL 指向 AI Router，密钥使用你的 AI Router API Key 即可。
1. 配置 API Key
Codex CLI 通过环境变量读取密钥。把它设置为你的 AI Router 密钥（占位示例为 sk-...，请替换为你自己的真实密钥）。
export OPENAI_API_KEY="sk-..."如需持久化，可写入 ~/.bashrc 或 ~/.zshrc：
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc
source ~/.zshrc[Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'sk-...', 'User')设置后请重新打开终端使其生效。
2. 配置模型提供方（Base URL）
编辑 Codex 的配置文件 ~/.codex/config.toml（不存在则新建），加入一个指向 AI Router 的 OpenAI 兼容提供方：
# ~/.codex/config.toml
# 默认使用的提供方与模型
model_provider = "code-router"
model = "gpt-4o" # 改成你在 AI Router 中实际开通/分组的模型名
[model_providers.code-router]
name = "AI Router"
# AI Router 的 OpenAI 兼容接口地址（以你的实例为准）
base_url = "https://ai.sammier.com/v1"
# 从名为 OPENAI_API_KEY 的环境变量读取密钥
env_key = "OPENAI_API_KEY"字段说明
base_url：填 AI Router 的 OpenAI 兼容地址（https://ai.sammier.com/v1）。请替换为你自己部署或使用的实例地址。env_key：指定读取密钥的环境变量名，对应上一步设置的OPENAI_API_KEY。model：填你在 AI Router 中可用的模型名（具体可用模型与分组以你的 AI Router 控制台为准）。
配置截图（占位）
（此处原为旧产品配置界面截图，截图待补 / screenshot TBD。）
开始使用
完成配置后即可启动 Codex CLI：
# 在任意目录直接启动
codex
# 或先进入你的项目目录再启动
cd /path/to/your/project
codexWindows（WSL）下访问挂载盘路径示例：
cd /mnt/c/path/to/your/project。
启动后可在交互界面中：
- 输入
/model切换模型（需是 AI Router 中可用的模型名）。 - 按需设置写入/审批权限：例如允许 Codex 直接修改文件，或要求每次修改手动授权。
常见问题
反馈
使用 AI Router 过程中遇到问题，可在源码仓库提交 issue：https://github.com/ssgzy/Router-new-api
这篇文档对您有帮助吗？
最后更新于