平台支持矩阵
AI Switch 认识 7 个目标平台，每个平台在 10 种能力上的支持情况是在代码里显式声明的，不是运行时猜的。这一页把完整矩阵列出来，并解释每种能力和每个状态的实际含义。
两类支持级别
7 个平台分成两类：
原生支持（supported）—— Codex、Claude Code、Gemini CLI、Grok
AI Switch 认识这些工具的配置文件格式和官方登录态格式。10 项能力全部可用（唯一例外见下面的 Gemini CLI 额度查询）。
只有 API 账号（partial）—— OpenCode、OpenClaw、Hermes
这三个是 agent harness，不是模型厂商 —— 它们没有自己的官方登录态。所以官方账号那一半能力（导入、官方账号路由、deeplink、额度查询）对它们不存在，partial 现在只指这件事。
其余能力它们都有：配 API 账号、通过本地代理路由、写入原生配置、启动终端、管理会话。唯一的额外约束是 API 账号必须显式填 Base URL 和接口格式 —— 这三个平台没有默认方言。
完整矩阵
三种状态：
- ✅ 支持 —— 完整可用
- ◐ 部分支持 —— 可用，但有额外前置条件
- ✕ 不支持 —— 调用会被拒绝
| 能力 | Codex | Claude Code | Gemini CLI | Grok | OpenCode | OpenClaw | Hermes |
|---|---|---|---|---|---|---|---|
route_credentials | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
generic_api_routing | ✅ | ✅ | ✅ | ✅ | ◐ | ◐ | ◐ |
config_write | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
official_import | ✅ | ✅ | ✅ | ✅ | ✕ | ✕ | ✕ |
official_account_routing | ✅ | ✅ | ✅ | ✅ | ✕ | ✕ | ✕ |
deeplink_import | ✅ | ✅ | ✅ | ✅ | ✕ | ✕ | ✕ |
official_quota | ✅ | ✅ | ✕ | ✅ | ✕ | ✕ | ✕ |
model_test | ✅ | ✅ | ✅ | ✅ | ◐ | ◐ | ◐ |
terminal_launch | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
session_resume | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
一个例外：Gemini CLI 的额度查询
矩阵里唯一不按「原生支持 = 全绿」规律的格子是 Gemini CLI 的 official_quota。
Gemini CLI 是原生支持平台，配置写入、官方导入、官方账号路由都可用，但官方额度查询不可用（capability.quota_unavailable）。所以 Gemini 账号不会显示官方额度信息，也不能刷新额度。
其余三个原生平台（Codex、Claude Code、Grok）10 项能力全部支持。
10 种能力分别是什么
route_credentials
管理该平台的路由账号：创建、编辑、删除、加入或移出算力池。
7 个平台全部支持。 这是最基础的能力 —— 任何平台都可以配路由账号。
generic_api_routing
通过本地路由代理转发该平台的 API 请求。
原生四平台完整支持。OpenCode、OpenClaw、Hermes 是部分支持，原因码 capability.api_credentials_only：
仅支持已配置 Base URL 和接口格式的 API 账号。
具体限制有三条：
- 只接受
api类型的账号，官方登录态类型的账号不参与路由 - 必须显式提供 base URL
- 必须显式提供接口格式（上游 dialect）
原生四平台有默认 dialect（Codex 和 Grok 是 openai，Claude 是 anthropic，Gemini 是 gemini），这三个平台没有默认值，所以你不填就没法用。
注意「部分支持」不等于不能用 —— 它照样能路由，只是不给你省这两个字段。
config_write
把 CLI 的原生配置文件指向本地路由代理。
7 个平台全部支持，对应的目标文件：
| 平台 | 目标文件 | 格式 |
|---|---|---|
| Codex | ~/.codex/config.toml（外加 ~/.codex/ai-switch-model-catalog.json） | TOML |
| Claude Code | ~/.claude/settings.json | JSON |
| Gemini CLI | ~/.gemini/settings.json | JSON |
| Grok | ~/.grok/settings.json | JSON |
| OpenCode | ~/.config/opencode/opencode.json | JSON |
| OpenClaw | ~/.openclaw/openclaw.json | JSON |
| Hermes | ~/.hermes/config.yaml（HERMES_HOME 为绝对路径时以它为准） | YAML |
后三个平台的写入内容与前四个不同 —— 它们不是靠环境变量接入，而是各自往「自定义 provider」结构里塞一条 ai-switch 记录，再把默认模型指向它：
| 平台 | 写入位置 | 关键字段 |
|---|---|---|
| OpenCode | provider["ai-switch"] | npm: "@ai-sdk/openai-compatible"、options.baseURL、options.apiKey、每个模型的 models.<id>.limit.{context,output}；再把顶层 model 设为 ai-switch/<首个模型> |
| OpenClaw | models.providers["ai-switch"] | api: "openai-completions"、baseUrl、apiKey、models[] 里每项的 id / contextWindow / maxTokens；再把 agents.defaults.model.primary 设为 ai-switch/<首个模型> |
| Hermes | custom_providers 里 name: ai-switch 的那条 | base_url、api_key、api_mode: chat_completions、单数 model 与复数 models.<id>.context_length；再写 model: 段的 provider / default / base_url / api_mode |
三点值得单独说明：
Base URL 带 /v1。 这三个客户端拼的是裸端点（{base}/chat/completions），所以 /v1 必须在 base URL 里，和 Codex 一样。Claude / Gemini / Grok 反过来 —— 它们自己拼带版本号的路径，写 /v1 会变成 /v1/v1/messages。
Hermes 的 api_key 是内联写死的。 这是「Hermes 报缺少 API Key」的真因：Hermes 找不到内联 key 时，会去 ~/.hermes/.env 或按端点 host 推导出的环境变量里找（openrouter.ai 对应 OPENROUTER_API_KEY，以此类推）。回环地址匹配不上任何 host，所以手写一条只有 base_url 的 provider，Hermes 就无处可读 key。
协议一律用 Chat Completions（@ai-sdk/openai-compatible / openai-completions / chat_completions）。这是刻意的：代理的 chat-completions 桥接与平台无关，能把它转成四种上游方言里的任何一种，所以同一条记录既服务 OpenAI 池，也服务 Responses、Anthropic、Gemini 池。
这三个平台写入前必须有模型
它们都不会去探测自定义 provider 的 /v1/models，所以模型清单得由写入时带进文件。而且和原生四平台不同，它们没有内置的基准模型列表，因此算力池为空、或池内账号一个模型映射都没配时，写入会以 config.pool_models_empty 失败。至少配一条模型映射。
后三个平台仍需你自己填的场景（比如接一个 AI Switch 不认识的第三方工具）：点工具栏的 🔌 按钮，在弹窗的「其他 Agent」标签页复制 Base URL 和 API Key。
official_import
导入平台官方的登录态或账号凭据。AI Switch 支持多种输入：OAuth CPA、API Key CPA、session JSON、auth.json、Sub2API JSON、accessToken、refresh_token。
原生四平台支持。后三个不支持，原因码 capability.official_account_unavailable：
该平台不支持官方账号导入或官方账号路由。
official_account_routing
用导入的官方账号（而不是 API key 账号）来路由请求。
原生四平台支持，后三个不支持，同样是 capability.official_account_unavailable。这也是为什么它们的 generic_api_routing 限定只接受 api 类型账号。
deeplink_import
通过 deeplink 导入账号。桌面端注册了 aiswitch 这个 URL scheme。
原生四平台支持。后三个不支持，原因码 capability.deeplink_unavailable：
该平台不支持 Deeplink 导入。
official_quota
查询和刷新官方账号的额度信息。
Codex、Claude Code、Grok 支持。Gemini CLI 不支持。 OpenCode、OpenClaw、Hermes 也不支持。不支持的原因码统一是 capability.quota_unavailable：
该平台不支持官方账号额度刷新。
算力池的路由逻辑会参考账号的剩余额度过滤（剩余额度为 0 的账号不参与选择），但这个信息依赖额度查询能力。Gemini 账号拿不到官方额度，所以只能靠失败反馈来发现账号不可用。
model_test
对账号发起真实生成测试。这不是可达性探测 —— AI Switch 会真的让上游生成一段内容，然后展示模型输出和完整的请求链路。
原生四平台完整支持。后三个是部分支持，同样是 capability.api_credentials_only —— 只能测试配好了 base URL 和接口格式的 api 账号。方言覆盖对它们四种全开（只有 Gemini CLI 锁死在 gemini，因为它的入站流量从不桥接；Grok 锁死在 openai，因为 xAI 只提供这一种）。
详见 模型连通性测试。
terminal_launch
从 AI Switch 启动系统终端并运行该平台的 CLI。
7 个平台全部支持。
session_resume
恢复该平台之前的会话，可以在系统终端里恢复，也可以复制恢复命令自己执行。
7 个平台全部支持。
详见 会话管理。
「部分支持」和「不支持」在行为上的区别
这两个状态的差别很关键，因为它决定了操作会不会被拒绝。
部分支持（partial）的操作是可以调用的。 AI Switch 只是附带了额外约束（必须是 api 类型账号、必须有 base URL、必须有接口格式），满足条件就正常执行。界面上会显示原因码对应的提示文字，告诉你为什么有限制。
不支持（unavailable）的操作会被拒绝。 调用直接返回 capability.unavailable 校验错误，消息形如 Hermes does not support official_import，并附带具体原因码。界面上对应的按钮会被禁用，鼠标悬停显示原因。
这套检查在服务端强制执行，不只是界面上的置灰 —— 即使绕过界面直接调命令，也会被同一套规则拦住。
原生配置写入的安全性
7 个平台的配置写入都不是简单的覆盖文件：
原生配置写入采用安全直写：变更前建立快照、原子写入、检测并发修改、支持带守卫的回滚。
四层保障：
变更前建立快照。 每次写入前先把原文件存一份到 ~/.ai-switch/backups/config-snapshots/（Unix 上权限 0700）。写入结果面板会显示对应的快照 id。
原子写入。 不会出现写一半的配置文件。
检测并发修改。 如果文件在 AI Switch 读取之后、写入之前被别人改了（你手动编辑、另一个工具改了），会被检测出来，而不是默默覆盖掉。写入结果里带变更前后的哈希。
带守卫的回滚。 出问题可以回滚到快照，回滚本身也有守卫检查，不会盲目覆盖当前状态。
另外，写入是增量的：AI Switch 只增改自己管理的字段，你在这些文件里的其他配置项会被保留。比如 Claude Code 的 settings.json 里已有的 env 项和其他设置不会被清掉。
Hermes 的 config.yaml 还多一层保护：它自带大量注释、官方文档也让人手改，所以 AI Switch 只对 custom_providers: 和 model: 这两段做文本替换，其余内容按字节原样保留。反过来，读不懂的文件一律拒写而不是覆盖：OpenClaw 的 openclaw.json 名义上是 JSON5，但 AI Switch 按严格 JSON 解析，遇到注释或不带引号的键会报 validation.route_config_existing_invalid —— 一次删掉你所有 provider 的重写，比拒绝要糟得多。
平台标识和别名
命令和 API 里用的平台 id 是：codex、claude、gemini、grok、opencode、openclaw、hermes。
解析时接受一些别名：
| 平台 id | 接受的别名 |
|---|---|
codex | openai、chatgpt |
claude | anthropic、claude_code、claude_desktop、claude-code |
gemini | google、gemini_cli、gemini-cli |
grok | xai、x_ai、x.ai |
opencode | open_code、open-code |
openclaw | open_claw、open-claw |
hermes | —— |
解析大小写不敏感，空格和连字符会被规范化成下划线。但只接受显式别名 —— 像 my-claude-wrapper 这种包含平台名的字符串会被拒绝，返回 platform.unknown，不会被模糊匹配到 Claude。