帮助

快速解答

支持哪些系统？: macOS（Apple Silicon，macOS 12 及以上）和 Windows（10 / 11，x64）。暂时没有 Intel Mac 和 Linux 版本。
支持哪些 Agent？: Claude Code、Codex、Grok Build 和 ZCode。每个 Agent 由各自的开源适配器负责写入，见各 Agent 的写入细节。
收费吗？: 不收费，没有订阅，也不用注册账号。源码按 PolyForm Noncommercial 1.0.0 公开：个人使用、学习和研究可以自由使用；商业使用需另行取得授权。
需要装 Python 或别的依赖吗？: 不需要。四个适配器都已打包在 App 里。Switch 也不会替你安装 Agent 本身，Agent 请从各自的官方渠道安装。
会改坏我的配置吗？: 每次写入前都会先给你看部署计划，确认后才写；写之前自动备份。停用时只还原 Switch 写过的部分，你自己写的内容不动。适配器发现不安全时会拒绝写入，并且不改动任何文件。
我的提示词会被上传吗？: 不会。提示词只存在本机的 ~/.keysmith-switch/，也没有统计或遥测。App 联网主要是为了检查更新和读取公告；打开「拓展」后才会读取拓展源。完整列表见数据与隐私。
从哪里下载才安全？: 只从本站的下载页或 GitHub 上的官方发布页下载。从其他地方拿到的安装包，请不要打开。

安装与打开

macOS 提示「无法打开」或「无法验证开发者」: 第一次打开时 macOS 会拦一下。打开「系统设置 → 隐私与安全性」，在页面下方找到 Keysmith Switch，点「仍要打开」并确认。macOS 14 及更早版本也可以在「应用程序」里右键点它，选「打开」。只需要做一次。
Windows 提示「Windows 已保护你的电脑」: 点「更多信息」，再点「仍要运行」。它装在你自己的用户目录下，不需要管理员权限。
杀毒软件报毒怎么办？: 从本站或 GitHub 官方发布页下载的，就是误报。在杀毒软件的隔离区里恢复文件，再把 Keysmith Switch 加入信任区（白名单）即可。不确定的话，到 GitHub 上留言问我们。
怎么更新？: 有新版本时，App 设置处会出现红点，点一下就能更新，装不装由你确认。也可以随时从下载页下载新版本直接安装，提示词库不会受影响。
检查更新超时: 如果你用的是 v0.3.7 之前的版本，而且电脑开着代理，检查更新可能会超时。到下载页下载新版本手动安装一次，之后的更新就正常了。
怎么卸载？: 先在 App 里停用各 Agent 的提示词、断开输入替换，Agent 的配置就会还原。然后 macOS 把 App 移到废纸篓，Windows 在「设置 → 应用」里卸载。卸载不会删除 ~/.keysmith-switch/（提示词库和备份），想彻底删除可以之后手动删掉这个文件夹。

部署与停用

部署了，但 Agent 里没有生效: 部署后要重启 Agent：Claude Code、Codex、Grok Build 开一个新会话，ZCode 重新打开 App。已经打开的会话不会重新读取提示词。
部署被拦下，提示配置被改过: 部署之后有人（或别的工具，例如 cc-switch）改过这个 Agent 的配置，这叫漂移。为了不覆盖你的修改，部署会被拦下。按弹窗提示操作：
只是托管的几行被挪动：点「整理配置」；
记录已经乱了：点「清理」从头开始（会删除这个 Agent 的登录和会话历史，先看清清理计划）。
停用时提示找不到部署记录或备份: 如果部署前的配置备份已经不在（例如被清理删掉了），可以选「保留当前配置并停用」，只移除 Keysmith 写入的那一段。找不到部署记录时，可以用「清理」清掉过期的记录。
Windows 上提示权限不足: 你的 Windows 账户没有这个 Agent 文件夹的完全控制权限。给这个文件夹加上「完全控制」权限后再试一次。
编辑了正在用的提示词，Agent 里没变: 保存只改库里的内容。要再部署一次，修改才会写进 Agent。保存后页面会提醒你。
ZCode 部署失败: 请确认 ZCode 已经从官方渠道安装、至少打开过一次，并且用 API 登录（ZCode 只支持 API 登录）。部署被拒绝时，弹窗会写出适配器给出的具体原因。

清理与回滚

清理会删掉什么？: 清理把 Agent 清回刚安装的样子：移除部署的提示词、你自己加的规则和配置；登录、会话历史、插件和缓存会直接删除，不保存。清理前会先列出全部内容，详见清理与回滚。
清理之后还能找回来吗？: 可以找回大部分：清理前会先存一个版本，在「设置 → 版本」里回滚，提示词、记忆文件、规则和配置都会放回去。登录和会话历史不会回来，需要重新登录。
清理时提示 Agent 正在运行: 先退出这个 Agent 再清理：它运行时，会话、记忆和登录正在使用中。

输入替换

连接后 Agent 连不上模型: 输入替换页会显示每个 Agent 的状态。如果提示中转服务没在运行，点「重新连接」；也可以随时「断开」，Agent 会恢复直接连接。
为什么显示「被绕过」？: 有别的工具改了 Switch 写进去的那项设置，例如切换了 Codex 的 provider，或改了 Claude Code 的接口地址。点「重新连接」即可。
为什么我的 Agent 不能连接？: 目前的限制：Claude Code 不支持 Bedrock 和 Vertex；Codex 需要使用自定义 provider，不能用内置的 OpenAI 登录；ZCode 不支持账号登录的 Coding Plan；Grok Build 要先运行过一次。

反馈与求助

怎么反馈问题或提需求？: 在 App 的「设置 → 关于」里点「问题上报」或「提需求」，会打开预填好的 GitHub 表单，你检查后提交。也可以到 GitHub Discussions 留言，或在 LINUX DO 社区、Telegram 交流群里讨论。
反馈时要注意什么？: GitHub issue 是公开的。不要填写 token、cookie、私人路径、完整配置或提示词正文。安全漏洞请不要在 Discussion 中公开披露。