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 清除凭据。令牌存储在 ~/.pi/agent/auth.json 中，过期后会自动刷新。OpenRouter 则会生成一个由用户控制的 API Key，该 Key 不会自动过期。

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

Anthropic 订阅身份验证适用于 Claude Pro/Max 帐户。第三方 harness 使用量会计入 extra usage，并按 token 计费，不占用 Claude 计划额度。

• 按 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。缺少环境变量会导致该值无法解析。
• 转义： "$" 输出字面量 "
  quot;；"$!" 输出字面量 "!"，且不会触发命令执行。

  { "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