使用指南。

下载与安装

Keyway 是桌面端本地网关,不是在线聊天工具,也不会替你安装 AI CLI。macOS 用户按芯片选择 .dmg,Windows 选择安装程序,Linux 选择对应架构的 AppImage、deb 或 rpm 包。

• 准备 CLI:先安装你要使用的 Claude Code、Codex 或 Gemini CLI 等工具,确认它能在终端中启动。Keyway 管理的是这些工具的请求去向。
• 准备供应商:从供应商控制台取得 API Key、API 接口地址和可用模型名。不要假设网页聊天订阅同时包含 API 额度;以供应商账户权限为准。
• 保护已有配置:首次接管前另存一份 CLI 配置。不要同时让多个切换工具改写同一份配置;不确定时先只接入一个 CLI。

下载 for Apple 芯片(M1/M2/M3/M4) Intel 芯片版 Windows 版 Linux AppImage Linux .deb Linux .rpm 全部平台安装包 ›

• 首次打开若提示「无法验证开发者」:在「应用程序」里右键点 Keyway → 打开;或在 系统设置 → 隐私与安全性 中点击「仍要打开」。
• 认准下载按钮显示的版本和文件名(Apple 芯片示例为 Keyway_{版本}_aarch64.dmg):如果双击时提示「没有可打开的应用」,多半是没下载完整,删掉重新下载即可。
• 启动后 Keyway 会常驻菜单栏(托盘),关闭窗口不影响代理运行。
• 本地代理默认监听 127.0.0.1:9527,只接受本机请求。

添加供应商

打开主界面,按 CLI 分组(Claude Code、Codex、Gemini CLI 等)添加你要用的模型供应商:

• 预设直选:内置常见供应商与中转站,填入 API Key 即可用。
• 从现有配置导入:已在 CLI 里配过?一键导入,不用重新填。
• 自定义:填名称、Base URL、API Key,任意中转/自建网关都支持。
• 以 CoderPlan 为例:预设置顶、端点已预填;点 「获取 API Key」直达 coderplan.ai/dashboard/keys,创建并复制 Key,粘贴即可。

添加完成后,可点击供应商卡片上的 测速按钮 检查连通性与延迟,再决定用谁。

这些字段怎么填?

• 名称:使用易辨认的名称,如「主力渠道」或「备用渠道」。编辑已有供应商前确认它是否也被其他 CLI 分组复用。
• 接口地址:填供应商文档中的 API Base URL,不是官网或控制台网址,也不是完整的 /chat/completions 请求地址。按实际协议选择端点;示例 https://api.example.com/v1 仅用于说明,不能直接请求。
• API Key:粘贴该供应商的密钥,不要上传到工单或截图中。编辑时留空表示保留原密钥;换机导入配置后需要重新填写。
• 模型:使用上游支持的准确模型名。卡片中的模型列表用于展示,不会自动为 CLI 改名或开通模型权限;实际请求模型仍需在 CLI 中配置。

一键接管 CLI

点击导航中的网关状态或分组页的 「网关详情」,在接管管理中选择目标 CLI。接管后,Keyway 会把该 CLI 的配置指向本地代理:

• 接管前自动备份原配置,可在接管管理中还原。还原前请确认是否有需要保留的手动修改。
• 首次接管 Codex 后请新开一次会话。接管期间保持 Keyway 运行;完全退出前如需直连,请先还原配置。
• 也可以不接管,手动给 CLI 设置环境变量指向 127.0.0.1:9527(应用内有可复制的变量)。

切换并确认请求去向

卡片上的默认供应商是选择,不是实际请求证明。切换后发送新请求,再从日志确认实际去向:

• 主界面点供应商卡片上的 「切换」,或直接在菜单栏托盘里选,两秒钟完成。
• 全局快捷键 ⌘⇧K(Windows/Linux 为 Ctrl+Shift+K)随时唤起快速切换面板:↑↓ 选择、Enter 切换、Esc 关闭,手不离键盘。
• 已通过代理的会话无需重启。切换影响后续请求,不会迁移已发出的请求;路由规则可能覆盖默认选择。
• 同一供应商可按协议复用到多个 CLI(如一个中转 Key 同时供 Claude Code 和 Codex)。
• Responses 桥接:Codex 的 /v1/responses 请求可按供应商开启桥接,自动转成 /v1/chat/completions 发给只支持 chat 协议的中转站;编辑供应商时勾选即可,官方 OpenAI 等原生支持 Responses 的渠道无需开启。
• 协议转换有边界:Keyway 实现了部分 Anthropic、OpenAI Chat 和 Gemini 请求/响应转换,不代表所有模型、工具、多模态或深度思考参数都能无损兼容。优先使用 CLI 原生协议端点;Codex 的 Responses 桥接需单独开启并用实际任务验证。
• 余额查询:OpenRouter 兼容的中转站,在供应商卡片点钱包图标即可查看已用额度 / 总额度,方便及时充值。
• MCP 服务器统一管理:在 Keyway 里定义一次 MCP 服务器,自动写入 Claude Code 与 Codex 的配置(stdio 支持环境变量);手工配置的条目不受影响,还可逐个测试连接。
• 本地代理提供 http://127.0.0.1:9527/healthz 探活端点,返回版本号与各 CLI 分组当前使用的供应商,方便脚本与健康检查集成。
• 更多应用内快捷键:⌘N 新建供应商、⌘1..5 切换 CLI 分组、⌘⇧M / ⌘⇧S 直达 MCP / Skills 管理页(Windows/Linux 对应 Ctrl 组合)。
• Skills 统一管理:本地 vault 集中维护 Skills,一键同步给 Claude Code 与 Codex;CLI 自带或手工添加的 skill 不受影响。

怎样确认第一条请求真的经过 Keyway?

1. 先只配置一组:选择你要用的 CLI 分组,添加一个供应商并点击「切换」。确认已经选中,而不只是出现在列表里。
2. 检查代理:保持 Keyway 运行。在终端执行 curl http://127.0.0.1:9527/healthz(PowerShell 可用 curl.exe)。返回状态、版本与当前供应商仅证明本地代理可访问,不证明上游已连通。
3. 接管并新开会话:在接管管理中接入目标 CLI。首次接管 Codex 需新开会话;其他 CLI 若仍读取旧配置,也请重新启动会话。Gemini 的环境变量可能受终端或项目配置影响。
4. 发一条简单消息:在 CLI 输入「只回复 OK,不要读写文件或调用工具」。这仍是一次真实上游请求,可能产生费用;不要先用长任务或敏感内容测试。
5. 核对日志:回到同一 CLI 分组的「日志」,点击刷新。检查是否出现刚才时间的新记录,供应商、模型和 HTTP 状态是否符合预期。CLI 收到回复且日志记录对应请求,才完成基本验收。
6. 再测试切换:添加备用供应商,切换后再发一条消息,核对新日志的实际去向。路由或故障转移可能覆盖默认选择;不要拿上一条请求的记录判断切换结果。

路由 · 故障转移 · 日志 · 档案

模型路由规则 —— 在「设置 → 模型路由」里,让特定模型永远走特定供应商:

• 例:规则 claude → 中转站 A;规则 deepseek → 官方。CLI 里指定模型名,Keyway 自动分发。
• 匹配方式可选「包含」或「前缀」:前缀更精准,避免关键词误命中。
• 每条规则可临时停用(开关),保留配置不删除;规则从上到下匹配,首条命中生效,可用 ↑↓ 调整顺序。
• 命中规则的请求会在「日志」页打上蓝色标记,分流效果一目了然。
• 场景分流:除长上下文外,还可为「深度思考」(请求开启 thinking 或 reasoning/thinking 档模型)与「后台轻量」(haiku / mini / flash / nano 档小任务)各指定一个供应商 —— 贵模型用在刀刃上,小任务走便宜渠道。
• 长上下文分流:超大数据量的请求(阈值可调,默认 6 万 token 估算)自动改走指定供应商 —— 大上下文走便宜渠道,日常对话不受影响。命中时响应头带 x-keyway-route。

自动故障转移 —— 先分别验证主力与备用供应商,确认它们支持请求中的模型,再为目标分组启用故障转移并检查候选链。可重试的连接失败、429 或 5xx 会尝试后续候选;不是所有错误都重试,也不保证流式响应中途无缝恢复。发生回退时可检查 x-keyway-fallback 响应头。

用量与日志 —— 侧栏「用量」按 CLI / 供应商汇总 token 与成功率;「日志」可查最近 100 条请求(模型、上下行 token、状态码),排障一目了然;日志按天分组,「设置」里还可开启周期健康检测,定时测速当前供应商并同步到托盘。

配置档案与备份 —— 「设置」里可将当前供应商组合保存为档案(工作 / 个人 / 测试一键整组切换),也可导出 JSON 备份(不含密钥,系统保存对话框自选位置),换机无忧;另支持「配置导出/导入」:供应商、路由规则与预设导出为可分享的 JSON,导入按名称自动合并,团队共享配置一步到位。

不再使用代理时,怎样恢复?

1. 先结束正在执行的请求。关闭 Keyway 窗口可以驻留托盘;完全退出会停止本地代理,仍指向代理的 CLI 将无法继续通过它请求。
2. 打开接管管理,逐个还原已接管的 CLI。旧版本还原前请另存当前配置,避免接管期间的新改动被覆盖。新版遇到目标字段冲突会中止并保留现场,不要删掉备份或反复强行覆盖。
3. 检查手动设置。手动添加到终端、shell 启动文件或项目中的代理环境变量不一定由自动还原移除;按自己的改动记录恢复原值。新开 CLI 会话并确认直连可用后,再退出或卸载 Keyway。

换机步骤:在设置中导出供应商备份或可分享配置 → 妥善保存 JSON → 在新设备安装 Keyway 并导入 → 重新填写 API Key → 验证供应商 → 在新设备重新接管 CLI。配置档案只保存各分组的默认供应商选择,不是完整备份;导出配置不含密钥,也不替代 CLI 文件与请求日志的备份。

遇到问题?

• CLI 有回复,日志却没有新记录:先刷新日志并确认分组;再检查终端环境变量、项目配置或其他切换工具是否覆盖了接管地址。不要仅凭供应商卡片的选中状态判断成功。
• Connection refused / 本地代理不可达:确认 Keyway 未完全退出,再检查 /healthz。如果启动时提示端口被占用,先确认占用进程是否为另一实例,不要随意终止未知进程。
• 404 / 模型不存在:核对 API Base URL、端点协议和 CLI 请求的模型名。Codex 使用 Responses 请求时,确认上游支持该接口;只支持 Chat 的渠道需要验证桥接兼容性。
• 429 / 5xx:分别检查供应商限流、额度与服务状态。先降低请求频率,必要时切换已验证的备用渠道;不要连续快速重试放大限流。
• 请求 401 / 403:响应头带 x-keyway-hint,按提示检查 Key 是否有效、额度是否充足。
• 切换没生效:先确认代理运行与 CLI 接管状态,再发送新请求并查看日志。模型路由可能覆盖默认供应商;首次接管 Codex 需新开会话。
• 想恢复原样:分组页「还原」即可,原配置在接管时已备份。
• 数据在哪:配置与用量保存在本机加密数据库;请求内容和认证信息会发给所选上游。卸载不保证清除应用数据或钥匙串记录。