pi-ai 的目录，带各自的认证方式）。除此之外你可以：
- 加自定义端点 —— 任何 OpenAI 兼容的 API
- 从其他工具导入 —— 已经在 opencode / Codex / ZCode / cc-switch 里配好的服务
- 覆盖模型属性 —— 比如给某个模型补上思考档位映射
内置服务
内置目录由pi-ai 提供，每个服务带自己的认证方式（环境变量、系统凭据等）。
设置 → 模型服务里能看到全部内置服务与它们的状态。
内置目录是只读快照。你能做的是往里加（自定义端点、导入的模型），
以及在模型粒度上覆盖属性。删内置服务不在支持范围内——
它随
pi-ai 版本更新，不适合本地删改。自定义端点
任何 OpenAI 兼容的 API 都能接。填三样东西：名称、Base URL、API Key， 再加一个模型 id 列表。Base URL
完整前缀，语义与 OpenAI SDK 一致——具体端点（
/chat/completions 之类）
由 API 实现在其后拼接，所以填到路径段即可，不要带尾部的具体端点。API Key
存在本地，不外传。可以留空走环境变量。
模型 id
一行一个。id 必须与服务端实际接受的字符串一致。
Base URL 末尾的斜杠会被去掉，重复斜杠也容忍——但路径段本身不能错。
填
https://host/v1 是对的，填 https://host/v1/chat/completions 会拼坏。从其他工具导入
如果你已经在别的工具里配好了模型服务，可以直接导入，不用手抄。 设置 → 模型服务里有导入入口，会扫描这几个来源并把找到的候选列出来， 你可以逐条勾选后导入。路径不硬编码。opencode 走 XDG（
$XDG_CONFIG_HOME 或 ~/.config，
Windows 上是 %APPDATA%）；Codex 和 ZCode 都在用户目录下。导入时发生了什么
导入器的解析逻辑是纯函数（文本进、候选出，不碰文件系统）， 所以各家配置格式变了、字段缺了，都有单测能立刻发现。 三个解析器归一化到同一个形状，前端预览弹窗只认这个形状，不认各家原始格式。 这意味着导入预览里看到的字段就是最终会存下来的字段。覆盖模型属性
模型目录之上可以做模型粒度的属性覆盖，比如：- 补上某个模型的
thinkingLevelMap——决定它支持哪些思考档位（关 / 低 / 中 / 高 …） - 调整上下文窗口等展示属性
思考档位的映射和 UI 上的档位选择器是同一份数据。
某个模型显示不出思考档位，通常就是它缺
thinkingLevelMap——
覆盖一条就能出来。凭据从哪来
内置服务的凭据由pi-ai 的凭据存储负责，可能是环境变量、也可能是系统钥匙串。
自定义端点的 API Key 存在本地存储里。
两者都不参与提示词缓存的键计算——但模型 id 会。
换模型会改变工具表与系统提示词的字节内容，从而让前缀缓存失效一次。
换回同一个模型会重新命中。
排查
模型不出现在选择器里
自定义服务先确认 Base URL 与模型 id；导入的先看扫描结果里有没有它——
文件路径不对是常见原因（尤其是 XDG 目录被改过的情况）。
选了模型但对话报认证错
自定义端点看 API Key；内置服务看它的凭据来源（多为环境变量）。
401/403 基本都是这一层。
没有思考档位可选
该模型缺
thinkingLevelMap，在覆盖里补一条。导入扫不到东西
先确认源文件真的存在（路径见上表）。扫描对「文件不存在」是静默的，
不会报错——它只报「找到了 0 条」。
下一步
提示词缓存
为什么换模型会让缓存失效一次。
远程与移动端
端点与密钥在多端之间怎么同步。