models.json 配订阅、API Key 和 custom provider。这一节把它们管起来：用 pi-switch 在图形界面或命令行里切换 Profile、做模型名路由、开 failover。以后 md-tools 换模型、换通道，不再手改配置。为什么需要 pi-switch
Claude Code、Codex 的供应商管理有 cc-switch，但 cc-switch 不知道 Pi——它管理 claude、codex、gemini 等，Pi 的配置在 ~/.pi/agent 自己的文件（models.json、auth.json）里。
pi-switch 就是「Pi 版的 cc-switch」：专门管理 Pi 的 Provider、模型、认证与路由。社区已有多个实现，形态分两类：
- CLI + TUI 版（如
@cokefenta/pi-switch，Rust 实现）：交互式 TUI 或命令行管理 profile，自带本地模型名路由网关 - 桌面版（Tauri 实现）：cc-switch 风格的图形界面，还能浏览历史 Session、统计 Token 用量、管理 Skill
无论哪种形态，核心能力一致：
| 能力 | 说明 |
|---|---|
| Provider / Profile 管理 | 增删改查、一键切换、自动备份 |
| 模型名路由网关 | 本地起一个网关，按模型名把请求路由到对应供应商 |
| Failover | 上游挂了自动切到备用通道 |
| 配置校验 | 改完用 pi --list-models 验证可用 |
| 安全 | Key 加密保存（macOS Keychain 等），导入导出不含密钥 |
| 兼容 | 可只读导入 cc-switch 的数据库，已有中转配置不用重填 |
一句话：前三节你学会的每一条配置，pi-switch 都是它们的管理界面；多出来的，是模型路由与 failover 这两个手写很麻烦的能力。
安装
CLI/TUI 版（任选其一）：
npm install -g @cokefenta/pi-switch # 全局安装
# 或通过 pi 安装
pi install npm:@cokefenta/pi-switch
桌面版从项目 Releases 下载对应平台的安装包即可。
快速上手
- 添加 Provider：打开 pi-switch，新建 Provider（支持 OpenAI 兼容、Anthropic、DeepSeek 等模板，模板只预填公开的端点/模型字段，Key 始终由你单独输入）；也可以从 cc-switch 数据库导入，已有中转配置免重填
- 配置模型路由网关：起一个本地端口，建立「模型名 → 供应商」的映射；请求到网关后按模型名分发，模型名冲突时还能做优先级
- 切换并验证：切到目标 Profile，跑
pi --list-models确认当前配置可用，再正常启动 pi 会话 - 开启 failover：给关键模型配备用供应商，上游 4xx/5xx 或超时自动切换
切换前 pi-switch 会自动生成带时间戳的备份；写回配置时保留未知字段，降低与 Pi 后续版本之间的兼容风险。
落地练习：配两个 Provider 并切一次
- 安装 pi-switch，添加两个 Provider（比如 DeepSeek + 一个 OpenAI 兼容通道），各填一个 Key
- 启动模型路由网关，把
deepseek-chat指向 Provider A、另一个模型名指向 Provider B - 切换 Profile 后用
pi --list-models验证；给 Provider A 配一个 failover 到 Provider B - 正常启动 pi，问一句「你是谁」，确认走的是当前 Profile 的通道
怎么判断做对了？——
pi --list-models输出的模型与当前 Profile 一致；关掉 Provider A 的 Key（或用一个错 Key）后，模型调用自动落到备用通道，会话不中断。
卡住了怎么办？ 切换后 pi 还是旧模型 → 确认 pi 已重启、读取的是新 models.json。路由网关不通 → 检查本地端口是否被占用、映射的模型名与 models.json 一致。导入失败 → 确认源是 cc-switch 的数据库文件且 pi-switch 版本支持。
常见坑：把「模型路由」和「Provider 切换」当成一回事
两者是不同层级的能力：
- Provider 切换：换的是「当前会话用哪套配置」——一次切一个，会话级生效
- 模型路由网关：在请求级做分发——同一个 pi 进程里，按模型名把不同请求送到不同供应商，还带 failover
很多刚用 pi-switch 的人以为「切换了 Profile 就等于路由了」，结果 failover 没生效。记住：Profile 管「用谁」，路由网关管「把每个请求发给谁」，要 failover 就必须走网关。
另一个安全提醒：密钥只存在 pi-switch 的加密存储里，导出配置、分享 Profile 时都不应包含 Key；模板同步也只会更新公开字段，不会动你的凭据。
小结
- cc-switch 管不了 Pi，pi-switch 是「Pi 版的 cc-switch」，专管
~/.pi/agent的配置 - 形态：CLI + TUI / 桌面版，核心是 Provider 管理 + 模型名路由网关 + failover
- 安装：
npm install -g @cokefenta/pi-switch或pi install npm:...；桌面版走 Releases - 安全：Key 加密存储、导入导出不含密钥、可只读导入 cc-switch 数据库
- Profile 管「用谁」，路由网关管「每个请求发给谁」，failover 必须走网关
下一节，进入模块 02：Pi Packages 分发——把能力打包发出去。