模型与提供方

本页说明如何连接模型提供方、添加你自己的地址、调整模型列表，以及凭据最终存在哪里。

打开 Pi 设置（侧栏底部），选择 模型。第一次在没有任何模型的情况下启动 pi-webapp 时，这一页会自动打开。

提供方是怎么连接的

pi-webapp 显示的是 Pi 支持的提供方，它们来自 pi-webapp 所运行的 Pi 版本，会随版本变化（写这篇文档时有几十个，包括 Anthropic、OpenAI、Google、GitHub Copilot、OpenRouter、Mistral 和 xAI）。每个提供方通过下面一种或两种方式连接：

方式	你会看到	会发生什么
网页登录	一个 网页登录 按钮	提供方的页面会在新标签页里打开。你完成后，设置对话框会自动更新。
API Key	一个 API Key 输入框和 连接	Key 会保存到 Pi 的 auth.json，且不会再发回页面。

连接一个提供方

1. Pi 设置 → 模型 → ＋ 添加提供方（首次启动时这张卡片已经展开）。
2. 在 提供方 列表里选择提供方。
3. 点击 网页登录，或粘贴 Key 后点 连接。
4. 卡片显示 已连接 之后，点 返回会话选择模型，再在对话的模型选择器里选择模型。

如果网页登录无法完成，是因为提供方的回调到不了运行 Pi 的那台机器（远程或容器化的环境），对话框会提供 无法自动完成？手动输入授权码。把提供方显示给你的授权码粘贴进去即可。未完成的登录可以用 取消 终止。

有些提供方需要非默认地址（代理或区域主机）。对使用 Key 的提供方，点击前先展开 自定义设置，在 API 地址（可选） 里填写，再点 连接。

永远不要把 API Key 或登录授权码粘贴进对话里。

添加你自己的地址

任何使用 Pi 所支持协议的服务都可以用自定义提供方接入，包括你本机上的模型服务或公司内部的网关。

1. 如果 添加提供方 卡片是展开的，先关闭它，再点 ＋ 添加自定义提供方。

2. 填写表单：

   字段	含义	示例
   名称	在选择器里显示的名字	我的模型服务
   提供方 ID	一个简短的 ID，最多 64 个字符	my-provider
   接口地址	服务的基础 URL	https://api.example.com/v1
   接口协议	OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages	OpenAI Chat Completions
   模型 ID	服务所要求的模型名	model-name

3. 点 保存并继续，再填写服务要求的 API Key，点 连接。

   

提供方的条目会保存到 models.json，不含 Key；Key 保存到 auth.json。要给同一个提供方添加更多模型，请使用它的 编辑（见下文）。

本机服务请使用 http://127.0.0.1:<端口>/v1 形式的地址。表单仍然要求填 Key，所以如果你的服务不检查 Key，随便填一个占位值即可。

编辑提供方的模型

已连接的提供方会显示 已配置 标记。点击 编辑 可以：

• 替换凭据：输入新的 API Key 后点 保存，或者重新登录。
• 搜索模型目录，选中某个模型来修改它的设置：显示名称、上下文窗口、最大输出 token 数 和 输入类型（文本、图片）。上下文和输出容量接受纯数字，或带 K/M 后缀的写法，例如 128K。
• ＋ 添加模型，填入提供方提供的 模型 ID。
• 恢复默认 撤销你对某个模型的自定义设置，移除模型 则把它从你的配置里去掉。
• 移除认证 删除 pi-webapp 保存的 Key 或登录凭据。之后该模型可能无法使用。

如果没有 移除认证 按钮，说明该提供方的认证来自环境变量、模型配置，或 pi-webapp 之外的其他来源，请在设置它的地方移除。

对模型列表的修改会写入 Pi 的 models.json，随后模型选择器会刷新。

东西都存在哪里

文件	内容	能分享吗？
~/.pi/agent/auth.json	API Key 和登录令牌，仅你的用户可读	绝对不要。
~/.pi/agent/models.json	自定义提供方和每个模型的设置	里面没有 Key，但可能暴露内部地址。分享前请先检查。

凭据不会发回浏览器。如果你改过 Pi 的数据目录，见 PI_CODING_AGENT_DIR。

费用与数据

模型用量由你的提供方计费。对话、工具输出和附件都会发送给该提供方，适用它的数据政策。本地网页不等于本地推理，除非你把自定义提供方指向运行在你自己机器上的模型。

不工作时

• 连接之后选择器里没有模型：打开 Pi 设置 → 模型，确认提供方显示 已配置，再重新打开模型选择器。
• 回复里出现认证错误：重新输入 Key，或者在 编辑 里重新登录。
• 更多见排错。

下一页：包、技能与插件。