常见问题
AI Switch 和我自己改 CLI 配置文件有什么区别？
手改配置文件能切一次账号，AI Switch 解决的是"切换之后"的事。
具体差异：
- 一次改，多个 CLI 生效。Codex、Claude Code、Gemini CLI、Grok 的配置格式各不相同，AI Switch 用统一界面写入各自的原生格式。
- 写入是安全的。每次写配置前先做快照并记录哈希，原子写入，检测并发修改，写坏了可以回滚。手改没有这层保护。
- 切换可以是自动的。账号进入冷却或额度耗尽后，请求会自动落到池里的下一个账号，不需要你在报错后手动去改文件。
- 能看到发生了什么。用量、token 数、计价、失败原因、上游原始错误体都有记录。
如果你只有一个账号且从不切换，手改确实够用。账号一多、或者你希望失败时自动接管，差别就出来了。详见快速开始与账号与算力池。
支持哪些平台？为什么 OpenCode、OpenClaw、Hermes 是「部分支持」？
共 7 个平台。7 个都能路由 API、写配置，区别在官方账号那一半：
| 平台 | 支持程度 |
|---|---|
| Codex | 原生：API 路由、写配置、官方账号导入与额度 |
| Claude Code | 原生：同上（额度取决于上游账号流程是否允许） |
| Gemini CLI | 原生：API 路由、写配置、导入；不声称官方额度 |
| Grok | 原生：同 Claude Code |
| OpenCode | 部分：API 路由、写配置；无官方账号 |
| OpenClaw | 部分：同上 |
| Hermes | 部分：同上 |
后三个是 agent harness，不是模型厂商 —— 它们没有自己的官方登录态，所以官方账号导入、官方账号路由、deeplink、额度查询这四项对它们不存在，这就是「部分支持」的全部含义。写配置是有的：AI Switch 会往 ~/.config/opencode/opencode.json、~/.openclaw/openclaw.json、~/.hermes/config.yaml 里写一条 ai-switch 自定义 provider。唯一的额外要求是给它们建 API 凭据时必须显式填写 base URL 与 API 协议，因为这三个平台没有默认方言。
完整的能力矩阵（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 上为什么既有网页又有模型 API？
默认共享监听端口是 19527。同一个 listener 按路径分成两类流量：
| 面板流量 | 模型 API 流量 | |
|---|---|---|
| 路径 | /, /api/*, /ws/*, /health | /models, /v1/*, /v1beta/*, /messages, /responses |
| 谁来连它 | 你的浏览器或手机 | 你本机或远程的 AI CLI |
| 传什么 | AI Switch 界面自身的 API 与事件推送 | 模型推理请求，被改写后转发给上游 |
| 用什么鉴权 | Web 访问令牌（HTTP Bearer） | 路由代理密钥（AI Switch 写进各 CLI 配置） |
| 路由接入关闭时 | 继续可用 | 返回 route_proxy.access_disabled |
一句话记法：端口只有一个，权限按流量分开。
路由接入是独立开关：关闭它不会停止共享端口，Web 页面与健康检查仍可用；开启它时如果端口未启动，会自动启动共享端口。路由代理的配置见账号与算力池，Web 服务的配置见Web 服务模式。
我的 API key 存在哪里，安全吗？
密钥保存在本地数据目录 ~/.ai-switch 下的 SQLite 数据库中，具体在 route_credentials 表的 secret_payload_json 列。
要说清楚的是：当前版本没有对这一列做静态加密，也没有使用操作系统的钥匙串。所以安全性等价于"你本机文件系统的安全性"——请把整个 ~/.ai-switch 目录当作凭据目录来对待：
- 注意目录与数据库文件的权限，不要让同机器上的其他用户可读。
- 不要把它放进公开仓库、未加密的同步盘或共享目录。
- 建议在开启了全盘加密的磁盘上使用。
- 备份这个目录时，按机密数据处理（加密压缩包、离线存储）。
Web 服务侧另有一层保护：所有 /api/* 与 /ws/events 请求都要带访问令牌。桌面版直接监听 127.0.0.1 或 0.0.0.0 时，敏感命令在服务启动后开放；环回监听通过 Tailscale 暴露时仍按 sidecar 状态动态切换。选择 0.0.0.0 明文开放后，令牌就是唯一保护。独立 server 则仍默认拒绝非回环明文启动。
数据目录的结构见桌面端部署。
账号额度用完会怎样？怎么自动切换？
账号按 1–5 的优先级参与调度，默认 3，数字小的先用。每个账号还有并发上限，新账号默认 5——账号跑满 5 个在飞请求后，下一个请求会去找池里的下一个账号。
当一个账号失败或额度耗尽时，AI Switch 会：
- 记录失败类型、失败消息，以及上游返回的原始错误体
- 区分是瞬时失败（累计计数、按退避时间安排重试）还是额度耗尽（进入冷却直到额度窗口重置）
- 识别连续出现的同类语义失败，避免在一个已经坏掉的账号上反复浪费请求
- 把请求交给池里下一个可用账号
自动恢复由后台的恢复调度器负责，可以按计划时间重新启用，也可以用健康检查探测。详见稳定性与自动恢复。
什么时候该把并发上限调低？
官方账号和部分第三方端点对并发敏感：同一账号并发多路请求容易触发限流，甚至被判定为异常使用。遇到这类上游就把该账号的上限调到 1 或 2，让 AI Switch 把并发分散到多个账号（这正是算力池的意义），而不是压在单个账号上。
报错「insufficient permissions ... Missing scopes」是什么意思？
完整报错长这样：
You have insufficient permissions for this operation. Missing scopes: api.responses.write. Check that you have the correct role in your organization (Reader, Writer, Owner) and project (Member, Owner), and if you're using a restricted API key, that it has the necessary scopes.
先看这个账号是 API Key 还是官方（OAuth）账号，两种情况原因完全不同。
API Key 账号：Key 的权限不够
OpenAI 的受限（restricted）API Key 是逐项勾选权限的，Missing scopes: 后面点名的那一项就是它没有的。api.responses.write 对应 /v1/responses，model.request 对应旧的 chat/completions 一类端点。报错后半句提到组织和项目角色，容易让人以为要去查团队权限，但绝大多数情况问题在 Key 本身。
两条出路：
- 去签发这个 Key 的平台，把它的权限改成 All，或者单独补上报错里点名的那一项。
- 缺的是
api.responses.write时，把这个账号的接口格式改成OpenAI Chat Completions。"模型调用"和"Responses"是两个独立权限项，只缺后者时走 chat/completions 通常还能用。
官方账号：v0.8.5 之前是 AI Switch 发错了地址
官方 Codex 账号拿的是 ChatGPT 订阅席位，不是 Platform API 额度，两者是不同的主机：订阅走 https://chatgpt.com/backend-api/codex，Platform API 走 https://api.openai.com。后者只认 API Key、并按 Key 的权限项判定，所以把订阅 token 发过去必然回这句"缺 api.responses.write"——它在报告一把这个账号根本没有的 Key。
v0.8.5 之前，官方 Codex 账号的 Config JSON 里如果没写 base_url（导入示例和大多数授权文件都不带），AI Switch 会默认发往 api.openai.com，于是订阅完全正常的账号也会一直报这个错，而同一份登录态在别的工具里好端端的。v0.8.5 起默认改成了 ChatGPT 后端。
如果你在用旧版且不便升级，可以手工绕开：编辑该账号 → Config JSON 里加一行
"base_url": "https://chatgpt.com/backend-api/codex"中转站托管的 OAuth 账号不受影响：它们的 Config 里本来就写着中转站自己的 base_url，显式值优先，不会被改动。
AI Switch 怎么处理这个错误
账号会一次就置为异常（不像普通失败那样攒够连击才落定），因为缺权限对这个凭据上所有模型都成立，换号、换模型、等冷却都改变不了结果。上游那句原话会保留在账号列表的失败提示和真实生成测试的结果面板里，附一条中文提醒。想确认自己属于哪种情况，点「真实生成测试」展开「查看输入输出」，看 target_url 落在哪个主机上。
能不能在手机上用？
可以。开启 Web 服务后，用手机浏览器访问并输入访问令牌即可——桌面和浏览器跑的是同一份界面，功能没有阉割版。
要点：
- 默认绑定
127.0.0.1:19527，只有本机能访问。手机要访问必须改绑定地址或走 Tailscale。 - 桌面设置可选择
0.0.0.0，无需 TLS 即可向局域网开放；全部 Web 命令都会通过明文 HTTP 提供，访问令牌是唯一保护，请只在可信网络使用。独立 server 的非回环明文限制不变。 - 更推荐的做法是启用 Tailscale：手机装上 Tailscale 客户端加入同一个 tailnet，就能在不暴露公网端口、也不必自己张罗证书的前提下访问。
配置步骤见Web 服务模式与远程访问与 HTTPS。
走 Tailscale 就不用令牌了吧？
还是要的。 这是刻意设计，不是遗漏。
Tailscale 只解决"网络可达性"，不代替应用层鉴权。无论请求是从本机来、从 tailnet 内某台设备来、还是通过 Tailscale Funnel 从公网进来，/api/* 与 /ws/events 的令牌校验都不会被跳过。
理由很直接：tailnet 里的任何设备（包括别人共享给你的、或者某台被入侵的设备）都能连到你的节点。少一层令牌，就等于把账号管理界面对整个 tailnet 敞开。
另外 Tailscale 登录是手动的，应用不会在启动时自动登录。
数据存在哪里，怎么备份？
所有数据在用户主目录下的 ~/.ai-switch/：
~/.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 在三个平台上分别构建：
| 系统 | 安装包格式 |
|---|---|
| Windows | NSIS 安装器（.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 个，科研方法类）。