Codex Router 社区文档 EN GitHub
最后更新

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

本页覆盖在 Windows 上为 Codex App 或 CLI 安装 Codex Router、PowerShell 命令包装器、Codex Desktop 与 shell 分处不同环境的 WSL 边界情况，以及如何验证按用户服务。

Windows 前置要求

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

引导式安装

打开 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

向导按编号切换供应商，实时显示每个供应商的状态，并为你选择的项目以隐藏方式提示输入 API Key。它通过任务计划程序安装按用户的后台服务，未经你显式开启 smoke test 不会发起付费测试请求。

codex-router.ps1 包装命令

安装后，所有路由器命令都通过 PowerShell 包装器执行：

./codex-router.ps1 codex doctor
./codex-router.ps1 codex providers
./codex-router.ps1 codex provider-key deepseek set
./codex-router.ps1 codex update
./codex-router.ps1 codex uninstall

API Key 通过隐藏提示输入。不要把凭据放进对话、命令行参数、shell 历史或受版本控制的文件。

WSL 与 Codex Desktop 配置

当 Codex Desktop 在 Windows 上运行、而命令通过 WSL 执行时，可能存在两个不同的 Codex 主目录：C:\Users\<WindowsUser>\.codex 和 /home/<LinuxUser>/.codex。路由器命令使用 CODEX_HOME 选定的 Codex 主目录，因此在 WSL 内不覆盖该变量运行，可能更新的是 Linux CLI 配置，而不是 Windows Codex Desktop 使用的配置。

从 WSL 指向 Windows Desktop 配置：

export CODEX_HOME=/mnt/c/Users/<WindowsUser>/.codex
export CODEX_ROUTER_STATE_DIR="$CODEX_HOME/codex-router"

还要确保 Windows config.toml 中的 model_catalog_json 路径能被 WSL 读取——用 /mnt/c/Users/<WindowsUser>/.codex/codex-router/merged-models.json 而不是 C:\... 路径。如果安装看似成功但 Desktop 选择器没有变化，先检查改的是哪个 Codex 主目录再重跑安装。

验证安装

  1. 运行 ./codex-router.ps1 codex doctor 并处理所有 FAIL 项。
  2. 确认供应商报告 SHOW 与 ready。
  3. 完全退出 Codex（用应用的 Quit 命令，或在托盘存在时从托盘结束），重新打开并新建任务。
  4. 打开模型选择器。

检查计划任务：

Get-ScheduledTask -TaskName "Codex Router"

某层不健康时，./codex-router.ps1 codex doctor --fix 会重建托管配置与服务。

Windows 特有坑：Grok OAuth

Windows 上的 Smart App Control 可能阻止官方 Grok CLI，导致 Grok OAuth 无法完成登录或刷新会话。如果 grok --version 报 spawn UNKNOWN、“An Application Control policy has blocked this file,” 或 Smart App Control 通知，请改用带 xAI API Key 的 grok-api 供应商。详见故障排查。

卸载

./codex-router.ps1 codex uninstall

卸载移除活动集成与服务，但按设计保留检出目录、日志、备份与凭据。删除任何内容前请先手动检查 %LOCALAPPDATA%\codex-router 与状态目录。