Providers

Pi 支援透過 OAuth 使用訂閱型 Provider，也支援透過環境變數或 auth 檔案使用 API Key Provider。內建模型目錄隨 pi 一起提供；已設定的 Provider 可以重新整理更新的目錄，並將其快取到 ~/.pi/agent/models-store.json 以供離線使用。

• Subscriptions
• API Keys
• Auth File
• Cloud Providers
• llama.cpp
• Custom Providers
• Resolution Order

在互動模式下使用 /login，然後選擇一個 Provider：

• ChatGPT Plus/Pro (Codex)
• Claude Pro/Max
• GitHub Copilot
• xAI（Grok/X 訂閱）
• OpenRouter（透過 OAuth 建立 API Key，並從 OpenRouter credits 計費）
• Radius

使用 /logout 清除憑證。token 儲存在 ~/.pi/agent/auth.json 中，過期後會自動重新整理。OpenRouter 則會產生一個由使用者控制的 API Key，該 Key 不會自動過期。

• 需要 ChatGPT Plus 或 Pro 訂閱
• OpenAI 官方認可：Codex for OSS

Anthropic 訂閱身分驗證適用於 Claude Pro/Max 帳戶。第三方 harness 使用量會計入 extra usage，並按 token 計費，不佔用 Claude plan 額度。

• 按 Enter 鍵進入 github.com，或輸入你的 GitHub Enterprise Server 域
• 如果出現“model not supported”，請在 VS Code 中啟用它：Copilot Chat → model selector → select model → “Enable”

• 執行 /login xai，然後選擇 使用訂閱
• XAI_API_KEY 仍可透過 Use an API Key 使用

• 執行 /login openrouter，然後選擇 Sign in with OpenRouter，開啟 OpenRouter PKCE 授權流程
• 授權會建立一個由使用者控制的 OpenRouter API Key，並從 OpenRouter credits 計費
• 在遠端/無頭機器上（例如透過 SSH）瀏覽器無法存取 loopback callback；此時請將最終重新導向 URL（或授權碼）貼上到登錄提示中
• OPENROUTER_API_KEY 仍可透過 Use an API Key 使用

Radius 是一個動態 pi-messages 閘道。/login radius 會將 OAuth token 儲存到 auth.json；閘道目錄會獨立重新整理並快取到 models-store.json。自訂 Radius 閘道可以在 models.json 中透過 "oauth": "radius" 和閘道 baseUrl 聲明。

在互動模式下使用 /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。

將憑證儲存在 ~/.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": "..." },
  "qwen-token-plan":  { "type": "api_key", "key": "sk-sp-..." },
  "qwen-token-plan-individual": { "type": "api_key", "key": "sk-sp-..." },
  "qwen-token-plan-cn": { "type": "api_key", "key": "sk-sp-..." },
  "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": "..." }
}

qwen-token-plan-individual 與 qwen-token-plan 使用相同的國際端點和 QWEN_TOKEN_PLAN_API_KEY，但會將選擇器限制為 Individual 訂閱檔案中列出的模型。現有 Provider 保留更寬的目錄以保持向後相容。使用 auth.json 時，請將憑證儲存在所選擇的 Provider 下；兩個國際 Provider 共享同一個環境變數。

該檔案會以 0600 權限建立（僅使用者可讀/寫）。Auth file 中的憑證優先於環境變數。

API Key 憑證還可以包含 Provider 範圍的環境值。在解析憑證 key、Provider/模型 header，以及 Cloudflare account ID、Azure OpenAI 設定、Vertex project/location、Bedrock 設定、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 欄位支援指令執行、環境變數插值和字面值：

• 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。缺少環境變數會導致該值無法解析。
• 轉義： "$" 輸出 literal "
  quot;；"$!" 輸出 literal "!"，且不會觸發指令執行。

  { "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 憑證也會儲存在這裡，並自動管理。

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
# also supported: https://your-resource.cognitiveservices.azure.com
# also supported: https://your-resource.openai.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

使用 /login amazon-bedrock 儲存 Bedrock API Key，或設定以下任一環境 AWS 憑證源：

# 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 任務角色 (AWS_CONTAINER_CREDENTIALS_*) 和 IRSA (AWS_WEB_IDENTITY_TOKEN_FILE)。

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

對於 ID 包含可識別模型名稱的 Claude 模型（基礎模型和系統定義的推理設定檔），會自動啟用 Prompt caching。對於應用程式推理設定檔（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_API_KEY 可以透過 /login 設定。account 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 使用 Unified API (/compat) 和帶前綴的模型 ID (workers-ai/@cf/...)。OpenAI 使用 OpenAI passthrough route (/openai) 和原生 OpenAI 模型 ID，例如 gpt-5.1。Anthropic 使用 Anthropic passthrough route (/anthropic) 和原生 Anthropic 模型 ID，例如 claude-sonnet-4-5。

AI Gateway 身分驗證使用 CLOUDFLARE_API_KEY 作為 cf-aig-authorization。上游身分驗證可以是以下之一：

正常使用 pi 時，建議優先使用統一計費或 Stored BYOK。Inline BYOK 需要為 Cloudflare AI Gateway Provider 設定額外的上游 Authorization header，例如透過 models.json Provider/模型覆寫。

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 以獲得 prefix caching 折扣。

使用 Application Default Credentials：

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

或者將 GOOGLE_APPLICATION_CREDENTIALS 設定為 service account key 檔案。

Pi 支援 llama.cpp router server。使用 /login llama.cpp 設定它，使用 /llama 管理已載入模型，並使用 /model 選擇已載入模型。

有關伺服器設定、模型目錄版面設定、環境變數和指令用法，請參閱 llama.cpp。

透過 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 key