提供商

Pi 支持通过 OAuth 的基于订阅的提供商，以及通过环境变量或认证文件的 API 密钥提供商。内置目录随 pi 一起提供；已配置的提供商可能会刷新更新的目录并将其缓存到 ~/.pi/agent/models-store.json 以供离线使用。

目录

• 订阅
• API 密钥
• 认证文件
• 云提供商
• llama.cpp
• 自定义提供商
• 解析顺序

订阅

使用 /login 进入交互模式，然后选择一个提供商：

• ChatGPT Plus/Pro (Codex)
• Claude Pro/Max
• GitHub Copilot
• xAI (Grok/X 订阅)
• OpenRouter (通过 OAuth 生成的 API 密钥，从 OpenRouter 余额中计费)
• Radius

使用 /logout 清除凭据。令牌存储在 ~/.pi/agent/auth.json 中，并在过期时自动刷新。而 OpenRouter 会生成一个用户控制的 API 密钥，该密钥不会自动过期。

OpenAI Codex

• 需要 ChatGPT Plus 或 Pro 订阅
• 由 OpenAI 官方认可： 面向开源软件的Codex

Claude Pro/Max

Anthropic 订阅认证对 Claude Pro/Max 账户有效。第三方工具的使用会消耗 额外用量 ，并按令牌计费，不计入 Claude 计划限制。

GitHub Copilot

• 按 Enter 键使用 github.com，或输入您的 GitHub Enterprise Server 域名
• 如果遇到“模型不支持”，请在 VS Code 中启用：Copilot Chat → 模型选择器 → 选择模型 → “启用”

xAI (Grok/X 订阅)

• 运行 /login xai，然后选择 使用订阅
• XAI_API_KEY 仍可通过 使用 API 密钥

OpenRouter

• 运行 /login openrouter，然后选择 使用 OpenRouter 登录 以打开 OpenRouter PKCE 授权流程
• 该授权会创建一个用户控制的 OpenRouter API 密钥，从您的 OpenRouter 余额中计费
• 在远程/无头机器上（例如通过 SSH），浏览器无法访问环回回调；请将最终重定向 URL（或授权码）粘贴到登录提示中
• OPENROUTER_API_KEY 仍可通过 使用 API 密钥

Radius

Radius 是一个动态 pi-messages 网关。 /login radius 将 OAuth 令牌存储在 auth.json中；网关目录独立刷新并缓存在 models-store.json中。自定义 Radius 网关可以在 models.json 中使用 "oauth": "radius" 和网关 baseUrl.

API 密钥

环境变量或认证文件

使用 /login 进入交互模式并选择一个提供商，将 API 密钥存储在 auth.json，或通过环境变量设置凭据：

export ANTHROPIC_API_KEY=sk-ant-...
pi

环境变量和 auth.json 密钥的参考： const envMap 在 packages/ai/src/env-api-keys.ts.

认证文件

将凭据存储在 ~/.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_API_KEY 作为 qwen-token-plan，但将选择器限制为个人订阅所记录的模型。现有的 提供商保留其更广泛的目录以实现向后兼容。使用 auth.json时，将 凭据存储在你选择的提供商下；一个环境变量由两个国际提供商共享。

该文件创建时具有 0600 权限（仅用户可读写）。认证文件凭据优先于环境变量。

API 密钥凭据还可以包含提供商范围的环境值。在解析凭据密钥、提供商/模型标头以及提供商配置（如 Cloudflare 账户 ID、Azure OpenAI 设置、Vertex 项目/位置、Bedrock 设置、 PI_CACHE_RETENTION和 HTTP_PROXY/HTTPS_PROXY.

{
  "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 环境不同的提供商设置时，请使用此功能。

密钥解析

该 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；使用 ${FOO}_BAR 当 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" }

OAuth 凭据也会在 /login 之后存储在此处，并自动管理。

云提供商

Azure OpenAI

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

Amazon Bedrock

使用 /login amazon-bedrock 存储 Bedrock API 密钥，或配置以下环境 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 模型（基础模型和系统定义的推理配置文件），提示缓存会自动启用。对于应用程序推理配置文件（其 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 网关

CLOUDFLARE_API_KEY 可以通过 /login设置。账户 ID 和网关 slug 可以设置为环境变量，或在 API 密钥凭据的 env 对象中设置，位于 auth.json.

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。内联 BYOK 需要为 Cloudflare AI Gateway 提供商配置额外的上游 Authorization 标头，例如通过 models.json 提供商/模型覆盖。

Cloudflare Workers AI

CLOUDFLARE_API_KEY 可以通过 /login. CLOUDFLARE_ACCOUNT_ID 可以设置为环境变量，或在 API 密钥凭据的 env 对象中设置，位于 auth.json.

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

使用应用程序默认凭据：

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

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

llama.cpp

Pi 支持 llama.cpp 路由服务器。使用 /login llama.cpp进行配置，使用 /llama管理已加载的模型，并使用 /model.

选择已加载的模型。请参阅 llama.cpp 了解服务器设置、模型目录布局、环境变量和命令用法。

自定义提供商

通过 models.json： 添加 Ollama、LM Studio、vLLM 或任何支持受支持 API（OpenAI Completions、OpenAI Responses、Anthropic Messages、Google Generative AI）的提供商。请参阅 models.md.

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

解析顺序

解析提供商的凭据时：

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