6 模型提供商

6.1 概述

Pi 支持两种类型的模型提供商：

订阅制提供商：通过 OAuth 认证，使用你的现有订阅（如 Claude Pro、ChatGPT Plus）
API Key 制提供商：通过环境变量或认证文件配置，按 Token 计费

内置的模型目录随 Pi 发布，配置的提供商可以刷新更新的目录并缓存到 ~/.pi/agent/models-store.json 供离线使用。

6.2 订阅提供商

在交互模式中运行 /login，然后选择一个提供商：

6.2.1 OpenAI Codex

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

6.2.2 Claude Pro/Max

Anthropic 订阅认证适用于 Claude Pro/Max 账户。第三方工具使用会从额外使用额度中扣费，按 Token 计费，不使用 Claude 计划限额。

Warning

使用 Pi 连接 Claude Pro/Max 订阅会产生额外费用（按 Token 计费），不在你的 Claude 计划月度限额内。默认情况下 Pi 会显示相关警告。

6.2.3 GitHub Copilot

按 Enter 使用 github.com，或输入你的 GitHub Enterprise Server 域名
如果遇到”model not supported”错误，在 VS Code 中启用该模型：Copilot Chat → 模型选择器 → 选择模型 → “Enable”

6.2.4 xAI（Grok/X 订阅）

/login xai

然后选择 Use a subscription。XAI_API_KEY 仍可通过 Use an API key 使用。

6.2.5 OpenRouter

/login openrouter

然后选择 Sign in with OpenRouter 进入 OpenRouter PKCE 授权流程。该授权会创建一个用户可控的 OpenRouter API Key，从你的 OpenRouter 余额中扣费。

Note

在远程/无头机器上（如通过 SSH），浏览器可能无法访问回调地址。此时请将最终的跳转 URL（或授权码）粘贴到登录提示中。

6.2.6 Radius

Radius 是一个动态 pi-messages 网关。/login radius 将 OAuth 令牌存储在 auth.json 中；网关目录会独立刷新并缓存到 models-store.json。

6.3 API Key 提供商

6.3.1 配置方式

方式一：通过 /login 交互式配置，Key 会存储到 auth.json

方式二：通过环境变量配置

export ANTHROPIC_API_KEY=sk-ant-...
pi

6.3.2 完整提供商列表

提供商	环境变量	`auth.json` Key
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 (Global)	`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`
Radius	`RADIUS_API_KEY`	`radius`
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`
Qwen Token Plan	`QWEN_TOKEN_PLAN_API_KEY`	`qwen-token-plan`
Qwen Token Plan (China)	`QWEN_TOKEN_PLAN_CN_API_KEY`	`qwen-token-plan-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`

Note

环境变量和 auth.json Key 的完整参考来源：packages/ai/src/env-api-keys.ts。

6.4 Auth 文件格式

凭证存储在 ~/.pi/agent/auth.json 中：

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "deepseek": { "type": "api_key", "key": "sk-..." },
  "google": { "type": "api_key", "key": "..." },
  "together": { "type": "api_key", "key": "..." }
}

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

6.4.1 提供商作用域环境变量

API Key 凭证还可以包含提供商作用域的环境变量值。这些值在解析凭证 Key、提供商/模型头信息和提供商配置时优先于进程环境变量使用：

{
  "cloudflare-ai-gateway": {
    "type": "api_key",
    "key": "$CLOUDFLARE_API_KEY",
    "env": {
      "CLOUDFLARE_API_KEY": "...",
      "CLOUDFLARE_ACCOUNT_ID": "account-id",
      "CLOUDFLARE_GATEWAY_ID": "gateway-id"
    }
  }
}

Tip

当你需要 Pi 使用与项目 Shell 环境不同的提供商设置时，这个功能非常有用。

6.5 Key Resolution（密钥解析）

key 字段支持命令执行、环境变量插值和字面量值：

6.5.1 Shell 命令执行

以 ! 开头的值会作为 Shell 命令执行，使用 stdout 作为 Key（进程生命周期内缓存）：

{ "type": "api_key", "key": "!security find-generic-password -ws 'anthropic'" }
{ "type": "api_key", "key": "!op read 'op://vault/item/credential'" }

6.5.2 环境变量插值

$ENV_VAR 或 ${ENV_VAR} 使用命名变量的值。插值可以在更大的字面量中工作：

{ "type": "api_key", "key": "$MY_ANTHROPIC_KEY" }
{ "type": "api_key", "key": "${KEY_PREFIX}_${KEY_SUFFIX}" }

Note

$FOO_BAR 表示变量 FOO_BAR；如果你想让 BAR 作为字面文本，请使用 ${FOO}_BAR。缺失的环境变量会使值未解析。

6.5.3 转义字符

$$：输出字面 $
$!：输出字面 !（不触发命令执行）

{ "type": "api_key", "key": "$$literal-dollar-prefix" }
{ "type": "api_key", "key": "$!literal-bang-prefix" }

6.5.4 字面量值

纯大写字符串（如 MY_API_KEY）是字面量。使用 $MY_API_KEY 才表示环境变量：

{ "type": "api_key", "key": "sk-ant-..." }
{ "type": "api_key", "key": "public" }

6.6 云提供商配置

6.6.1 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

6.6.2 Amazon Bedrock

使用 /login amazon-bedrock 存储 Bedrock API Key，或配置以下 AWS 凭证来源之一：

# 方式 1：AWS Profile
export AWS_PROFILE=your-profile

# 方式 2：IAM 密钥
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

# 方式 3：Bearer Token
export AWS_BEARER_TOKEN_BEDROCK=...

# 可选区域（默认 us-east-1）
export AWS_REGION=us-west-2

Note

还支持 ECS 任务角色（AWS_CONTAINER_CREDENTIALS_*）和 IRSA（AWS_WEB_IDENTITY_TOKEN_FILE）。

使用示例：

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

Prompt 缓存：对于 ID 中包含可识别模型名称的 Claude 模型（基础模型和系统定义的推理配置文件），自动启用 Prompt 缓存。对于应用推理配置文件（ARN 中不包含模型名称），设置 AWS_BEDROCK_FORCE_CACHE=1 来启用：

export AWS_BEDROCK_FORCE_CACHE=1

Bedrock 代理：如果连接 Bedrock API 代理：

export AWS_ENDPOINT_URL_BEDROCK_RUNTIME=https://my.corp.proxy/bedrock
export AWS_BEDROCK_SKIP_AUTH=1        # 代理不需要认证时
export AWS_BEDROCK_FORCE_HTTP1=1      # 代理仅支持 HTTP/1.1 时

6.6.3 Cloudflare AI Gateway

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 请求。

Note

AI Gateway 认证使用 CLOUDFLARE_API_KEY 作为 cf-aig-authorization。上游认证模式包括：Workers AI（Cloudflare 原生）、统一计费、存储 BYOK 和内联 BYOK。推荐使用统一计费或存储 BYOK。

6.6.4 Cloudflare Workers AI

export CLOUDFLARE_API_KEY=...           # 或使用 /login
export CLOUDFLARE_ACCOUNT_ID=...
pi --provider cloudflare-workers-ai --model "@cf/moonshotai/kimi-k2.6"

Tip

Pi 自动设置 x-session-affinity 以获得 Prefix Caching 折扣。

6.6.5 Google Vertex AI

使用应用默认凭证：

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

或设置 GOOGLE_APPLICATION_CREDENTIALS 指向服务账户密钥文件。

6.7 llama.cpp

Pi 支持 llama.cpp 路由服务器：

使用 /login llama.cpp 配置
使用 /llama 管理已加载的模型
使用 /model 选择已加载的模型

Note

关于 llama.cpp 的服务器设置、模型目录布局和环境变量，请参阅 llama.cpp 专用文档。

6.8 自定义提供商

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

通过扩展：对于需要自定义 API 实现或 OAuth 流程的提供商，创建扩展。

6.9 解析顺序

当为提供商解析凭证时，Pi 按以下顺序查找：

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

Tip

这个解析顺序意味着：命令行参数优先级最高，其次是认证文件，然后是环境变量。如果你在 auth.json 中存储了 Key，它将覆盖同名环境变量。