认证与模型
先把认证方式选对，再考虑模型参数。对刚开始使用 Pi 的人，最实用的判断只有三种。
先选认证方式
| 场景 | 推荐方式 | 原因 |
|---|---|---|
| 个人电脑，已有支持的订阅 | 在 Pi 中执行 /login | 交互完成登录，适合长期使用 |
| 个人电脑，使用供应商 API Key | /login 保存，或启动前注入环境变量 | 前者方便，后者更容易随 shell 或任务隔离 |
| CI、容器或一次性任务 | 由密钥管理系统注入环境变量 | 不把凭据写进仓库或镜像 |
订阅账号和 API Key 都由供应商计费与授权。具体供应商、环境变量和登录方式变化较快，请以 Providers 为准。
本机交互式登录
启动 Pi 后执行：
/login选择供应商并按提示完成订阅登录或录入 API Key。保存的认证信息位于：
~/.pi/agent/auth.json这个文件应当像 SSH 私钥一样对待：
- 不提交到 Git。
- 不复制进项目
.env。 - 不粘贴进对话或会话导出。
- 不让不可信扩展读取它。
- 怀疑泄露时在供应商侧撤销或轮换。
在 SSH 或无图形界面的机器上，浏览器登录通常会要求你在另一台设备完成授权，再把最终回调地址或授权码交回终端。不同供应商流程不同，以 /login 当时的提示为准。
Pi 0.83 还提供 pi auth print-api-key --model <model> [--provider <provider>] 和 pi auth print-bearer-token --model <model> [--provider <provider>]，用于把已保存凭据交给受控的无头进程。--model 必填；Pi 可以根据已配置凭据推断 provider，也可以用 --provider 明确指定。这两个命令会把秘密直接写到标准输出：不要在共享终端、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-approve 只处理项目受保护资源，并不是工具权限开关。其余 --no-* 参数同时排除上下文文件和用户级资源，避免全局 Extension 在最小任务中启动。
选择与切换模型
| 操作 | 用途 |
|---|---|
/model | 打开模型选择器 |
Ctrl+L | 快速打开模型选择器 |
/scoped-models | 配置日常循环切换的模型集合 |
/settings | 调整思考级别等会话设置 |
pi --list-models [关键词] | 在启动 Pi 前检查模型目录 |
--provider、--model | 为本次启动显式指定供应商和模型 |
--thinking <级别> | 为本次启动指定思考级别 |
不要在项目文档里长期维护具体模型 ID。供应商可能更名、下线或调整能力；让 pi --list-models 和 /model 成为当前环境的事实来源。
需要固定个人默认值时，可在 ~/.pi/agent/settings.json 设置：
{
"defaultProvider": "<provider>",
"defaultModel": "<model-id>",
"defaultThinkingLevel": "medium"
}把占位符替换为 /model 当前显示的值。项目 .pi/settings.json 可以覆盖全局设置，但只有在项目被信任后才加载；作用域与风险见配置与扩展。
Pi 会缓存模型目录到：
~/.pi/agent/models-store.json需要刷新时运行：
pi update --models本地模型与自定义供应商
如果你需要本地运行或连接自建服务，不必把它伪装成某个固定云模型：
- 本地 llama.cpp：查看 llama.cpp 集成。
- OpenAI、Anthropic 或 Google 兼容端点：查看 Custom Models。
- 自定义 API 或 OAuth：查看 Custom Provider。
自定义模型配置通常位于 ~/.pi/agent/models.json。配置文件可能引用环境变量，但不应包含准备提交到仓库的真实密钥。
最小排查顺序
认证或模型不可用时，按这个顺序检查：
- 在同一个 shell 中运行
pi --list-models。 - 进入 Pi，重新执行
/login，再打开/model。 - 如果使用环境变量，确认它确实注入了启动 Pi 的进程。
- 运行
pi update --models刷新目录。 - 查看供应商当前文档，而不是猜测模型 ID。
认证通过后，继续学习日常使用与会话。无头运行与程序控制见自动化与程序集成；需要处理浏览器密钥和工具权限时，先读权限与安全边界。