1. 两种事实
- 供应商 = 一个 OpenAI 兼容 Base URL + 一个 API key。key 只存系统钥匙串
（macOS 钥匙串 service=
ai.cosk.coskey），不写配置文件、不进日志。 - 上游模型 = 挂在供应商下的一条事实记录：请求上游时的
model字段、走哪条协议、 上下文窗口多少。
上游模型默认只入目录，不会出现在 ChatGPT.app 的选择器里。要让它出现在选择器里， 去「模型映射」页加一条映射，见模型映射与窗口。
2. 新增供应商
进「供应商」页，点右上「新增供应商」，填四个字段：
| 字段 | 说明 |
|---|---|
| 供应商 id | 仅字母数字与 - _；会作为映射 id 的命名空间 |
| 展示名（可选） | 卡片标题，以及自动展示名的前缀 |
| Base URL | OpenAI 兼容端点，照供应商文档原样填（是否带 /v1 以文档为准） |
| API key | 输入不回显；保存时写入系统钥匙串 |
保存后卡片立即出现，标题右侧显示「钥匙串 ✓」：
3. 从上游清单导入模型
卡片右上点「导入模型…」。Coskey 用该供应商的钥匙串密钥拉一次上游 /models，
列出还没入库的模型：
- 搜索框按名字过滤，模型多时不用翻长列表；搜索只影响显示，不会丢掉已勾选项；
- 全选当前结果 = 勾选当前搜索结果里的全部；
- 勾好之后点「导入 N 个」。
导入时逐个探测 /responses 并按结论落库，完成后模型出现在卡片里：
- 原生 = 上游原生支持
/v1/responses，请求直接透传（保留工具定义与系统指令）； - 转译 = 上游只有 chat/completions，由本地翻译层做 responses ⇄ chat 双向翻译， 流式与工具调用照旧；
- 「被谁使用」列还是空的（—）：模型进了目录，但还没出现在 ChatGPT.app 选择器里。
上游清单里没有的模型（自建网关常见）用「+ 添加模型」手工录入：填上游
model字段、 窗口事实值，同样会自动探测协议。
4. 卡片上的其它操作
| 操作 | 说明 |
|---|---|
| 导入模型… | 拉上游 /models 清单，搜索、多选导入（推荐方式） |
| + 添加模型 | 手工录入单个模型 |
| 测速 Base URL | 测你填的地址是否可达、往返耗时 |
| 测试连接 | 按该模型标记的协议发一次最小请求，返回结论与耗时 |
| 编辑 / 删除 | 删除供应商会连带其模型、选择器条目与钥匙串条目（有二次确认） |
| 「被谁使用」列 | 显示该上游模型在 ChatGPT.app 选择器里出现的名字；空白表示还没建映射 |
配置改完记得退出并重新打开 ChatGPT.app。
下一步：模型映射与上下文窗口。