Codex Router 安装指南 — macOS、Windows、Linux

本指南覆盖在 macOS、Windows 和 Linux 上安装 Codex Router 的全部方式：每种方法做什么、如何在 OAuth 与 API Key 之间选择、以及如何验证、更新和移除集成。当前推荐安装会同时加入引导式供应商设置、Electron Control Center、托盘/菜单栏应用和 macOS 桌面小组件。Codex App 支持 macOS 与 Windows；Codex CLI 支持三种平台。

前置要求

开始前请从官方来源安装以下软件。安装器不会替你静默安装包管理器或运行时。

• Codex App 或 CLI。
• Node.js 22.19 或更高版本（推荐 Node.js 24 LTS）。
• uv，或 Python 3.10+（含 venv）。
• Git，用于托管式一键安装与回滚。
• Windows 上的 Windows PowerShell 必须处于 FullLanguage 模式，且本地应用控制策略允许 Add-Type；安装器会检查这些条件，不会削弱系统策略。

选择安装方式

根据你是否需要桌面界面选择安装方式：

• 推荐完整安装——引导式供应商设置 + Control Center + 托盘/菜单栏应用 + macOS 桌面小组件。适合大多数人。
• AI Agent 安装——把一段指令粘贴进 Codex 任务，让 Agent 按仓库 AGENTS.md 流程安装。适合想要可复现安装或省事的用户。
• Homebrew 纯 CLI 安装——只安装路由器与命令行，不构建桌面前端。
• 克隆后审查安装——先克隆仓库、审阅代码，再从检出目录运行安装器。适合想先看代码再执行的人。

三种方式见下文。如果你已确定供应商，可以直接跳到模型教程。

推荐完整安装

macOS 或 Linux：

curl -fsSL https://raw.githubusercontent.com/duolahypercho/codex-router/main/install.sh \
  | sh -s -- --target codex --guided --with-tray

Windows PowerShell：

$installer = Join-Path $env:TEMP "codex-router-install.ps1"
Invoke-WebRequest https://raw.githubusercontent.com/duolahypercho/codex-router/main/install.ps1 -OutFile $installer
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $installer -Target codex -Guided -WithTray

向导按编号分步进行：用编号切换供应商列表（a 全选、n 清空、回车继续），每个供应商实时显示 ready/needs-key/needs-sign-in 状态；为你选择的、尚未接入的项目做凭据引导；最后在改动前给出确认摘要。

完成后，完全退出并重新打开 Codex，新建任务并选择路由模型，再打开 Codex Router 使用 Control Center。macOS 上可从 Spotlight 或 ~/Applications 打开；关闭窗口后菜单栏宿主仍会运行。桌面小组件已包含，可在 Settings → Dynamic Island → Desktop 开启。macOS 尚无公开 .dmg，因此命令会在本机构建应用；SwiftUI macro 与 WidgetKit target 要求完整 Xcode App，只有独立 Command Line Tools 不够。

Homebrew 纯 CLI 安装

Codex Router 尚未进入 homebrew/core。先把上游仓库添加为 tap，再安装公式：

brew tap duolahypercho/codex-router https://github.com/duolahypercho/codex-router
brew install codex-router
codex-router setup --guided

Homebrew 只安装路由器与 CLI，不包含 Electron Control Center、托盘/菜单栏应用和桌面小组件。升级使用 brew upgrade codex-router；卸载前先运行 codex-router uninstall，再运行 brew uninstall codex-router。

免凭据安装与浏览器面板

你可以把路由器以空闲状态安装——不选择任何供应商、不提示任何凭据，钥匙串、其他 CLI 的会话与 Codex 的 auth.json 一律不动：

curl -fsSL https://raw.githubusercontent.com/duolahypercho/codex-router/main/install.sh \
  | sh -s -- --target codex --no-provider --no-discovery

此模式下 Codex 流量返回本地 503 router_idle_no_provider 而非供应商或原生转发；doctor 以 warn 报告空闲状态并退出 0；新增的 stop 子命令补全了 安装 → 启动 → 状态 → doctor → 停止 → 卸载 的生命周期。不带这些标志重新运行安装会保持空闲模式。

安装完成后，用 bin/panel（Windows：codex-router.ps1 panel）在浏览器中打开面板。它与托盘是同一个应用——所有命令走同一命令表——输出中的 URL 会被脱敏，因为它携带本地调用方能力。

克隆后审查安装

git clone https://github.com/duolahypercho/codex-router.git
cd codex-router
./install.sh --target codex --guided

git clone https://github.com/duolahypercho/codex-router.git
Set-Location codex-router
./install.ps1 -Target codex -Guided

认证方式选择

Codex Router 支持两种认证方式，它们即使属于同一厂商也是独立的账户与计费体系：

API Key 只通过隐藏的终端提示（或桌面托盘的替换/移除操作）输入。永远不要把 token 或 API Key 粘贴到对话、命令行参数、shell 历史或受版本控制的文件里。

详细对比见常见问题与各模型页（DeepSeek、Kimi、GLM、Grok、Claude）。

验证安装

model_catalog_json 在 Codex 启动时加载，所以安装后必须完全退出 App、重新打开并新建任务，然后检查：

./bin/model-router codex doctor
./bin/model-router codex providers
codex debug models

doctor 对每个健康层报告 OK，对每个 FAIL 给出针对性修复。目标供应商必须同时显示 SHOW 与 ready。

更新、回滚、停用与卸载

./bin/model-router codex update
./bin/model-router codex rollback
./bin/model-router codex disable
./bin/model-router codex enable
./bin/model-router codex uninstall

update 要求可识别的 GitHub 源，且检出目录中跟踪文件没有修改——未跟踪文件不会阻塞更新，需要时可用 --force（./bin/update --force、./bin/rollback --force）丢弃跟踪文件的修改。它把上一版本保留为回滚引用。disable 只移除 Codex 集成与当前服务。uninstall 有意保留检出目录、日志、备份与供应商凭据，避免常规卸载销毁认证或恢复数据。

平台细节见 macOS 安装、Windows 安装 与 Agent 安装，出问题时看故障排查。