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

本页讲解如何在 macOS 上为 Codex App 或 CLI 完整安装 Codex Router。推荐方案包含 Control Center、菜单栏宿主与桌面小组件，并说明如何在打开模型选择器前验证所有组件健康。

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 --with-tray

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

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

Control Center 与菜单栏应用

推荐命令会构建并安装 Codex Router.app，把原生菜单栏宿主与 Electron Control Center 组合为一个应用。打开应用会显示 Control Center；关闭窗口后菜单栏宿主继续运行。可从 Spotlight 或 ~/Applications 启动，也可重新构建：

./bin/model-router-tray

App bundle 位于 ~/Applications。由于包含 SwiftUI macro 与 WidgetKit target，它要求完整 Xcode App，仅安装独立 Command Line Tools 不够。安装器会尊重 DEVELOPER_DIR 或 Xcode → Settings → Locations → Command Line Tools 中的选择，也可临时使用 /Applications/Xcode.app 而不修改全局设置。Dynamic Island 覆盖层默认关闭，可在 Settings → Dynamic Island → Desktop 开启。

若 Xcode 位于其它路径，可这样重建桌面伴侣：

env DEVELOPER_DIR="/path/to/Xcode.app/Contents/Developer" \
  ~/.local/share/codex-router/bin/model-router-tray

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 安装指南。