Provider（模型提供方）

Pi 通过 OAuth 支持基于订阅的 provider，也通过环境变量或 auth 文件支持 API key provider。对每个 provider，pi 都知道所有可用模型。这个列表会随着每次 pi 发布一起更新。

目录

• 订阅
• API Keys
• Auth File
• Cloud Providers
• Custom Providers
• Resolution Order

订阅

在交互模式下使用 /login，然后选择一个 provider：

• ChatGPT Plus/Pro (Codex)
• Claude Pro/Max
• GitHub Copilot

使用 /logout 清除凭据。token 会存储在 ~/.pi/agent/auth.json 中，并在过期时自动刷新。

OpenAI Codex

• 需要 ChatGPT Plus 或 Pro 订阅
• 已获得 OpenAI 官方背书： Codex for OSS

Claude Pro/Max

Anthropic 订阅认证对 Claude Pro/Max 账户生效。使用第三方 harness 会消耗 额外用量，并按 token 计费，不计入 Claude 套餐额度。

GitHub Copilot

• 按 Enter 使用 github.com，或者输入你的 GitHub Enterprise Server 域名
• 如果看到 "model not supported"，请在 VS Code 中启用它：Copilot Chat → model selector → select model → "Enable"

API Keys

环境变量或 Auth File

在交互模式下使用 /login，选择一个 provider，把 API key 存到 auth.json，也可以通过环境变量设置凭据：

export ANTHROPIC_API_KEY=sk-ant-...
pi

环境变量和 auth.json key 的参考定义在 packages/ai/src/env-api-keys.ts 中的 const envMap。

Auth File

把凭据存到 ~/.pi/agent/auth.json：

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "ant-ling": { "type": "api_key", "key": "..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "deepseek": { "type": "api_key", "key": "sk-..." },
  "nvidia": { "type": "api_key", "key": "nvapi-..." },
  "google": { "type": "api_key", "key": "..." },
  "opencode": { "type": "api_key", "key": "..." },
  "opencode-go": { "type": "api_key", "key": "..." },
  "together": { "type": "api_key", "key": "..." },
  "xiaomi": { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-cn":  { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-ams": { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-sgp": { "type": "api_key", "key": "..." }
}

该文件会以 0600 权限创建（仅用户可读写）。Auth file 中的凭据优先于环境变量。

API key 凭据也可以包含 provider 作用域的环境值。在解析凭据 key、provider/model headers，以及诸如 Cloudflare account ID、Azure OpenAI settings、Vertex project/location、Bedrock settings、PI_CACHE_RETENTION 和 HTTP_PROXY/HTTPS_PROXY 等 provider 配置时，这些值会优先于进程环境变量。

{
  "cloudflare-ai-gateway": {
    "type": "api_key",
    "key": "$CLOUDFLARE_API_KEY",
    "env": {
      "CLOUDFLARE_API_KEY": "...",
      "CLOUDFLARE_ACCOUNT_ID": "account-id",
      "CLOUDFLARE_GATEWAY_ID": "gateway-id"
    }
  }
}

当 pi 需要使用与项目 shell 环境不同的 provider 设置时，就用这个方式。

Key 解析

key 字段支持命令执行、环境变量插值和字面量：

• Shell 命令： 以 "!command" 开头时，会把整个值作为命令执行，并使用 stdout（在进程生命周期内缓存）

  { "type": "api_key", "key": "!security find-generic-password -ws 'anthropic'" }
  { "type": "api_key", "key": "!op read 'op://vault/item/credential'" }
  

• 环境变量插值： "$ENV_VAR" 或 "${ENV_VAR}" 会使用指定变量的值。插值也可以出现在更长的字面量中。

  { "type": "api_key", "key": "$MY_ANTHROPIC_KEY" }
  { "type": "api_key", "key": "${KEY_PREFIX}_${KEY_SUFFIX}" }
  

  $FOO_BAR 表示变量 FOO_BAR；如果 BAR 只是字面文本，就用 ${FOO}_BAR。缺失的环境变量会让该值保持未解析状态。
• 转义： "$$" 会输出字面量 "$"；"$!" 会输出字面量 "!"，而不会触发命令执行。

  { "type": "api_key", "key": "$$literal-dollar-prefix" }
  { "type": "api_key", "key": "$!literal-bang-prefix" }
  

• 字面量： 直接使用。像 MY_API_KEY 这样的全大写字符串就是字面量；如果要引用环境变量，请使用 $MY_API_KEY。

  { "type": "api_key", "key": "sk-ant-..." }
  { "type": "api_key", "key": "public" }
  

/login 之后，OAuth 凭据也会存到这里，并由系统自动管理。

---

云端 Provider

Azure OpenAI

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
# also supported: https://your-resource.cognitiveservices.azure.com
# root endpoints are auto-normalized to /openai/v1
# or use resource name instead of base URL
export AZURE_OPENAI_RESOURCE_NAME=your-resource

# Optional
export AZURE_OPENAI_API_VERSION=2024-02-01
export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o

Amazon Bedrock

# Option 1: AWS Profile
export AWS_PROFILE=your-profile

# Option 2: IAM Keys
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

# Option 3: Bearer Token
export AWS_BEARER_TOKEN_BEDROCK=...

# Optional region (defaults to us-east-1)
export AWS_REGION=us-west-2

还支持 ECS task role（AWS_CONTAINER_CREDENTIALS_*）和 IRSA（AWS_WEB_IDENTITY_TOKEN_FILE）。

pi --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0

对于 ID 中包含可识别模型名的 Claude 模型（基础模型和系统定义的 inference profile），提示词缓存会自动启用。对于 application inference profile（其 ARN 不包含模型名），设置 AWS_BEDROCK_FORCE_CACHE=1 即可启用缓存点：

export AWS_BEDROCK_FORCE_CACHE=1
pi --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123

如果你连接的是 Bedrock API 代理，可以使用下面这些环境变量：

# Set the URL for the Bedrock proxy (standard AWS SDK env var)
export AWS_ENDPOINT_URL_BEDROCK_RUNTIME=https://my.corp.proxy/bedrock

# Set if your proxy does not require authentication
export AWS_BEDROCK_SKIP_AUTH=1

# Set if your proxy only supports HTTP/1.1
export AWS_BEDROCK_FORCE_HTTP1=1

Cloudflare AI Gateway

CLOUDFLARE_API_KEY 可以通过 /login 设置。账号 ID 和 gateway slug 可以作为环境变量设置，也可以写入 auth.json 中 API key 凭证的 env 对象。

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
export CLOUDFLARE_GATEWAY_ID=...        # create at dash.cloudflare.com → AI → AI Gateway
pi --provider cloudflare-ai-gateway --model "claude-sonnet-4-5"

通过 Cloudflare AI Gateway 路由到 OpenAI、Anthropic 和 Workers AI。Workers AI 使用统一 API（/compat）和带前缀的模型 ID（workers-ai/@cf/...）。OpenAI 使用 OpenAI 透传路由（/openai），并使用原生 OpenAI 模型 ID，例如 gpt-5.1。Anthropic 使用 Anthropic 透传路由（/anthropic），并使用原生 Anthropic 模型 ID，例如 claude-sonnet-4-5。

AI Gateway 的认证会把 CLOUDFLARE_API_KEY 作为 cf-aig-authorization。上游认证方式可以是：

在普通 pi 使用中，优先选择统一计费或已存储 BYOK。Inline BYOK 需要为 Cloudflare AI Gateway Provider 额外配置一个上游 Authorization header，例如通过 models.json 的 provider/model 覆盖来设置。

Cloudflare Workers AI

CLOUDFLARE_API_KEY 可以通过 /login 设置。CLOUDFLARE_ACCOUNT_ID 可以作为环境变量设置，也可以写入 auth.json 中 API key 凭证的 env 对象。

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
pi --provider cloudflare-workers-ai --model "@cf/moonshotai/kimi-k2.6"

Pi 会自动设置 x-session-affinity，以便享受 前缀缓存 折扣。

Google Vertex AI

使用 Application Default Credentials：

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT=your-project
export GOOGLE_CLOUD_LOCATION=us-central1

或者将 GOOGLE_APPLICATION_CREDENTIALS 设为服务账号密钥文件。

自定义 Provider

**通过 models.json：**添加 Ollama、LM Studio、vLLM，或任何实现了受支持 API 的 Provider（OpenAI Completions、OpenAI Responses、Anthropic Messages、Google Generative AI）。参见 models.md。

**通过扩展：**对于需要自定义 API 实现或 OAuth 流程的 Provider，请创建一个扩展。参见 custom-provider.md 和 examples/extensions/custom-provider-gitlab-duo。

解析优先级

为 Provider 解析凭证时，优先级如下：

1. CLI --api-key 标志
2. auth.json 条目（API key 或 OAuth token）
3. 环境变量
4. models.json 中的自定义 Provider 密钥