AI Switch

简体中文

English

简体中文

English

外观

常见问题 ​

AI Switch 和我自己改 CLI 配置文件有什么区别？ ​

手改配置文件能切一次账号，AI Switch 解决的是"切换之后"的事。

具体差异：

  • 一次改，多个 CLI 生效。Codex、Claude Code、Gemini CLI、Grok 的配置格式各不相同，AI Switch 用统一界面写入各自的原生格式。
  • 写入是安全的。每次写配置前先做快照并记录哈希，原子写入，检测并发修改，写坏了可以回滚。手改没有这层保护。
  • 切换可以是自动的。账号进入冷却或额度耗尽后，请求会自动落到池里的下一个账号，不需要你在报错后手动去改文件。
  • 能看到发生了什么。用量、token 数、计价、失败原因、上游原始错误体都有记录。

如果你只有一个账号且从不切换，手改确实够用。账号一多、或者你希望失败时自动接管，差别就出来了。详见快速开始与账号与算力池。

支持哪些平台？为什么 OpenCode、OpenClaw、Hermes 只有通用 API 路由？ ​

共 7 个平台。前四个是原生支持，后三个是通用 API 路由：

平台支持程度
Codex原生：API 路由、写配置、官方账号导入与额度
Claude Code原生：同上（额度取决于上游账号流程是否允许）
Gemini CLI原生：API 路由、写配置、导入；不声称官方额度
Grok原生：同 Claude Code
OpenCode通用 API 路由
OpenClaw通用 API 路由
Hermes通用 API 路由

后三个之所以只有通用路由，是因为 AI Switch 不声称能可靠地解析和改写它们的原生配置、导入官方账号或读取官方额度。它们仍然可以作为 API 路由账号使用、可以从终端启动、可以做会话管理——只是给这些账号建凭据时必须显式填写 base URL 与 API 协议，因为 AI Switch 不会为它们猜默认值。

完整的能力矩阵（10 种平台能力 × 7 个平台）见平台支持矩阵。

什么是协议桥接，我什么时候需要它？ ​

不同 CLI 说不同的"方言"，不同的上游服务也说不同的方言。协议桥接就是在中间做翻译。

AI Switch 支持 4 种上游协议：openai、openai-responses、anthropic、gemini。本地入口的协议是固定的——Codex 入口用 OpenAI Responses，Claude 入口用 Anthropic Messages。当入口协议与你选的上游账号协议不一致时，桥接自动介入，共 7 条桥接链路。

你需要它的典型场景：你有一个 Anthropic 协议的账号，但想用 Codex CLI 来用它；或者你有个 OpenAI 兼容的第三方端点，想让 Claude Code 走过去。两种情况下你都不用改 CLI，只要在 AI Switch 里选好账号的上游协议即可。

你不需要关心它的场景：账号协议和 CLI 天然匹配（比如 Claude Code 配 Anthropic 账号），桥接不会介入，请求原样转发。

原理与各链路的行为差异见协议路由与桥接。

端口 19527 和 3090 有什么区别？ ​

这是两个完全不同的东西，很容易搞混，务必分清：

本地路由代理 · 19527Web 服务 · 3090
默认地址127.0.0.1:19527127.0.0.1:3090
谁来连它你本机的 AI CLI你的浏览器或手机
传什么模型推理请求，被改写后转发给上游AI Switch 界面自身的 API 与事件推送
用什么鉴权路由代理密钥（AI Switch 写进各 CLI 配置）Web 访问令牌（HTTP Bearer）
不开会怎样CLI 无法通过 AI Switch 路由，但界面照常可用只能用桌面应用，浏览器访问不了

一句话记法：19527 是给 AI 用的，3090 是给你用的。

两者互相独立。只在桌面端管理账号可以完全不开 3090；只想在手机上看用量统计也不必开 19527。路由代理的配置见账号与算力池，Web 服务的配置见Web 服务模式。

我的 API key 存在哪里，安全吗？ ​

密钥保存在本地数据目录 ~/.ai-switch 下的 SQLite 数据库中，具体在 route_credentials 表的 secret_payload_json 列。

要说清楚的是：当前版本没有对这一列做静态加密，也没有使用操作系统的钥匙串。所以安全性等价于"你本机文件系统的安全性"——请把整个 ~/.ai-switch 目录当作凭据目录来对待：

  • 注意目录与数据库文件的权限，不要让同机器上的其他用户可读。
  • 不要把它放进公开仓库、未加密的同步盘或共享目录。
  • 建议在开启了全盘加密的磁盘上使用。
  • 备份这个目录时，按机密数据处理（加密压缩包、离线存储）。

Web 服务侧另有一层保护：所有 /api/* 与 /ws/events 请求都要带访问令牌；11 个敏感命令（凭据导出/导入、读取代理密钥、MCP 与技能的写入操作）在传输不满足安全要求时会返回 404 而不是 403，连"这个命令存在"都不透露。此外，绑定到非回环地址且未配置 TLS 时，Web 服务会直接拒绝启动，而不是降级运行。

数据目录的结构见桌面端部署。

账号额度用完会怎样？怎么自动切换？ ​

账号按 1–5 的优先级参与调度，默认 3，数字小的先用。每个账号还有并发上限，新账号默认 5——账号跑满 5 个在飞请求后，下一个请求会去找池里的下一个账号。

当一个账号失败或额度耗尽时，AI Switch 会：

  1. 记录失败类型、失败消息，以及上游返回的原始错误体
  2. 区分是瞬时失败（累计计数、按退避时间安排重试）还是额度耗尽（进入冷却直到额度窗口重置）
  3. 识别连续出现的同类语义失败，避免在一个已经坏掉的账号上反复浪费请求
  4. 把请求交给池里下一个可用账号

自动恢复由后台的恢复调度器负责，可以按计划时间重新启用，也可以用健康检查探测。详见稳定性与自动恢复。

什么时候该把并发上限调低？

官方账号和部分第三方端点对并发敏感：同一账号并发多路请求容易触发限流，甚至被判定为异常使用。遇到这类上游就把该账号的上限调到 1 或 2，让 AI Switch 把并发分散到多个账号（这正是算力池的意义），而不是压在单个账号上。

能不能在手机上用？ ​

可以。开启 Web 服务后，用手机浏览器访问并输入访问令牌即可——桌面和浏览器跑的是同一份界面，功能没有阉割版。

要点：

  • 默认绑定 127.0.0.1:3090，只有本机能访问。手机要访问必须改绑定地址或走 Tailscale。
  • 绑定到非回环地址（比如 0.0.0.0）时必须同时配置 TLS，否则 Web 服务会直接拒绝启动并报 web.sensitive_transport_requires_tls。这不是警告而是硬性拦截——明文 HTTP 暴露到局域网上会让访问令牌和凭据裸奔。
  • 更推荐的做法是启用 Tailscale：手机装上 Tailscale 客户端加入同一个 tailnet，就能在不暴露公网端口、也不必自己张罗证书的前提下访问。

配置步骤见Web 服务模式与远程访问与 HTTPS。

走 Tailscale 就不用令牌了吧？ ​

还是要的。 这是刻意设计，不是遗漏。

Tailscale 只解决"网络可达性"，不代替应用层鉴权。无论请求是从本机来、从 tailnet 内某台设备来、还是通过 Tailscale Funnel 从公网进来，/api/* 与 /ws/events 的令牌校验都不会被跳过。

理由很直接：tailnet 里的任何设备（包括别人共享给你的、或者某台被入侵的设备）都能连到你的节点。少一层令牌，就等于把账号管理界面对整个 tailnet 敞开。

另外 Tailscale 登录是手动的，应用不会在启动时自动登录。

数据存在哪里，怎么备份？ ​

所有数据在用户主目录下的 ~/.ai-switch/：

text
~/.ai-switch/
├── ai-switch.db              # 主数据库（开发版为 ai-switch-dev.db）
├── settings.json             # 应用设置
├── web-service.json          # Web 服务配置
├── route-proxy-https.json    # 路由代理 HTTPS 配置
├── backups/
│   └── config-snapshots/     # 每次写 CLI 配置前的快照
├── certs/route-proxy/        # 路由代理自签证书
├── imports/
├── logs/
└── tailscale/

备份整个目录就够了——账号、设置和密钥都在里面（密钥在数据库中）。正因如此，这份备份本身就是一份凭据：请加密存放，不要放进公开仓库或未加密的同步盘。

数据目录的位置不可配置。README 里出现过的 AI_SWITCH_DATA_DIR 在当前代码中并未实现，设置它不会有任何效果——程序始终使用运行用户主目录下的 .ai-switch。需要换位置的话，只能通过控制运行账号的主目录或容器卷挂载来实现。

如果目标是把账号搬到另一台设备，比拷目录更推荐内置的凭据导出/导入功能，它会记录来源溯源信息。

升级到 0.7.3 后账号列表空了，数据还在吗？ ​

在。 数据没有被删除，只是被挪到了 ~/.ai-switch/backups/ 下，文件名形如 ai-switch.db.migration-conflict-<时间戳>。

起因是 0.7.3 把两个数据库迁移脚本的行尾从 CRLF 改成了 LF。SQL 语句一个字都没变，但迁移校验和是对文件原始字节计算的，于是所有已安装的旧版本在启动时都判定"迁移被改过"，触发了当时的兜底逻辑：把数据库整个移入 backups/ 并新建一个空库。

0.8.0 起：

  • 仅行尾差异导致的校验和不匹配会被原地修复，不再隔离数据库；
  • 如果本地库是空的、而 backups/ 里存在被隔离的库，启动时会自动恢复它（先在副本上验证能升级到当前结构，且绝不覆盖你在此之后新建的账号）；
  • 真正改动过迁移内容且库里有数据时，应用会报错拒绝启动，而不是替换数据库。

所以升级到 0.8.0 后打开应用，账号列表应当自行恢复。若没有恢复，把 backups/ 里时间戳最新的那个 migration-conflict 文件复制回 ~/.ai-switch/ai-switch.db（先关闭应用），再启动即可。

支持哪些操作系统？ ​

Windows、macOS、Linux 三平台，每次发布都由 CI 在三个平台上分别构建：

系统安装包格式
WindowsNSIS 安装器（.exe）
macOS.dmg 与 .app
Linux.deb 与 .AppImage

桌面端支持自动更新（更新包带 minisign 签名，客户端会验签）。独立服务器与 Tailscale sidecar 也为三平台分别提供二进制压缩包。

下载与安装见安装。

AI Switch 是开源的吗？用什么许可？ ​

是。许可为 MIT，Copyright (c) 2026 xyito。

源码仓库：https://github.com/ijry/ai-switch

MIT 意味着你可以自由使用、修改、分发，包括商用，只需保留版权与许可声明。第三方依赖的许可信息见仓库的 LICENSES/ 目录与 THIRD_PARTY_NOTICES.md。

AI Switch 和 cc-switch 是什么关系？ ​

AI Switch 兼容 cc-switch 的导入协议，目的只有一个：让使用 cc-switch 的用户能方便地把配置迁移过来。新增账号对话框的「导入其他客户端」标签还能直接读取本机 ~/.cc-switch 下的配置文件（只读打开，不改动对方数据），勾选后把 API 账号搬过来；桌面端也可以选择性开启 ccswitch:// 深链兼容（默认关闭），这样原本发给 cc-switch 的导入链接也能被 AI Switch 接收。

除此之外没有关系。AI Switch 是从零实现的独立项目：本项目只研究公开行为、公开文档和公开文件格式，不复用其代码。 仓库 README 的 "Clean-Room Boundary" 一节就是明确这条边界的。

换句话说，兼容体现在"能读懂同一种配置/导入格式"这个层面，而不是共享实现。

桌面端会自动更新吗？ ​

会。更新器指向仓库 Release 的 latest.json 清单，客户端会用内置的公钥校验安装包的 minisign 签名，验签失败不会安装。

发布流程中有一道专门的校验，确保签名密钥与配置里的公钥属于同一对——防止密钥轮换后更新链路静默断裂。细节见发布流程。

MCP 服务器和技能能管到哪些客户端？ ​

MCP 管理覆盖 11 个客户端的配置文件，包括 Claude Code、Codex、Gemini、Grok、OpenCode、OpenClaw、Hermes、Cursor、Cline、CodeBuddy、Kimi Code。你可以在一个界面里装一次 MCP 服务器，然后勾选要写入哪些客户端。

技能方面内置 2 个技能包共 27 个技能：ai-switch.core（14 个，工程流程类）与 ai-switch.science（13 个，科研方法类）。

详见MCP 服务器与技能管理。

基于 MIT 许可发布

Copyright © 2026 xyito