PaiSwitch

面向 AI Coding Agent 的模型控制台。

PaiSwitch 不只是一个“改配置文件”的小工具，而是一套本地优先的 Agent Model Control Plane。它把 Claude Code、Codex 等 Agent 的底层模型选择、API Key 管理、协议适配、配置备份、自然语言切换和 Skills 管理收拢到同一个工作台里，让开发者可以在官方模型、国产大模型、多模型网关和自定义供应商之间稳定切换。

当前已支持 Claude Code 与 Codex 两条链路，覆盖 DeepSeek V4、智谱 GLM-5/GLM-5.1、Kimi、Qwen、OpenRouter、SkyClaw、讯飞星辰 MaaS 等模型或网关，并保留 OpenAI / Anthropic 官方登录路径。

核心价值

架构图

切换链路

支持矩阵

Agent 目标

内置模型与网关

说明：具体模型名以你的供应商账号权限和当前 Provider 配置为准。PaiSwitch 支持在模型管理页覆盖 base_url、主模型、小模型与 API Key。

项目结构

PaiSwitch/
├── ClaudeModelSwitcher/        # macOS 原生菜单栏应用，负责本机快速切换与 Keychain 存储
├── paiswitch-backend/          # Spring Boot API、配置写入器、代理转换器、Flyway 迁移
├── paiswitch-web/              # Vue 3 管理台，模型管理、切换、AI 助手、Skills 管理
├── docker-compose.yml          # MySQL + Backend + Frontend 一体化部署
└── README.md                   # 项目总览

快速开始

Docker Compose

cp .env.example .env
docker compose up -d --build

启动后访问：

默认账号：

admin / admin123

本地开发

先启动 MySQL，并创建数据库：

CREATE DATABASE paiswitch CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

启动后端：

cd paiswitch-backend
mvn spring-boot:run

启动前端：

cd paiswitch-web
npm install
npm run dev

访问：

http://localhost:3000

macOS 本地应用

open ClaudeModelSwitcher.xcodeproj

在 Xcode 中选择 PaiSwitch 目标并运行。macOS 应用支持本地切换、Keychain 存储、在线登录、AI 助手与 Claude Code Skills 管理。

macOS 桌面发行包

桌面发行包使用 Tauri 打包，会内置 Spring Boot 后端 Jar 和精简 Java Runtime，不要求用户单独安装 Java。

cd paiswitch-web
npm install
npm run desktop:build

构建产物：

src-tauri/target/release/bundle/dmg/*.dmg
src-tauri/target/release/bundle/macos/*.app

对外发布优先上传 .dmg；.app 适合作为 zip 备用包。Release 资产会按构建架构命名，例如 PaiSwitch-1.0.0-macos-arm64.dmg 或 PaiSwitch-1.0.0-macos-x64.dmg。

未配置 Apple Developer ID 签名时，macOS 首次打开会拦截。免费分发阶段可以让用户按下面方式安装：

1. 下载 Release 页面里的 .dmg。
2. 打开 .dmg，把 PaiSwitch.app 拖到 Applications。
3. 第一次启动时不要双击，右键点击 PaiSwitch.app，选择“打开”。
4. 如果仍被拦截，进入“系统设置” -> “隐私与安全性”，在安全提示处选择“仍要打开”。

使用方式

1. 选择目标 Agent

Web Console 顶部支持在 Claude Code 与 Codex 之间切换。不同 Agent 会维护独立的当前 Provider、模型参数和 API Key 状态。

2. 配置 Provider

进入“模型管理”：

3. 一键切换

进入“仪表盘”或“模型切换”页选择 Provider。PaiSwitch 会：

1. 读取当前用户、目标 Agent 和 Provider。
2. 查询对应 API Key 并解密。
3. 创建配置备份。
4. 写入 Claude Code 或 Codex 的本机配置。
5. 记录切换历史。

4. 自然语言切换

在 AI 助手中输入：

切换到 DeepSeek
帮我换成智谱
用 OpenRouter

PaiSwitch 会解析意图并触发切换。当前自然语言切换优先服务 Claude Code 链路，Codex 链路建议直接使用工具页切换。

协议适配

很多国产模型和 Agent 专用模型提供 OpenAI Chat Completions 接口，但 Codex 和 Claude Code 的请求形态并不相同。PaiSwitch 在本地提供两个代理入口：

代理会处理常见兼容性问题：

• 将工具调用结构映射到 Chat Completions。
• 合并或清理部分上游不接受的 system / stream 参数。
• 将上游 usage 字段重组为 Agent 可识别的格式。
• 对 OpenAI 官方链路保留 Codex OAuth 登录状态。
• 对第三方 Codex Provider 统一写入 wire_api = "responses"，由 PaiSwitch 代理完成转换。

配置文件落点

Claude Code

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8086/claude-proxy/skyclaw",
    "ANTHROPIC_AUTH_TOKEN": "your-provider-key",
    "ANTHROPIC_MODEL": "skywork-ai/skyclaw-v1",
    "ANTHROPIC_SMALL_FAST_MODEL": "skywork-ai/skyclaw-v1-lite",
    "API_TIMEOUT_MS": 600000
  }
}

官方 Anthropic 模式会清理第三方 Provider 变量，避免旧配置污染。

Codex

model_provider = "deepseek"
model = "deepseek-v4-pro"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers.deepseek]
name = "DeepSeek"
base_url = "http://127.0.0.1:8086/codex-proxy/deepseek/v1"
wire_api = "responses"
requires_openai_auth = true

OpenAI Official 模式会尽量保留 codex login 产生的 OAuth token；如果你在 PaiSwitch 中配置了 OpenAI API Key，则会改走 API Key 模式。

技术栈

API 概览

完整接口见：

http://localhost:8086/swagger-ui.html

环境变量

生产环境请务必覆盖 JWT_SECRET 与 AES_ENCRYPTION_KEY。

开发与验证

后端测试：

cd paiswitch-backend
mvn test

后端打包：

cd paiswitch-backend
mvn clean package

前端构建：

cd paiswitch-web
npm run build

macOS 桌面包构建：

cd paiswitch-web
npm run desktop:build

发布到 GitHub Release：

git tag v1.0.0
git push origin v1.0.0

在 GitHub 创建并发布同名 Release 后，.github/workflows/release-desktop.yml 会在 macOS runner 上构建 .dmg 和 .app.zip，并上传 SHA256SUMS.txt。资产名会包含构建架构，例如 PaiSwitch-1.0.0-macos-arm64.dmg。

如果不配置 Apple 凭证，workflow 会上传未签名包，首次打开可能触发 macOS Gatekeeper 提示。面向更大范围用户分发时，建议在 GitHub Secrets 中配置 Apple Developer ID 签名和 notarization：

常见问题

切换后 Agent 没有立刻生效？

Claude Code / Codex 可能已经在当前会话中读取了旧配置。重新打开终端或重启对应 Agent 后再试。

为什么 Codex 第三方模型要走本地代理？

Codex 对配置中的 wire_api 有严格限制，而 DeepSeek、GLM、Kimi、Qwen 等供应商通常提供 Chat Completions。PaiSwitch 将 Codex 请求先引到本地 /codex-proxy/{provider}/v1，再转换为上游可识别的请求。

Claude Code 能使用 OpenAI Chat Completions 兼容模型吗？

可以。Provider 的 wire_api 标记为 openai 时，PaiSwitch 会让 Claude Code 访问本地 /claude-proxy/{provider}，由代理完成 Anthropic Messages 与 Chat Completions 的双向转换。

API Key 存在哪里？

Web / 后端模式下存储在 MySQL，并通过 AES 加密；macOS 本地模式下存储在系统 Keychain。写入 Agent 配置时，PaiSwitch 只写入当前切换所需的 Key。

如何增加新的模型供应商？

在 Web Console 的“模型管理”中创建自定义 Provider，填写 base_url、模型名和 API Key。若需要内置到系统，可新增 Flyway 迁移并补充 DefaultUserInitializer。

文档入口

• Backend README
• Web README

License

MIT