$ pi –providers

TL;DR. Pi 出厂带 40+ 内建 provider，覆盖订阅型 OAuth（Claude Pro、ChatGPT Plus、GitHub Copilot、OpenRouter、Kimi Code、Radius）和 API key 网关（Anthropic、OpenAI、Google Gemini、Bedrock、llama.cpp、Baseten 以及数十个区域 provider）。用 /login（OAuth）或对应环境变量 / auth.json 条目配置；运行时切换模型用 /model 或 Ctrl+P；用 ~/.pi/agent/models.json 自定义目录。两个值得知道的特性：pricing tiers（v0.80.6）用于准确的长上下文计费，constrained sampling（v0.82.0）保证工具输出形状。脚本从 PI_PROVIDER 与 PI_MODEL 环境变量读当前激活模型，而不是从系统提示推断。

provider 的选择本质上取决于你想要用哪个模型、持有什么认证。配好一个 provider 后，切换其下模型用 /model 或 Ctrl+P；切换 provider 需要重新 /login，或在 CLI 用 pi --provider <name> --model <pattern>。

内建 provider

provider 列表分订阅型 OAuth 和 API key 两种入口。挑跟你认证方式匹配的。

Provider	认证	备注
Anthropic	`ANTHROPIC_API_KEY` 或 `/login`（Claude Pro/Max 订阅）	一方；默认 `x-api-key`。v0.82.1 新增 `ANTHROPIC_AUTH_TOKEN` 用于期望 `Authorization: Bearer` 的 Anthropic 兼容网关。
OpenAI	`OPENAI_API_KEY` 或 `/login`（ChatGPT Plus/Pro Codex 订阅）	订阅路径含 OpenAI Codex Responses API。
Google Gemini / Vertex AI	`GEMINI_API_KEY`（Vertex 用 ADC）	Vertex：`gcloud auth application-default login` 加上 `GOOGLE_CLOUD_PROJECT` 与 `GOOGLE_CLOUD_LOCATION`。
Amazon Bedrock	`AWS_BEARER_TOKEN_BEDROCK`（或 IAM profile / IRSA）	可选 `AWS_REGION`（默认 `us-east-1`）；代理通过 `AWS_ENDPOINT_URL_BEDROCK_RUNTIME`。
GitHub Copilot	`/login`（github.com 或 GitHub Enterprise Server）	订阅路径；任何 Forge 兼容平台都能跑。
OpenRouter	`/login openrouter`（PKCE）或 `OPENROUTER_API_KEY`	v0.83.0 新增专门为 OpenRouter 设计的 SSH 无头登录。
Kimi Code	`/login kimi-coding`	OAuth 订阅在 v0.82.0 加入。
xAI (Grok)	`/login xai`（X 订阅）或 `XAI_API_KEY`	v0.80.8 新增 xAI 设备码登录。
Radius	`/login radius`	OAuth token；网关目录缓存到 `models-store.json`。
Baseten	`BASETEN_API_KEY`	v0.84.0 加入内建 provider。
llama.cpp	`LLAMA_BASE_URL`（可选 `LLAMA_API_KEY`）	本地 router；v0.81.0 加入。用 `/llama` 管理。
Qwen Token Plan	`QWEN_TOKEN_PLAN_API_KEY`（含 China 变体）	Individual 订阅路径在 v0.84.1 加入。
Cloudflare AI Gateway / Workers AI	`CLOUDFLARE_API_KEY`（+ `CLOUDFLARE_ACCOUNT_ID`、`CLOUDFLARE_GATEWAY_ID`）	四种鉴权模式；倾向 Unified billing 或 Stored BYOK。
ZAI Coding Plan（Global / China）	`ZAI_API_KEY` / `ZAI_CODING_CN_API_KEY`	—
Xiaomi MiMo	`XIAOMI_API_KEY`	—
Xiaomi MiMo Token Plan	`XIAOMI_TOKEN_PLAN_*_API_KEY`（China / Amsterdam / Singapore）	订阅 token-plan 变体
还有 OpenCode Zen/Go、Hugging Face、Fireworks、Together、Groq、Cerebras、Mistral、NVIDIA NIM、DeepSeek、Moonshotai、MiniMax	各有对应环境变量	完整列表见 Providers。

auth 文件位于 ~/.pi/agent/auth.json，权限 0600，优先级高于同名环境变量。auth.json 中 key 字段支持 shell 命令（!command，读时执行、stdout 在进程生命周期内缓存）、环境变量插值（$VAR / ${VAR，$$ 输出字面 $，$! 输出字面 !）、以及字面字符串。

切换激活模型

同一个动作三种入口：

/model 打开交互式模型选择器。每次打开都会重新读 ~/.pi/agent/models.json 并触发后台目录刷新（v0.80.8 加入）。已经认证过的模型之间切换最便宜的方式。
Ctrl+P 切到 enabledModels 集合中的下一个模型。Shift+Ctrl+P 反向切。Ctrl+L 直接打开模型选择器。Shift+Tab 切思考级别。
CLI 参数：--provider <name>、--model <pattern>（接受精确 id、glob、provider/id、以及 :thinking 简写如 sonnet:high 或 openai/gpt-4o）、--models <patterns>（cycling 集合）、--list-models [search]（列出可用模型）、--thinking <level>（off | minimal | low | medium | high | xhigh | max）。

模型 pattern 是 glob。claude-*、gpt-4o、gemini-2* 都行。多个 provider 共名的精确 id 以前会静默选第一个目录条目；v0.84.0 改成了优先选唯一已认证 provider，否则报明确的歧义错误。

如果一个 model pattern 不在 enabledModels 里，它对 Ctrl+P cycling 隐藏，但 /model 里还能选。用 CLI --models 'claude-*,gpt-4o'，或在 ~/.pi/agent/settings.json 设 enabledModels（项目 .pi/settings.json 覆盖全局；嵌套对象合并）。

自定义模型与 provider override

~/.pi/agent/models.json 是定制层。每次 /model 打开都会重新读，会话中途改动即时生效，无需重启。

顶层结构 { "providers": { ... } }。每个 provider：

{
  "baseUrl": "https://my-proxy.example.com/v1",
  "api": "openai-completions",
  "apiKey": "$MY_PROXY_KEY",
  "headers": { "X-Org": "team-alpha" },
  "models": [
    { "id": "my-custom-gpt", "name": "Custom GPT", "contextWindow": 200000, "maxTokens": 8192 }
  ],
  "modelOverrides": {
    "claude-sonnet-4-20250514": { "name": "Sonnet (internal)", "maxTokens": 16384 }
  }
}

apiKey 和 headers 的值复用 auth.json 的解析规则：$VAR、${VAR}、!command、$$、$!、字面字符串。模型 id 是 pi 发给 API 的字段；name 是显示名，并影响 --model pattern 匹配。

可以 override 内建 provider——比如把所有 Anthropic 流量走公司代理：

{ "providers": { "anthropic": { "baseUrl": "https://my-proxy.example.com/v1" } } }

所有内建模型仍可用。现有 OAuth 或 API key 认证继续生效。合并语义：内建模型保留；自定义模型按 id upsert 进 provider；匹配 id 替换内建；新 id 与内建并存。

modelOverrides 应用到内建 provider 模型（以及匹配的扩展注册 provider 模型）。未知 model id 静默忽略。可覆盖字段：name、reasoning、thinkingLevelMap、input、cost（部分）、contextWindow、maxTokens、samplingParams（按 key 合并）、headers、compat。

Pricing tiers（v0.80.6）

对长短上下文不同价的模型（Anthropic Claude、OpenAI GPT-5.6 等），pricing tiers 给你跨边界的准确计费：

{
  "cost": {
    "input": 5,
    "output": 30,
    "cacheRead": 0.5,
    "cacheWrite": 6.25,
    "tiers": [
      { "inputTokensAbove": 272000, "input": 10, "output": 45, "cacheRead": 1, "cacheWrite": 12.5 }
    ]
  }
}

tier 给出完整的替代费率集，在总输入使用量（input + cacheRead + cacheWrite）超过 inputTokensAbove 时，对整个请求生效。多个 tier 都满足时，取阈值最高那个。tier 阈值是总输入 token，不只是未缓存的 input——读缓存命中和写缓存命中都算。

Constrained sampling（v0.82.0）

如果你写的工具需要保证 JSON 输出形状，与其依赖重试，不如用 provider 端的 constrained sampling：

{
  "name": "apply_patch",
  "strict": "require",
  "parameters": Type.Object({ "path": Type.String(), "patch": Type.String() })
}

strict: "prefer" 让 provider 在支持时强制按 schema，否则回退到普通工具调用。strict: "require" 在当前 provider/model 不支持时直接失败——重试比直接失败成本更高时选这个。constrainedSampling: false 显式 opt out，效果等同于省略字段。

能力是按 model 门控的，不是按 provider：Anthropic、支持的 Amazon Bedrock Converse 模型、Mistral、Gemini 3（经 Google Generative AI 和 Vertex）、以及 OpenAI Chat Completions / Responses 严格 JSON schema 都支持。OpenAI 还支持 Lark 和 regex grammar 通过 custom 工具；两个都给时 Lark 优先于 regex。早于 Gemini 3 的版本对 strict: "prefer" 回退、对 strict: "require" 直接拒绝，所以由 model capability metadata 决定路径。

对内建默认工具（read、bash、edit、write），constrained sampling 当前被 PI_EXPERIMENTAL=1 守门。一旦稳定，这些工具的重试与形状失败会更少——目前只在自己写的工具上 opt in。

从脚本读取激活模型

每个工具启动的 shell 都暴露两个环境变量：

PI_PROVIDER——当前选中的 model provider
PI_MODEL——当前选中的 model id

两者反映 pi 的选择，不是 provider 静默重定向到的某个上游 router。当工具或脚本问“当前跑的是什么模型”，检查这两个变量，别从系统提示推断——系统提示就是由这两个变量构造的，可能滞后于最近的 /model 切换。

目录新鲜度与离线使用

内建目录随二进制发布，构成基线。已配置的 provider 可刷新新目录，缓存到 ~/.pi/agent/models-store.json 用于离线使用。每次 /model 打开触发后台刷新。强制立即刷新用 pi update --models。完全禁用刷新设 PI_OFFLINE=1。

models-store.json 并发读取以前会形成文件锁队列（v0.84.0 修复）。调试目录陈旧问题时，pi update --models 是最干净的复位；删 ~/.pi/agent/models-store.json 是会强制从内建完全重建的“核选项”。

何时新增 model vs. override

常见决策点：到底需要在 models.json 加新 model，还是在 modelOverrides 覆盖内建就够了？内建 model 需要换皮时——代理端点、fine-tune、区域变体——用 override。当 provider 或 model 真的新、pi 不靠这个文件就不知道它时——加新 model。

对 Ollama、LM Studio 或其他本地/无 key 服务，models.json 是必需的：pi 没有 apiKey 字段就不在 /model 显示，加 "apiKey": "ollama"（或任意非空占位）模型就出现。

简短示例：Anthropic 走公司代理

假设你想把 Anthropic 流量全部走公司代理、代理会加认证头。在 ~/.pi/agent/models.json 写入：

{
  "providers": {
    "anthropic": {
      "baseUrl": "https://anthropic-proxy.internal/v1",
      "headers": { "X-Corp-Tenant": "team-alpha" }
    }
  }
}

所有 pi 出厂的 Anthropic 模型——每个 Claude 变体——仍可用。pi --provider anthropic --model claude-sonnet-4-20250514 现在打到代理。auth.json 的 ANTHROPIC_API_KEY 继续工作；代理预期信任同一个 key。如果你想顺便改显示名以区分内部部署，加 modelOverrides 块：

{
  "providers": {
    "anthropic": {
      "baseUrl": "https://anthropic-proxy.internal/v1",
      "headers": { "X-Corp-Tenant": "team-alpha" }
    }
  },
  "modelOverrides": {
    "claude-sonnet-4-20250514": { "name": "Sonnet (internal)" }
  }
}

页脚和状态栏读 “Sonnet (internal)”，但 API 仍看到 claude-sonnet-4-20250514。无需重启、无需 schema 迁移。

Provider 与模型配置