Claude CLI 接入手册
面向 Claude Code 命令行（claude）用户。SynaRoute 在本机起一个代理，把 claude 的请求按你配置的多个 Key 做故障转移与模型映射——一个不可用了自动换下一个。
解决什么问题
你手上有多个 AI 服务的 Key（不同厂商、不同中转），希望 claude 命令行能做到：
- 一个 Key 限流或不可用时自动切到下一个，不用手动改配置；
- 不同厂商的模型名对不上时（客户端要
claude-opus-*，上游只认别的名字）自动映射； - 密钥本地加密存放，不散落在各处明文配置里。
SynaRoute 在 127.0.0.1 上开一个本地代理端口，claude 把请求发给它，它再按你的规则转发给真正的上游。只监听本机，不对外。
安装
- 从下载页获取安装包，双击安装（当前用户安装，无需管理员权限）。
- 首次运行如提示缺少 WebView2，安装包会自动下载安装（Windows 11 一般自带）。
- 从开始菜单启动 SynaRoute。
卸载方式与普通软件一致：控制面板 → 程序 → 卸载。
前置要求：Claude Code CLI 需 v2.1.129 或更高。低于此版本时
/model选择器不会拉取代理暴露的模型列表。查看版本：claude --version
三步跑起来
第 1 步：添加 Key
打开 SynaRoute，进入「Claude CLI」分类，点「添加 Key」，填写：
| 字段 | 说明 |
|---|---|
| 名称 | 随便起，方便自己辨认（如 主力、备用） |
| 厂商 / 协议 | 选上游对应的类型（Anthropic 原生 / OpenAI 兼容 / 自定义） |
| Base URL | 上游地址，如 https://api.your-provider.com |
| API 密钥 | 你的上游密钥。本地加密存放，不会写进任何明文配置 |
| 模型 | 可留空（保存后自动拉取），也可手填上游支持的模型名 |
想要故障转移就多加几个 Key。上下拖动可调整优先级，越靠上越先被使用。
第 2 步：点「启动」
在顶部状态条点 启动。这一步会做两件事：
- 在
127.0.0.1上开一个代理端口； - 自动写入
~/.claude/settings.json（原文件会先备份），把claude指向这个代理。
状态条随后显示运行状态、当前地址 http://127.0.0.1:<端口>，以及路由模式（单 Key 为直连，多 Key 为故障转移并显示数量）。地址旁有复制按钮。
你不需要手动改任何配置文件——「启动」已经把 claude 接好了。
第 3 步：正常使用 claude
新开一个终端（让它读到刚写入的配置），照常使用：
claude
claude 现在走的就是 SynaRoute 代理，/model 里能看到 SynaRoute 暴露的可选模型。
关于启动与关闭
- 代理不随应用自启：每次想用，需要在 SynaRoute 里点一次「启动」。
- 关窗口不等于退出：点右上角关闭只是隐藏到系统托盘，代理仍在后台运行，
claude照常可用。想彻底停止：右键托盘图标 → 退出。 - 端口是动态的：每次启动端口可能变化，但启动时会自动把新端口写回
~/.claude/settings.json，新开终端即可，无需手动改。
写入了哪些配置
点「启动」后，SynaRoute 会在 ~/.claude/settings.json 里写入这些字段（改动前自动备份原文件）：
| 字段 | 值 | 作用 |
|---|---|---|
env.ANTHROPIC_BASE_URL | http://127.0.0.1:<端口> | 把 claude 指向本地代理 |
env.ANTHROPIC_AUTH_TOKEN | 占位串 | 代理不校验它，但 CLI 要求该字段存在 |
env.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY | 1 | 让 /model 去代理拉取可选模型列表 |
env.ANTHROPIC_MODEL 与顶层 model | 主 Key 的默认对外模型名 | /model 的默认项 |
同时会删除旧的 ANTHROPIC_DEFAULT_HAIKU/SONNET/OPUS_MODEL（若存在），避免 /model 里出现三个同名条目。三档（Haiku / Sonnet / Opus）由代理内部按规则解析，无需在客户端写死。
想查看当前实际写入的内容，点状态条上的「配置预览」按钮（只读，密钥已脱敏）。
模型是怎么选中的
claude 发来一个模型名（如 claude-opus-4-x），SynaRoute 按优先级从高到低决定真正发给上游哪个模型：
- 精确映射——你为该 Key 配了「客户端名 → 上游真实名」的映射，命中即用。显式意图优先级最高。
- 三档匹配——请求名里含
haiku/sonnet/opus，且你为该 Key 配了对应档位，则用该档模型。 - 原生同名——该 Key 的模型列表里正好有这个名字，原样使用。
- 默认模型——用该 Key 配置的默认模型兜底。
- 列表第一个——以上都没有，取该 Key 模型列表的第一项。
- 透传——该 Key 没配任何模型，原样把请求名发给上游。
容易踩的一点：三档优先级高于「原生同名」。如果你给某个 Key 设了「三档 Opus = 某模型」，那么所有含
opus的请求都会被改写成那个模型，即使该 Key 原生就支持客户端要的名字。不想要这个改写，把对应档位留空即可。
不以 claude / anthropic 开头的模型名（如 grok-4.5）会被 CLI 静默过滤。SynaRoute 会自动把它们包装成 claude-synaroute-<原名> 暴露给 /model，转发时再剥掉前缀。所以在 /model 里看到 claude-synaroute-xxx 是正常的。
故障转移与健康状态
- 多个 Key 时自动故障转移：主 Key 返回限流、繁忙或错误（HTTP 429 / 5xx 等）时，自动切到下一个候选 Key 重试，
claude侧无感知。运行日志里能看到转移记录。 - 健康检查：后台按设定间隔（默认 60 秒）探测各 Key 的可达性，在列表上显示状态与延迟。
- 健康状态只影响界面展示，不挡路由：显示「不可达」的 Key 仍会被真实流量尝试——只有真实请求连续失败才会触发短暂熔断（自动跳过一小段时间）。偶尔看到红色状态不代表这个 Key 不能用。
设置页「调试」区还有两个开关：
- 记录调用模型日志：开启后每次转发都记录「客户端要什么 → 实际发了什么 → 结果」。默认关闭，因为开启后日志会包含完整对话正文。
- 健康检查用真实请求：开启后探测会发一个极小的真实请求，更贴近实际业务；代价是被限流或繁忙的 Key 也会显示为不可达，看着扎眼但不影响实际转发。想少些红字可以关掉它，回到轻量连通探测。
常见问题
/model 里看不到我的模型？
依次确认：CLI 版本 ≥ v2.1.129；SynaRoute 已点过「启动」；该 Key 配了模型（或已成功拉取）；你是在点启动之后新开的终端里跑的 claude。
claude 报连接被拒（connection refused）？
SynaRoute 的代理没在运行。回到 SynaRoute 点「启动」，然后新开终端。注意关窗口只是隐藏到托盘，但如果从托盘选了「退出」就需要重新启动。
某个模型总是返回 502 / 503 / 429？
那是上游返回的，不是 SynaRoute。检查该 Key 对应的上游是否过载、限流或账号有问题。多配几个 Key 可以让故障转移兜底。
请求被改成了我没预期的模型？
多半是该 Key 的某个档位配了值，见上面「模型是怎么选中的」里的提醒。把不想要的档位留空即可。
想临时不用 SynaRoute、直连官方？
SynaRoute 在改动前备份了你的 ~/.claude/settings.json，可以从备份恢复；也可以手动删掉写入的 ANTHROPIC_BASE_URL 等字段。停止代理时同样会自动还原。
密钥安全吗？
密钥经加密后存放在本地的 secrets.enc 里，不会写进 settings.json（那里只有一个占位 token）。配置预览里密钥也做了脱敏。
更新
SynaRoute 内置在线更新：有新版本时侧栏会出现更新标识，设置页可一键检查并安装。也可以直接下载新安装包覆盖安装。
反馈问题
反馈时尽量附上：
- 现象（
claude的报错原文或截图）； - SynaRoute 运行日志里相关的几行，或直接用设置页的「导出诊断报告」；
- 涉及哪个 Key（名称即可）和哪个模型名。
请不要粘贴任何真实密钥。日志与配置预览已做脱敏，但手动复制时仍需自行留意。