Pi Coding Agent 自定义 API 教程：models.json 与认证优先级

本页仅适用于 pi.dev 的终端 Pi Coding Agent。它与 Inflection 的个人聊天产品 Pi 不是同一个客户端；后者的官网身份不能用来证明终端配置。2026 年 9 月 30 日核对了前者的官方模型指南，本页未做真实服务联通测试。

Pi 接入关系原创示意图，非运行截图，不代表已联通

图中连线用于说明配置关系，不是接口测试结果。

找到用户级模型配置

Pi 的用户级 Agent 目录默认是 ~/.pi/agent，兼容端点写在其中的 models.json。若设置了 PI_CODING_AGENT_DIR，应以那个目录为准。项目里的 .pi 是另一层配置，不要随手新建同名文件来覆盖用户设置。

已有文件时先备份，合并 providers 下的新条目，而不是用整份示例替换原文件。

一个 Chat Completions 示例

官方用 baseUrl、api 和 models 描述兼容服务；示例中的 openai-completions 是 Pi 的 API 类型标识。以下地址仅作占位，本站未提供对应真实接口，也没有可据此创建 Key 或充值的服务。模型与密钥须以实际服务方提供的参数替换。

{
  "providers": {
    "tutorial-gateway": {
      "baseUrl": "https://80321.cn/v1",
      "api": "openai-completions",
      "apiKey": "YOUR_API_KEY",
      "models": [{ "id": "YOUR_MODEL_ID" }]
    }
  }
}

生产使用不要把真实 Key 写进可共享文件。官方支持 apiKey 使用 $NAME 或 ${NAME} 环境变量引用；应改用受控凭据来源。不要顺手开启图片、缓存或额外兼容开关，这些声明需要服务端证据。

用模型选择器重载并验证

打开 /model 会重新加载模型文件；模型须具备可解析的认证信息才会进入可用列表。先选择新增服务商下的精确模型 ID，再用一句不含敏感内容的短提示验证文字回复。

随后在测试目录检查一次只读文件任务。流式回复、工具参数和图片输入应分别验收，不把一次聊天成功写成全功能兼容。如果 JSON 无法解析，先修文件结构，不要改协议碰碰运气。

凭据被旧配置覆盖时

官方给出的优先级是运行时 --api-key、已保存的 auth.json、models.json 的 apiKey，最后才是提供商环境变量。修改环境变量后仍走旧凭据，要检查启动参数和既有认证来源。

如果密钥只在一个终端有效，核对启动 Pi 的进程是否得到该变量；若服务端拒绝请求，则核对 API 类型与实际支持字段，不以删除全部认证文件作为排错第一步。

小心项目资源和工具权限

Pi 可以按启动它的系统账户权限读写和执行文件，并非每次工具调用都会要求批准。项目信任只控制资源加载，不构成完整沙箱。

首次接入应使用低权限账户或隔离环境，排除生产密钥和私人目录。发现未知扩展要求执行凭据命令时，先停止并审查来源；不要因模型已经能回复就默认其工具行为安全。