跳转到内容

认证与模型

先把认证方式选对,再考虑模型参数。对刚开始使用 Pi 的人,最实用的判断只有三种。

先选认证方式

场景推荐方式原因
个人电脑,已有支持的订阅在 Pi 中执行 /login交互完成登录,适合长期使用
个人电脑,使用供应商 API Key/login 保存,或启动前注入环境变量前者方便,后者更容易随 shell 或任务隔离
CI、容器或一次性任务由密钥管理系统注入环境变量不把凭据写进仓库或镜像

订阅账号和 API Key 都由供应商计费与授权。具体供应商、环境变量和登录方式变化较快,请以 Providers 为准。

接入 OpenAI GPT

OpenAI 已在 Sign in with ChatGPT 官方文档中将 Pi 列为开源集成。你可以在 Pi 中用符合条件的 ChatGPT 订阅访问 GPT,也可以使用 OpenAI API Key。

OpenAI 接入与版本

本节以 Pi 1.5.0 为参考。Pi 从 0.99.0 起在 openai provider 中提供 Sign in with ChatGPT;旧订阅入口 openai-codex 标为 OpenAI Codex (legacy)。版本差异见 Pi 0.99.0 changelog。

先选一种接入方式:

方式需要准备Pi provider用量归属
Sign in with ChatGPT符合条件的 ChatGPT Plus / Pro 订阅,并授权使用计划openai使用已有计划中的 Codex / ChatGPT Work 额度
OpenAI API KeyOpenAI Platform 项目的 Key、可用 API 额度与模型权限openai按 API 用量计费

ChatGPT 计划的第三方应用用量计入现有计划上限,连接 Pi 不会增加一份额外额度;账户资格和授权以登录页面为准,见 OpenAI 计划使用说明。API Key 使用 OpenAI Platform 的 API 计费,见 OpenAI 认证说明。

方式 A:用 ChatGPT 订阅登录

如果还在使用 0.83 等旧版本,先按原来的安装方式升级 Pi。使用 npm 安装的用户可以运行:

终端窗口
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version
pi

在 Pi 的输入框执行:

/login openai
  1. 选择 Sign in with ChatGPT。
  2. 在浏览器中登录要使用的 ChatGPT 账号,确认账户与工作区。
  3. 检查授权页面,允许 Pi Use your ChatGPT plan,再完成授权。
  4. 回到终端,等待 Pi 确认登录成功。
  5. 执行 /model,选择 provider 为 openai 的可用 GPT 模型。

只登录账号与授权使用计划是两项权限;需要完成计划授权才能通过这条路径调用模型。新版的入口和菜单文案可核对 Pi 1.5.0 OpenAI provider。

浏览器没有自动打开时,手动打开 Pi 给出的链接。在 SSH 或远程环境中,如果浏览器完成授权后无法连回终端,按提示把浏览器地址栏中的完整最终回调 URL粘贴回 Pi。新版 OpenAI 流程需要完整 URL,不要只截取其中的授权码;回调地址也不要发到聊天或日志里。具体行为见 Pi 1.5.0 OpenAI 登录实现。

如果暂时保留 0.83.0,执行 /login 并选择 ChatGPT Plus/Pro (Codex) 对应的 openai-codex 入口,模型也要从同一 provider 中选择。这个旧入口与新版 openai 的凭据分别保存;升级后应重新执行 /login openai,不能只把默认 provider 改名。

方式 B:用 OpenAI API Key

在 OpenAI Platform API Keys创建项目的 API Key,并确认该项目有可用 API 额度和目标模型权限。

个人电脑上最直接的方式是启动 pi,执行 /login openai,选择 Sign in with an API key,再按提示输入 Key。Pi 会将它保存到 ~/.pi/agent/auth.json,后续启动可以复用。

如果希望凭据只由当前 shell 或 CI 提供,在启动 Pi 前注入 OPENAI_API_KEY。下面的值是占位符,自动化时由密钥管理系统提供真实值:

终端窗口
export OPENAI_API_KEY="<your-openai-api-key>"
pi

PowerShell:

终端窗口
$env:OPENAI_API_KEY="<your-openai-api-key>"
pi

启动后执行 /model 并选择 openai 下的 GPT 模型。OPENAI_API_KEY 是 Pi 的 OpenAI 内置环境变量,见 Pi Providers。不要把真实 Key 写进项目文档、提交到 Git,或通过 --api-key 参数传入共享脚本。

选模型、验证连接并设置默认值

认证后,在 Pi 中用 /model 选择 provider 为 openai 的 GPT 模型。也可以先在终端查看目录,再指定本次启动的模型:

终端窗口
pi --list-models openai
pi --provider openai --model "<model-id>"

把 <model-id> 替换为目录中 provider 为 openai 的实际模型 ID。Pi 1.5.0 的 --provider 需要与 --model 一起使用;交互选择时直接启动 pi 即可。目录列出的模型仍可能受账号权限或服务状态限制;不要直接照抄旧文章中的型号。

选好模型后,先发送一个不需要读取项目或调用工具的请求:

不要读取文件或调用工具,只回复 OK。

收到回复说明当前凭据和模型的请求链路可用。需要限制实际工具权限时,按权限与安全边界设置运行环境。

要固定以后新会话的默认值,将下面的字段合并到已有的 ~/.pi/agent/settings.json:

{
"defaultProvider": "openai",
"defaultModel": "<model-id>",
"defaultThinkingLevel": "medium"
}

保存前替换模型占位符;思考级别以 /settings 对该模型支持的选项为准。

在订阅与 API Key 之间切换

新版两种登录方式共用 openai。已保存的认证优先于环境变量:如果已经通过 ChatGPT 登录,仅设置 OPENAI_API_KEY 不会把请求切换为 API 计费。

要切换到环境变量中的 API Key,在 Pi 中执行 /logout 并选择 OpenAI,清除它的已保存凭据,然后退出 Pi,在已注入 OPENAI_API_KEY 的 shell 中重新启动。要切回订阅,重新执行 /login openai 并选择 Sign in with ChatGPT。

/logout 只清除 Pi 本机保存的凭据,不会撤销 OpenAI 侧的授权,也不会清除 shell 环境变量。需要撤销 ChatGPT 连接时,到 ChatGPT Settings → Security and login → Sign in with ChatGPT 中断开 Pi;用量管理见官方说明。OpenAI 专项排错见故障排查。

本机交互式登录

启动 Pi 后执行:

/login

选择供应商并按提示完成订阅登录或录入 API Key。保存的认证信息位于:

~/.pi/agent/auth.json

这个文件应当像 SSH 私钥一样对待:

  • 不提交到 Git。
  • 不复制进项目 .env。
  • 不粘贴进对话或会话导出。
  • 不让不可信扩展读取它。
  • 怀疑泄露时在供应商侧撤销或轮换。

在 SSH 或无图形界面的机器上,浏览器登录通常会要求你在另一台设备完成授权,再把最终回调地址或授权码交回终端。不同供应商流程不同,以 /login 当时的提示为准。

Pi 提供 pi auth check、pi auth print-api-key 和 pi auth print-bearer-token,用于检查或向受控的无头进程提供凭据。这些命令需要指定 --provider <provider> 或 --model <model>,也可以同时指定。这两个命令会把秘密直接写到标准输出:不要在共享终端、CI 日志或聊天中运行,也不要把结果落盘。一般 CI 仍应优先由密钥管理系统注入短期凭据。

环境变量与 CI

环境变量适合临时 shell、容器和 CI。以供应商文档给出的变量名为准:

终端窗口
export ANTHROPIC_API_KEY="<由密钥管理系统注入>"
pi

不要把真实 Key 直接写进 shell 脚本、Dockerfile、CI YAML 或命令行参数。命令行参数可能进入 shell 历史和进程列表。

非交互模式不会弹出项目信任提示。如果任务需要项目内 .pi 资源,应先审查它们,再显式使用 --approve;不需要时使用 --no-approve,让边界更清楚。

终端窗口
pi -p --no-approve --no-context-files --no-extensions \
--no-skills --no-prompt-templates \
--tools read,grep,find,ls \
"只读取当前目录,概览项目结构"

这里 --tools 选择只读工具,--no-extensions 同时禁用自动发现的扩展和内置 MCP;单独使用 --tools 并不会排除 MCP 工具。--no-approve 只处理项目受保护资源,并不是工具权限开关;其余 --no-* 参数排除上下文文件和用户级资源。这些选项都不是操作系统沙箱,详见 MCP 工具范围。

选择与切换模型

日常操作集中在命令速查:搜索并切换模型、保存启动默认值,以及调整思考级别。列表太长时,用 /scoped-models 保存常用范围,按从零勾选的步骤操作。

默认模型和常用范围是两项设置:前者决定新会话从哪个模型开始,后者决定选择器默认显示哪些模型、Ctrl+P 在哪些模型之间循环。它们保存在用户设置中;已信任项目的 .pi/settings.json 可以覆盖用户设置,作用域见配置与扩展。

思考级别、边框颜色、chat-latest 别名和虚拟模型见模型、思考与主题。

模型目录不等于账号权限

以下行为按 Pi 1.5.0(2026-11-05)核对。以使用 API Key 的内置 OpenAI provider 为例:

  • 模型名称来自 Pi 自带目录,并可合并 pi.dev 发布的更新。
  • 检测到 OPENAI_API_KEY 等凭据后,Pi 会把该供应商的目录纳入选择范围;这里没有逐个验证账号的模型权限。
  • Model catalogs refreshed. 表示目录刷新完成,不能用来判断所有模型都能调用。

因此,看到几十个模型不表示远程接口给这个 Key 开放了几十个型号。/model 和 pi --list-models 用于查找 Pi 已知的模型 ID,实际可调用性还要看目标服务的权限与请求结果。自定义供应商或扩展可以有自己的目录逻辑。

记成:目录只说明 Pi 看得见,不说明账号调得动。

依据见 Pi 模型目录说明与 Pi 1.5.0 目录刷新实现。

Pi 默认会缓存模型目录到:

~/.pi/agent/models-store.json

需要刷新时运行:

终端窗口
pi update --models

本地模型与自定义供应商

如果你需要本地运行或连接自建服务,不必把它伪装成某个固定云模型:

自定义模型配置通常位于 ~/.pi/agent/models.json。配置文件可能引用环境变量,但不应包含准备提交到仓库的真实密钥。

最小排查顺序

认证或模型不可用时,按这个顺序检查:

  1. 在同一个 shell 中运行 pi --list-models。
  2. 进入 Pi,重新执行 /login,再打开 /model。
  3. 如果使用环境变量,确认它确实注入了启动 Pi 的进程。
  4. 运行 pi update --models 刷新目录。
  5. 查看供应商当前文档,而不是猜测模型 ID。

认证通过后,继续学习日常使用与会话。无头运行与程序控制见自动化与程序集成;需要处理浏览器密钥和工具权限时,先读权限与安全边界。