z-switch

面向 Claude Code 与 Codex 的桌面供应商一键切换器 —— 直连原子改写或本地代理热切换

One-click desktop provider switcher for Claude Code & Codex — atomic direct-write or live hot-swap.

由 真测 Ztest · ztest.ai 出品 · 开源 · 无广告 · 无返利链接 · inspired by cc-switch

简介

z-switch 让你在多个 API 中转站 / 官方账号之间，为 Claude Code 和 Codex 快速切换供应商。

它提供两种工作方式：

• 直连模式（默认） — 直接、原子化地改写客户端配置文件，切换后由客户端本身生效，零中间层。
• 本地路由模式（实验） — 启动一个 localhost 代理，让你在进程运行期间热切换目标供应商，无需重启客户端。

项目坚持开源、无广告、无返利链接，当前专注于把「切换」这一核心能力做扎实；MCP、技能（Skills）等扩展功能也可能在后续版本中逐步加入。

⚠️ 隐私优先：所有配置和快照都保存在本地。真实测试内容、模型回复与 API Key 不写入任何持久化文件。

目录

• 核心特性
• 赞助商
• 快速开始
• 使用指南
• 工作原理
• 数据与文件位置
• 安全与隐私
• 开发
• 项目结构
• 致谢
• 许可

核心特性

❤️ 赞助商

感谢以下伙伴对 z-switch 的支持。本项目坚持无广告、无返利链接，赞助板块仅展示真实合作方。

本项目由 真测 Ztest（ztest.ai） 出品并支持！真测是一个 AI 中转站模型验真平台，检测结果完全公开。采用 23 个探针，覆盖协议、身份、能力、内容完整性、安全、性能六大维度，通过交叉验证识别伪造与降智，作为独立第三方持续监测各 AI 中转站的模型真实性、响应质量与服务可用性。点击此链接了解更多！

想成为 z-switch 的赞助商？欢迎通过 ztest.ai 与我们联系。

快速开始

下载安装

前往 Releases 下载对应平台的安装包，或参考 开发 从源码自行构建。

30 秒上手

1. 首次启动 — z-switch 自动保存本机 Claude Code / Codex 原始配置，建立默认「官方账号」卡片；检测到已有中转配置会自动导入并设为当前项。
2. 添加供应商 — 点击右上角「添加」，填写名称、Base URL 和 API Key，随后可测试连通性、拉取模型并测速。
3. 切换 — 点击供应商卡片上的「切换」，直连模式会立即写入客户端配置。
4. 验证（可选） — 点「真实测试」，选择模型并发送一条最小 Hi 请求，实时查看回复、首字耗时与总耗时。

真实测试会产生极少量模型调用费用；本地路由目前不提供自动重试或故障转移。

使用指南

📖 完整使用教程见 docs/USAGE.md（安装、添加供应商、切换、本地路由代理、FAQ 等）。下面是精简流程。

工作原理

直连模式（默认）

切换时，z-switch 直接改写客户端配置文件：

• Claude — 合并写入 ~/.claude/settings.json 的 env，保留其他顶层字段。
• Codex — 写入 ~/.codex/auth.json 与 ~/.codex/config.toml；第二个文件写入失败时回滚 auth。
• 官方账号卡片不保存 API Key — Claude 清除中转环境变量、改用客户端本机登录；Codex 切走前保存客户端刷新后的登录态，切回时恢复。
• 切换前 backfill — 把当前 live 配置回填到旧供应商，避免手工修改丢失。
• 安全删除 — 删除正在使用的供应商时，可选择恢复首次原始配置，或保留电脑当前配置、仅解除 z-switch 管理。

首次运行会把原始文件完整保存在 ~/.z-switch/original/。该快照独立于供应商列表和普通 JSON 导出，可在设置页分别恢复 Claude Code 或 Codex；恢复前仍会保存一份时间戳备份。

Claude Code 通常在下一次请求时读取新配置；Codex CLI 可能需要重启。

本地路由模式（实验）

开启后，z-switch 监听 127.0.0.1:8899（可由配置覆盖），并把两个客户端的 live Base URL 分别指向：

• http://127.0.0.1:8899/claude
• http://127.0.0.1:8899/codex

代理会根据当前 API 中转站注入对应鉴权信息并转发请求——不修改请求体、不做协议转换、不记录用量。切换中转站时立即更新上游 Base URL 与鉴权信息；官方账号始终保持客户端直连，另一个应用仍可继续使用本地代理。设置页可配置连接 / 首段 / 流静默 / 非流式超时、请求体硬上限、连接池与 TCP Keepalive；流式返回与连接复用始终开启。

失败请求会按设置写入 ~/.z-switch/logs/proxy-errors.jsonl，仅记录上游状态、脱敏 URL、失败阶段和截断后的错误详情，不记录请求正文。日志自动脱敏当前供应商密钥并按文件大小轮转，可在设置页打开目录或清空。

已知限制：当前不会同步改写开启代理时已落入 live 配置的模型名和 Codex wire_api。因此热切换只适用于模型 / 协议兼容的供应商；跨模型或跨协议切换仍需关闭代理后直连切换。该模式仍需用真实供应商持续验证路径、鉴权头和流式响应兼容性。

Claude 生态联动（可选开关）

除了 Claude Code CLI（~/.claude/settings.json），设置页可开启让切换同步到 Claude 的其它入口，均为「跟随当前 Claude 供应商」，官方账号 / 恢复原始时自动撤回：

• Claude 桌面版（独立聊天 App，仅 macOS / Windows） — 写桌面版 3p 网关配置：本地路由开着时网关指向 …/claude（复用代理，随热切换跟随），关着时直连供应商地址。需重启桌面 App 才读取新配置；未安装桌面 App 时该开关不产生任何写入。
• VS Code Claude Code 扩展 — 扩展有独立鉴权门槛，仅改 settings.json 不认；开启后写 ~/.claude/config.json 的 primaryApiKey（官方账号时清除），让扩展随第三方供应商生效。
• 跳过 Claude Code 初次安装确认 — 向 ~/.claude.json 写 hasCompletedOnboarding，跳过首次运行引导。

以上均只做单字段增量读改写，保留文件里的其它内容，绝不整体覆盖；任一同步失败只记日志，不影响供应商切换本身。

数据与文件位置

安全与隐私

• 所有数据均保存在本地，无云端上传、无遥测。
• 真实测试的内容、模型回复与 API Key 不写入任何持久化文件。
• 代理错误日志自动脱敏密钥，且不记录请求正文。
• 所有配置写入均为原子操作并在写前备份，最大限度避免破坏原有环境。
• 项目无广告、无返利链接，官方账号卡片不保存任何 API Key。

开发

环境要求

• Node.js 20.19+ 或 22.12+
• Rust stable
• Windows 需安装 Tauri 所需的 WebView2 与 MSVC 构建工具

本地运行

npm install
npm run tauri dev

常用检查

npm run build

cd src-tauri
cargo clippy --all-targets --all-features
cargo test

构建可执行文件

npm run tauri build -- --no-bundle

项目结构

src/                        前端（React 19 + TypeScript）
  App.tsx                   主界面、切换、深链和状态同步
  ProviderModal.tsx         供应商表单、连通性、密钥和模型选择
  SettingsModal.tsx         主题、自启、本地路由等设置
  providerFactory.ts        Provider 构建器和地址推断规则
  api.ts / types.ts         Tauri 命令封装与前端类型

src-tauri/src/              后端（Rust + Tauri 2）
  lib.rs                    Tauri 命令、状态和切换流程
  config.rs                 路径与原子写入
  store.rs                  providers.json 数据模型
  live.rs                   Claude/Codex live 配置读写
  proxy.rs                  本地代理和热切换目标
  claude_ext.rs             VS Code 扩展放行 + 跳过初次确认
  claude_desktop.rs         Claude 桌面版 3p 网关配置写盘
  connectivity.rs           HTTP 连通性检查与测速
  model_fetch.rs            模型列表拉取
  tray.rs                   系统托盘

致谢

• cc-switch（MIT，Copyright © 2025 Jason Young）—— z-switch 的设计与实现参考了该项目，特此致谢。
• 本项目接受 LINUX DO 社区佬友的监督与反馈，感谢每一位提出建议的朋友。

许可

本项目基于 MIT License 开源，可自由用于个人与商业用途，只需保留版权与许可声明。

项目参考了同为 MIT 许可的 cc-switch，其原始版权声明已一并保留在 LICENSE 中。