在 macOS 上安装 Codex Router（Codex App 与 CLI）

本页讲解如何在 macOS 上为 Codex App 或 CLI 安装 Codex Router，包括可选的菜单栏控制面板，以及在打开模型选择器之前如何验证一切正常。

macOS 前置要求

• Codex App 或 Codex CLI。
• Node.js 22.19 或更高版本（推荐 Node.js 24 LTS）。
• uv，或 Python 3.10+（含 venv）。
• Git，用于托管式一键安装与回滚。

引导式安装

打开「终端」并运行：

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

向导让你按编号切换供应商，实时显示每个供应商的 ready/needs-key/needs-sign-in 状态，并为所选项目完成凭据引导，最后在安装前给出确认摘要。

永远不要把密钥粘贴进命令。 API Key 通过隐藏的终端提示输入，安装器绝不会动你的 ChatGPT 登录或现有 Codex 设置。

桌面伴侣（可选）

在 macOS 上，引导式安装可以构建并启动原生菜单栏控制面板，以原生玻璃界面显示 Codex 健康状态、各供应商用量、配额卡片与供应商控制。随时运行：

./bin/model-router-tray

应用包会安装到 ~/Applications，需要 Swift 工具链；缺少工具链时安装会跳过该步骤并给出指引，而不是失败。首次启动时托盘会把自己注册为登录项以便重启后自动打开；可在其设置页或「系统设置 › 登录项」中关闭。

macOS 上的 Kimi OAuth

如果你选择 Kimi OAuth，引导式安装会复用官方 Kimi Code CLI 会话；CLI 存在时会提示运行登录命令：

kimi login

路由器从 $KIMI_CODE_HOME 或 ~/.kimi-code 读取官方凭据，并在跨进程锁下自动刷新。不要把 OAuth token 复制进 Codex 配置、密钥文件或环境变量。

验证安装

Codex 只在启动时加载 model_catalog_json，因此安装后：

1. 运行 ./bin/model-router codex doctor 并处理所有 FAIL 项。
2. 确认 ./bin/model-router codex providers 对你选择的供应商显示 SHOW 与 ready。
3. 用 Command-Q 完全退出 Codex，重新打开并新建任务。
4. 打开模型选择器，找到路由模型。

可直接查看 Codex 启动目录：

codex debug models

模型仍缺失时，运行 ./bin/refresh-catalog，完全退出 Codex 再重新打开。

检查后台服务

路由器以按用户的 launchd 服务运行：

launchctl print "gui/$(id -u)/io.github.codex-router"

服务停止时，./bin/model-router codex doctor --fix 会重建托管配置与服务状态。

卸载

./bin/model-router codex uninstall

卸载只移除标记的集成配置与当前服务，有意保留检出目录、日志、备份与供应商凭据。要彻底清理，请先手动检查 ~/.codex/codex-router 再删除。

常见问题见故障排查；Windows 特有说明见 Windows 安装指南。