模型提供方

Pi 支持通过 OAuth 登录的订阅型模型提供方，也支持通过环境变量或认证文件（auth file）配置 API 密钥型模型提供方。Pi 自带内置的模型目录（catalog）；配置的模型提供方可刷新更新的目录，并将其缓存在 ~/.pi/agent/models-store.json 中以供离线使用。

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

Radius

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

API 密钥

环境变量或认证文件

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

export ANTHROPIC_API_KEY=sk-ant-...
pi

模型提供方	环境变量	`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`
Amazon Bedrock	`AWS_BEARER_TOKEN_BEDROCK`	`amazon-bedrock`
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 Coding Plan（全球）	`ZAI_API_KEY`	`zai`
ZAI Coding Plan（中国）	`ZAI_CODING_CN_API_KEY`	`zai-coding-cn`
OpenCode Zen	`OPENCODE_API_KEY`	`opencode`
OpenCode Go	`OPENCODE_API_KEY`	`opencode-go`
Radius	`RADIUS_API_KEY`	`radius`
Hugging Face	`HF_TOKEN`	`huggingface`
Fireworks	`FIREWORKS_API_KEY`	`fireworks`
Together AI	`TOGETHER_API_KEY`	`together`
Baseten	`BASETEN_API_KEY`	`baseten`
Kimi For Coding	`KIMI_API_KEY`	`kimi-coding`
MiniMax	`MINIMAX_API_KEY`	`minimax`
MiniMax（中国）	`MINIMAX_CN_API_KEY`	`minimax-cn`
Qwen Token Plan（现有目录）	`QWEN_TOKEN_PLAN_API_KEY`	`qwen-token-plan`
Qwen Token Plan（个人版）	`QWEN_TOKEN_PLAN_API_KEY`	`qwen-token-plan-individual`
Qwen Token Plan（中国）	`QWEN_TOKEN_PLAN_CN_API_KEY`	`qwen-token-plan-cn`
Xiaomi MiMo	`XIAOMI_API_KEY`	`xiaomi`
Xiaomi MiMo Token Plan（中国）	`XIAOMI_TOKEN_PLAN_CN_API_KEY`	`xiaomi-token-plan-cn`
Xiaomi MiMo Token Plan（阿姆斯特丹）	`XIAOMI_TOKEN_PLAN_AMS_API_KEY`	`xiaomi-token-plan-ams`
Xiaomi MiMo Token Plan（新加坡）	`XIAOMI_TOKEN_PLAN_SGP_API_KEY`	`xiaomi-token-plan-sgp`

环境变量和 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 使用相同的国际端点和 QWEN_TOKEN_PLAN_API_KEY，但将选择器限制为文档中为 Individual 订阅列出的模型。原有模型提供方保留更广泛的目录以保持向后兼容。使用 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 字段支持命令执行、环境变量插值（interpolation）和字面量：

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 凭据也会存储在这里并自动管理。

云模型提供方

Azure OpenAI

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
# 同样支持：https://your-resource.cognitiveservices.azure.com
# 同样支持：https://your-resource.openai.azure.com
# 根端点会自动规范化为 /openai/v1
# 或使用资源名称代替 base URL
export AZURE_OPENAI_RESOURCE_NAME=your-resource

# 可选
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 凭据来源：

# 选项 1：AWS 配置文件
export AWS_PROFILE=your-profile

# 选项 2：IAM 密钥
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

# 选项 3：Bearer 令牌
export AWS_BEARER_TOKEN_BEDROCK=...

# 可选区域（默认为 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 代理，可以使用以下环境变量：

# 设置 Bedrock 代理的 URL（标准 AWS SDK 环境变量）
export AWS_ENDPOINT_URL_BEDROCK_RUNTIME=https://my.corp.proxy/bedrock

# 如果你的代理不需要身份验证则设置
export AWS_BEDROCK_SKIP_AUTH=1

# 如果你的代理仅支持 HTTP/1.1 则设置
export AWS_BEDROCK_FORCE_HTTP1=1

Cloudflare AI Gateway

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

export CLOUDFLARE_API_KEY=...           # 或使用 /login
export CLOUDFLARE_ACCOUNT_ID=...
export CLOUDFLARE_GATEWAY_ID=...        # 在 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 进行身份验证。上游身份验证可以是以下之一：

模式	请求身份验证	上游身份验证
Workers AI	仅 Cloudflare 令牌	Cloudflare 原生
统一计费	仅 Cloudflare 令牌	Cloudflare 处理上游身份验证并扣除积分
存储的 BYOK	仅 Cloudflare 令牌	Cloudflare 注入存储在 AI Gateway 仪表盘中的模型提供方密钥
内联 BYOK	Cloudflare 令牌加上游 `Authorization` 请求头	请求提供上游模型提供方密钥

常规 pi 使用中，优先选择统一计费或存储的 BYOK。内联 BYOK 需要为 Cloudflare AI Gateway 模型提供方额外配置上游 Authorization 请求头，例如通过 models.json 中的模型提供方/模型覆盖配置。

Cloudflare Workers AI

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

export CLOUDFLARE_API_KEY=...           # 或使用 /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 设置为服务账户密钥文件。

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 流程的模型提供方，请创建扩展。参见自定义模型提供方和examples/extensions/custom-provider-gitlab-duo。

解析顺序

为模型提供方解析凭据时：

CLI --api-key 标志
auth.json 条目（API 密钥或 OAuth 令牌）
环境变量
models.json 中的自定义模型提供方密钥