提供商

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

目录

• 订阅
• API 密钥
• Auth 文件
• 云 Provider
• 自定义 Provider
• 解析顺序

订阅

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

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

使用 /logout 清除凭证。令牌存储在 ~/.pi/agent/auth.json，过期时自动刷新。

OpenAI Codex

• 需要 ChatGPT Plus 或 Pro 订阅
• OpenAI 官方认可：Codex for OSS

Claude Pro/Max

Anthropic 订阅认证适用于 Claude Pro/Max 账户。第三方 harness 使用会从 extra usage 扣费，按 token 计费，不计入 Claude 计划限额。

GitHub Copilot

• 按 Enter 使用 github.com，或输入 GitHub Enterprise Server 域名
• 若出现 “model not supported”，在 VS Code 中启用：Copilot Chat → 模型选择器 → 选择模型 → “Enable”

API 密钥

环境变量或 Auth 文件

在交互模式使用 /login 选择 provider 将 API 密钥存入 auth.json，或通过环境变量设置凭证：

export ANTHROPIC_API_KEY=sk-ant-...
pi

Provider	环境变量	auth.json 键
Anthropic	ANTHROPIC_API_KEY	anthropic
Ant Ling	ANT_LING_API_KEY	ant-ling
Azure OpenAI Responses	AZURE_OPENAI_API_KEY	azure-openai-responses
OpenAI	OPENAI_API_KEY	openai
DeepSeek	DEEPSEEK_API_KEY	deepseek
NVIDIA NIM	NVIDIA_API_KEY	nvidia
Google Gemini	GEMINI_API_KEY	google
Mistral	MISTRAL_API_KEY	mistral
Groq	GROQ_API_KEY	groq
Cerebras	CEREBRAS_API_KEY	cerebras
Cloudflare AI Gateway	CLOUDFLARE_API_KEY (+ CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_GATEWAY_ID)	cloudflare-ai-gateway
Cloudflare Workers AI	CLOUDFLARE_API_KEY (+ CLOUDFLARE_ACCOUNT_ID)	cloudflare-workers-ai
xAI	XAI_API_KEY	xai
OpenRouter	OPENROUTER_API_KEY	openrouter
Vercel AI Gateway	AI_GATEWAY_API_KEY	vercel-ai-gateway
ZAI	ZAI_API_KEY	zai
ZAI Coding Plan (China)	ZAI_CODING_CN_API_KEY	zai-coding-cn
OpenCode Zen	OPENCODE_API_KEY	opencode
OpenCode Go	OPENCODE_API_KEY	opencode-go
Hugging Face	HF_TOKEN	huggingface
Fireworks	FIREWORKS_API_KEY	fireworks
Together AI	TOGETHER_API_KEY	together
Kimi For Coding	KIMI_API_KEY	kimi-coding
MiniMax	MINIMAX_API_KEY	minimax
MiniMax (China)	MINIMAX_CN_API_KEY	minimax-cn
Xiaomi MiMo	XIAOMI_API_KEY	xiaomi
Xiaomi MiMo Token Plan (China)	XIAOMI_TOKEN_PLAN_CN_API_KEY	xiaomi-token-plan-cn
Xiaomi MiMo Token Plan (Amsterdam)	XIAOMI_TOKEN_PLAN_AMS_API_KEY	xiaomi-token-plan-ams
Xiaomi MiMo Token Plan (Singapore)	XIAOMI_TOKEN_PLAN_SGP_API_KEY	xiaomi-token-plan-sgp

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

Auth 文件

将凭证存储在 ~/.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 文件凭证优先于环境变量。

API 密钥凭证还可包含 provider 作用域的环境值。解析凭证密钥、provider/模型 headers 以及 Cloudflare 账户 ID、Azure OpenAI 设置、Vertex 项目/位置、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（进程生命周期内缓存）
• 环境变量插值： "$ENV_VAR" 或 "${ENV_VAR}" 使用命名变量的值
• 转义： "$$" 输出字面 "$"；"$!" 输出字面 "!" 且不触发命令执行
• 字面值： 直接使用。纯大写字符串如 MY_API_KEY 是字面值；环境变量请用 $MY_API_KEY

OAuth 凭证在 /login 后也存储于此并由系统自动管理。

云 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 任务角色（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 启用 cache points：

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 密钥凭证的 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 路由（/openai）及原生 OpenAI 模型 ID 如 gpt-5.1。Anthropic 使用 Anthropic passthrough 路由（/anthropic）及原生 Anthropic 模型 ID 如 claude-sonnet-4-5。

AI Gateway 认证使用 CLOUDFLARE_API_KEY 作为 cf-aig-authorization。上游认证模式：

模式	请求认证	上游认证
Workers AI	仅 Cloudflare token	Cloudflare 原生
Unified billing	仅 Cloudflare token	Cloudflare 处理上游认证并扣费
Stored BYOK	仅 Cloudflare token	Cloudflare 注入 AI Gateway 仪表板存储的 provider 密钥
Inline BYOK	Cloudflare token 加上游 Authorization header	请求提供上游 provider 密钥

常规 pi 使用优先 unified billing 或 stored BYOK。Inline BYOK 需为 Cloudflare AI Gateway provider 配置额外的上游 Authorization header，例如通过 models.json provider/模型覆盖。

Cloudflare Workers AI

CLOUDFLARE_API_KEY 可通过 /login 设置。CLOUDFLARE_ACCOUNT_ID 可通过环境变量或 auth.json 中 API 密钥凭证的 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 折扣。

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（OpenAI Completions、OpenAI Responses、Anthropic Messages、Google Generative AI）的 provider。参见 models.md。

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

解析顺序

解析 provider 凭证时：

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