导读按 ZSwitch 0.4.0 整理的使用教程:安装和首次打开的系统提示怎么处理,Claude Code、Codex、Grok 的中转站地址怎么填,保存前怎么测速和做真实测试,403 时怎么模拟 CLI 请求,切换何时生效,以及本地代理和恢复原始配置。
这份教程按 ZSwitch 0.4.0 整理,从安装到切换走一遍。ZSwitch 是真测开发的开源工具,原名 z-switch,界面和安装包里暂时还会看到旧名字。
安装
在 GitHub Releases 下载:
- Windows:
.exe安装包。提示“Windows 已保护你的电脑”时,点“更多信息 → 仍要运行”。 - macOS:
.dmg,按 Apple 芯片或 Intel 选择。提示“已损坏,无法打开”时,把应用拖进“应用程序”,再在终端执行下面的命令。 - Linux:
.AppImage或.deb。
xattr -dr com.apple.quarantine /Applications/z-switch.app
第一次启动
ZSwitch 第一次运行会做三件事:把本机 Claude Code 和 Codex 的原始配置完整保存到 ~/.z-switch/original/;为 Claude 和 Codex 各建一张“官方账号”卡片;如果发现你已经在用某个中转站,就把它导入成一张卡片并设为当前项。
添加中转站
点右上角“添加”,填名称、地址和 API Key。
- Claude Code:地址一般填站点根地址,如
https://api.example.com。可以分别给主模型和 Haiku、Sonnet、Opus、Fable 四档填模型,留空用中转站默认。Claude 5.x 系列原生支持 100 万 token 上下文,不用勾“1M”。 - Codex:只支持
responses协议,地址填到/v1,中转站需要提供/v1/responses。高级选项可以设推理强度。旧版本保存的chat供应商升级后会自动改成responses。 - Grok:填地址、API Key 和模型,ZSwitch 生成
~/.grok/config.toml。Grok 没有官方账号卡片。
表单和 JSON 两种编辑方式可以随时切换。
保存前先体检
每张卡片都能测连通性、拉取模型列表、做 HTTP 层测速。测速刻意不用 TCP:本机开着 TUN 或透明代理时,TCP 握手会被本地直接应答,测出不到 1 毫秒的假数字。
“真实测试”会用保存的地址、Key、模型和协议发一条最小的流式 Hi(最多输出 32 tokens),弹窗里显示回复、首字耗时和总耗时。会产生极少量调用费用,测试内容、回复和 Key 不写入任何文件。
有的中转站 Key 只放行官方客户端,普通测试会返回 403,提示类似 this key requires Claude Code CLI。在弹窗左下角勾选“模拟 CLI 请求”再试,这个选项按卡片记住。
想确认中转站返回的是不是声称的模型,体检之外可以再到 真测免费检测 跑一次完整检测。
切换
在卡片上点“切换”。默认的直连模式会马上把这张卡片写进客户端配置;切换之前,ZSwitch 先把当前生效的配置回填到上一张卡片,你手动改过的内容不会丢。
- Claude Code 一般在下一次请求时读到新配置,不用重启。
- Codex CLI 可能要重启后才生效。
官方账号卡片不保存任何 Key。切到 Claude 官方账号时,ZSwitch 清掉中转相关的环境变量;Codex 切走前会保存客户端的登录状态,切回来时恢复。
本地路由代理(实验)
需要在客户端运行时频繁切换,可以在设置里打开本地路由代理。ZSwitch 监听 127.0.0.1:8899,把客户端地址指向 http://127.0.0.1:8899/claude 和 http://127.0.0.1:8899/codex,切换时只换上游地址和鉴权。
它不改写已经写进配置的模型名,所以只适合模型兼容的供应商之间切换,跨模型还是要关掉代理用直连切换。目前也没有自动重试和故障转移。日常使用推荐直连模式。
恢复原始配置
在设置里可以分别把 Claude Code、Codex 或 Grok 恢复成第一次启动时保存的配置,恢复前还会再备份一次。删除正在使用的供应商时,也可以选择恢复原始配置,或者保留电脑当前配置、只解除 ZSwitch 的管理。
文件位置
~/.claude/settings.json:Claude Code 配置,直连模式只改写其中的env,statusLine、hooks等其他顶层字段保留。~/.codex/auth.json、~/.codex/config.toml:Codex 配置,第二个文件写入失败时回滚第一个。~/.z-switch/:供应商列表、原始配置快照、写前备份和本地代理的脱敏错误日志。
更多说明见仓库里的 完整使用教程,工具介绍见 AI 工具:ZSwitch。
常见问题
切换后 Claude Code 没有生效怎么办?
Claude Code 一般在下一次请求时读取新配置,Codex CLI 需要重启。仍然无效时,检查卡片的地址和 Key,用连通性测试确认。
Codex 提示 wire_api = \"chat\" 不再支持?
Codex 已移除 chat 协议。ZSwitch 0.3.1 起会在启动时把供应商和 config.toml 里的 chat 改成 responses,改前先备份。中转站没有 /v1/responses 时不能再用于 Codex。
真实测试返回 403 是 Key 坏了吗?
通常不是。有的中转站只放行官方客户端,在真实测试弹窗左下角勾选“模拟 CLI 请求”再试;仍被拒时,以 Claude Code 或 Codex 里的实际使用为准。