CSSwitch

CSSwitch 快速入门

一句话卖点:让 Claude Science 不再绑定 Anthropic 订阅，本地代理一键接入 DeepSeek / GLM / Kimi 等任意 OpenAI / Anthropic 兼容端点，Tauri 2 桌面端 + 隔离虚拟登录保安全。

这是什么?适合谁?

CSSwitch 是开发者 SuperJJ007 专为 Claude Science 打造的 macOS 桌面端三方模型切换工具。它通过在本地启动一个反向代理，把 Claude Science 默认发往 Anthropic 的推理请求重定向到你填入的第三方 API Key，再在 Science 顶部显示你选择的真实模型名（如 glm-5.2），让 Anthropic 的科研工作流用国产模型也跑得起来。

项目诞生于一个很具体的痛点：Claude Science 是 Anthropic 推出的 AI Agent 科研平台，可以协助文献检索与分析、数据处理、图表生成和论文写作，但它启动时强制走 Anthropic OAuth 登录，订阅价格对很多个人科研工作者偏高。CSSwitch 用两段式解决方案破局——一是用隔离环境里的本地虚拟登录启动 Science，二是把推理请求通过本地代理劫持给 DeepSeek / 通义千问 / 智谱 GLM / Kimi / MiniMax / 小米 MiMo / 硅基流动 / OpenRouter / 任意自填 OpenAI/Anthropic 兼容端点。仓库在 GitHub 上线 3 天即达到 244 stars（截至 2026-07-05 已 116 commits，v0.3.3 当日发布），属于典型”小而精”的开源工具。

适合人群:已订阅或无法订阅 Claude Science 但需要其科研工作流的研究生 / 高校教师 / 算法工程师;在意 API 成本、用国产模型 API 跑长任务的团队;macOS Apple Silicon 用户希望一键管理多模型配置(支持同一家服务商多 Key / 多模型并行)。不适合 Intel Mac 用户(尚未提供 x86_64 构建)、Windows / Linux 用户(明确仅 macOS Apple Silicon)、以及只想要轻量 CLI 切换的人(本工具为桌面 GUI)。

准备工作

1. 一台 macOS Apple Silicon (M1/M2/M3/M4) 电脑;
2. 已安装 Claude Science (claude.com 下载);
3. macOS 自带 python3(用于本地代理子进程,无需手动安装 Node.js);
4. 一个第三方模型 API Key(DeepSeek / 通义千问 / 智谱 GLM / Kimi / MiniMax / 小米 MiMo / 硅基流动 / OpenRouter / 自定义端点均可);
5. 当前版本 v0.3.3 未经 Apple 公证,首次启动需右键「打开」或在「系统设置 → 隐私与安全性 → 仍要打开」放行。

3 步快速上手

第 1 步:下载安装

打开 CSSwitch 最新 Release 页 下载 CSSwitch_v0.3.3.dmg,把 CSSwitch.app 拖入「应用程序」。当前仅 Apple Silicon (arm64) 构建,Intel Mac 暂不支持。

第 2 步:新建一条第三方配置

打开 CSSwitch,顶部选择「第三方模型」,点击「+ 新建」,在弹窗中选择来源(例如「DeepSeek」或「通义千问」),粘贴你的 API Key,点「创建」。密钥以 0600 权限保存在 ~/.csswitch/config.json,UI 只显示遮盖后四位,不会写入命令行参数或日志。

第 3 步:一键启动

在配置列表点这条配置的「设为当前」—— CSSwitch 会发一条最小请求预校验 Key,通不过则自动回退不切换;通过后点「一键开始」,CSSwitch 会自动启动代理 → 写入本地虚拟登录 → 启动隔离环境 → 在浏览器中打开 Claude Science。Science 顶部模型选择器会显示你配置的真实模型名(如 deepseek-reasoner / glm-5.2),而非笼统的 claude。

完成一次配置后,后续打开 CSSwitch + 点「一键开始」即恢复之前的工作状态。重复点击也不会打乱当前会话或切换到其他组织。详见 docs/DEVELOPMENT.md。

功能特性

🔁 多服务商即装即用:内置 8 家常见国产 / 海外 API(DeepSeek / 通义千问 / 智谱 GLM / Kimi / MiniMax / 小米 MiMo / 硅基流动 / OpenRouter),同一家可保存多套配置(不同 Key / 不同模型),下拉里选维护好的主流模型或自填任意模型名,通过 ~/.csswitch/config.json 持久化。来源:README - 支持的第三方 API

🛡️ 隔离虚拟登录,不接触真实凭证:Science 启动所需的登录状态由 Rust 原生本地生成,代码路径(~/.claude-science)不会读取、复制、修改或删除。隔离环境拥有独立 HOME、端口(避开 8765)和数据目录,即使 API Key 走代理,Claude 真实登录信息也完全不经过 CSSwitch 子进程。来源:README - 与真实账号隔离

🔒 本地代理收口 + Key 0600 权限:代理(csswitch_proxy.py,计划用 Rust axum 重写)只监听 127.0.0.1 回环地址,通过路径 Secret 验证请求,自动移除传入请求的 Authorization 和 x-api-key 再转发第三方。API Key 以 0600 权限落盘,通过环境变量传给子进程,绝不进命令行参数或日志。来源:README - 风险与免责声明

🎯 DeepSeek 原生 Anthropic 端点,保留完整能力:DeepSeek 走原生 Anthropic 端点而非 OpenAI 协议转换,能更完整保留 Thinking 与工具调用(Tool Use);Qwen 等通过 DashScope OpenAI 兼容端点接入并由代理做协议转换;GLM / Kimi / MiniMax / 小米 MiMo / 硅基流动 / OpenRouter 走内置 Anthropic 兼容端点。来源:README - 支持的第三方 API

✅ 启用前最小请求校验:把一条配置「设为当前」或修改正在生效的连接时,CSSwitch 会先发一条最小请求验证 Key,通不过自动回退、不会谎报已生效——避免传统类似工具最常见的「配置看上去成功但调用 401」陷阱。新建配置只保存、不联网,验证留到启用那一步。来源:README - 省心好用

🪟 macOS 原生 Tauri 2 桌面体验:基于 Tauri 2 + Rust(95.1% Rust + 1.9% CSS + 3.0% HTML/JS,见 GitHub Languages API),从 GitHub Releases 一键下载 dmg,菜单栏常驻,菜单图标随状态切换;面板内直跳 GitHub Releases 检查更新。来源:GitHub API - SuperJJ007/CSSwitch

🧪 真实模型名透传,告别笼统 “claude”:与常见的「伪 claude」方案不同,CSSwitch 会在 Science 顶部模型选择器显示你配置的真实模型名(例如 glm-5.2),让你一眼看出当前会话跑的是哪个模型;代理层(/v1/models)在 force 时返回单壳 claude-opus-4-8 + 真实 display_name,Science 内部模型调度按真实名路由。来源:CHANGELOG.md - v0.3.2

竞品对比

CSSwitch 不与 CC Switch 或 Claude Code Router 正面抢开发者/编程 Agent 市场——它专注 Claude Science 科研 Agent 一条窄路径,典型的”宽度让位深度”策略。截至 2026-07-05 CC Switch 113k stars 是 CSSwitch 244 stars 的约 463 倍,但 CSSwitch 上线仅 3 天,追赶空间清晰(GitHub API vs GitHub API)。

适用场景

🎓 高校与科研机构低成本科研写作:Claude Science 订阅 $20/mo(Pro)或更贵,中国大陆研究生普遍难以订阅;CSSwitch 让一台 Mac + DeepSeek API Key 就能跑完文献综述、论文摘要、研究方法学讨论全流程,API 按 token 计费、单次任务几美分即可完成(DeepSeek 定价)。

🧪 多模型横评与 A/B 测试:同一家服务商保存多套配置(不同 Key 或不同模型),可随时切换观察 Claude Science 在 DeepSeek-Reasoner / GLM-5.2 / Kimi-K2 / MiniMax 下的真实表现(工具调用成功率、长文一致性、Thinking 输出质量),适合技术选型阶段对比国产模型。

❓ 常见问题 FAQ

基础使用

Q: CSSwitch 是否支持 Windows 或 Linux？ A: 当前 v0.3.3 仅支持 macOS Apple Silicon (M1/M2/M3/M4)。Intel Mac、Windows、Linux 均不支持。Intel x86_64 构建已在 Roadmap 中规划。

Q: 是否需要安装 Node.js 或额外的运行时？ A: 不需要。CSSwitch 基于 Tauri 2 (Rust 后端) + macOS 自带 Python 3 运行代理子进程，无需手动安装 Node.js、npm 或其他运行时。

Q: 首次启动被 macOS Gatekeeper 阻止怎么办？ A: 右键点击 CSSwitch.app →「打开」，或在「系统设置 → 隐私与安全性」中点击「仍要打开」。这是因为当前版本未经 Apple 公证（notarization）。

Q: 如何更新 CSSwitch？ A: 打开 CSSwitch 面板，点击菜单栏图标 →「检查更新」→ 自动跳转 GitHub Releases 页下载最新 dmg。覆盖安装即可，配置文件 ~/.csswitch/config.json 不会被覆盖。

API 与模型配置

Q: 同一家服务商可以配置多个 API Key 吗？ A: 可以。在「第三方模型」面板点击「+ 新建」多次，每次选择同一来源、填入不同 Key 或模型名即可。所有配置持久化在 ~/.csswitch/config.json，下拉列表可自由切换。

Q: DeepSeek 和通义千问的协议转换有什么区别？ A: DeepSeek 走原生 Anthropic 端点，完整保留 Thinking 与 Tool Use 能力。通义千问 (Qwen) 通过 DashScope OpenAI 兼容端点接入，由 CSSwitch 代理做 OpenAI→Anthropic 协议转换。当前版本 Qwen 流式协议转换尚未实现，首个 Token 等待时间较长。

Q: 配置后 Science 顶部显示的是什么模型名？ A: v0.3.2 起显示你配置的真实模型名（如 glm-5.2、deepseek-reasoner），而非笼统的 claude。代理层 /v1/models 返回单壳 claude-opus-4-8 作为 compatibility shim，display_name 为真实模型名。

Q: 为什么启用前需要「设为当前」并等待校验？ A: 「设为当前」时 CSSwitch 发一条最小请求预校验 API Key。通不过则自动回退，不切换——这防止了”配置看上去成功但调用时 401”的常见陷阱。新建配置只保存、不联网，验证留到启用那一步。

安全与隔离

Q: CSSwitch 会接触我的真实 Claude 账号吗？ A: 不会。Science 启动所需的登录状态由 Rust 本地生成，代码路径 ~/.claude-science 不会被读取、复制、修改或删除。隔离环境拥有独立的 HOME、端口和数据目录。

Q: API Key 存储在哪里？安全吗？ A: 存储在 ~/.csswitch/config.json，文件权限 0600（仅 owner 可读写）。UI 只显示遮盖后四位。Key 通过环境变量传给子进程，不写入命令行参数或日志文件。

Q: 代理会向外网暴露我的请求吗？ A: 不会。csswitch_proxy.py 仅监听 127.0.0.1 回环地址，本机外不可触达。代理额外使用路径 Secret 验证请求来源，并自动移除传入请求的 Authorization 和 x-api-key 头。

兼容性与限制

Q: 哪些 Claude Science 功能在 CSSwitch 下不可用？ A: (1) Science 内置的 PubMed / Clinical-Trials / bioRxiv 等 MCP 工具因授权问题无法使用；(2) DeepSeek 工具调用在少数情况下被返回为文本（当前默认关闭）；(3) Qwen 流式协议转换未实现。

Q: CSSwitch 与 CC Switch、Claude Code Router 能同时使用吗？ A: 理论上可以——CSSwitch 仅代理 Claude Science 的请求，CC Switch 和 Claude Code Router 代理 Claude Code 等 CLI 工具，三者在不同端口和进程空间运行，互不冲突。

🔬 高级使用技巧

多 Profile 隔离环境

CSSwitch 支持在同一台 Mac 上创建多个隔离的 Science 实例，每个实例拥有独立的 HOME 目录、端口分配和数据存储。通过命令行指定 Profile 名称实现：

# 启动名为 "research" 的隔离实例
open -a CSSwitch --args --profile research

不同 Profile 之间完全隔离，可用于：同一服务商不同模型 A/B 测试、为不同科研项目维护独立上下文、避免长任务之间的状态污染。详见 DEVELOPMENT.md 的命令契约章节。

自定义 API 端点

除 8 家内置服务商外，CSSwitch 支持手动填入任意 OpenAI 或 Anthropic 兼容端点。在新建配置弹窗中选择「自定义」来源，填入：

• 端点 URL：需支持 /v1/chat/completions（OpenAI 兼容）或 /v1/messages（Anthropic 兼容）
• API Key：该端点的认证密钥
• 模型名：端点支持的模型标识符

此功能适合自建 API 网关（如 one-api、LobeHub）、企业私有化部署的大模型服务、或尚未被 CSSwitch 内置的 API 服务商。

代理日志排障

当模型切换异常或请求失败时，检查 ~/.csswitch/logs/proxy.log：

# 实时查看代理日志
tail -f ~/.csswitch/logs/proxy.log

# 搜索 401/403 错误（通常为 Key 无效或权限不足）
grep -E "401|403" ~/.csswitch/logs/proxy.log

# 搜索协议转换错误
grep "protocol" ~/.csswitch/logs/proxy.log

常见错误码速查：401 = API Key 无效或过期，403 = 权限不足（检查 API Key 的模型访问权限），429 = 速率限制（降低并发或升级 API Plan），502/503 = 上游模型服务不可用。

端口冲突处理

CSSwitch 默认使用以下端口，确保不被其他服务占用：

若 8766 被占用，CSSwitch 会启动失败。排查命令：lsof -i :8766 查看占用进程，终止后重试。

批量任务最佳实践

对于需要长时间运行的科研任务（如文献综述、多轮论文润色）：

1. 单任务单 Profile：为长任务创建专用 Profile，完成后清理
2. Key 轮换：为同一服务商配置多个 Key，利用 API 免费额度分摊成本
3. 进度保存：Science 的会话状态存储在隔离环境的数据目录中，即使代理断开也不会丢失
4. 成本监控：定期检查各 API 服务商的控制台用量面板，设置预算告警