# 提供商

> 配置 pi 的模型提供商：订阅认证、API 密钥、云端与自定义提供商。

---

LLMS 索引： [llms.txt](/llms.txt)

---

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

## 目录 {#table-of-contents}

- [订阅](#subscriptions)
- [API 密钥](#api-keys)
- [认证文件](#auth-file)
- [云端提供商](#cloud-providers)
- [llama.cpp](#llamacpp)
- [自定义提供商](#custom-providers)
- [解析顺序](#resolution-order)

## 订阅 {#subscriptions}

在交互模式下使用 `/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 {#openai-codex}

- 需要 ChatGPT Plus 或 Pro 订阅
- 由 OpenAI 官方背书：[Codex for OSS](https://developers.openai.com/community/codex-for-oss)

### Claude Pro/Max {#claude-promax}

Anthropic 订阅认证适用于 Claude Pro/Max 账户。第三方工具的使用会消耗[额外用量](https://claude.ai/settings/usage)，并按 token 计费，而不计入 Claude 套餐限额。

### GitHub Copilot {#github-copilot}

- 在 github.com 上直接按 Enter，或输入你的 GitHub Enterprise Server 域名
- 如果出现 "model not supported"，请在 VS Code 中启用该模型：Copilot Chat → 模型选择器 → 选择模型 → "Enable"

### xAI（Grok/X 订阅）{#xai-grokx-subscription}

- 运行 `/login xai`，然后选择 **Use a subscription**
- `XAI_API_KEY` 仍可通过 **Use an API key** 使用

### OpenRouter {#openrouter}

- 运行 `/login openrouter`，然后选择 **Sign in with OpenRouter**，打开 OpenRouter PKCE 授权流程
- 授权会创建一个由用户控制的 OpenRouter API 密钥，从你的 OpenRouter 余额中扣费
- 在远程/无头机器上（例如通过 SSH 连接），浏览器无法访问本地回环回调；此时请将最终重定向 URL（或授权码）粘贴到登录提示中
- `OPENROUTER_API_KEY` 仍可通过 **Use an API key** 使用

### Radius {#radius}

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

## API 密钥 {#api-keys}

### 环境变量或认证文件 {#environment-variables-or-auth-file}

在交互模式下使用 `/login` 并选择一个提供商，即可将 API 密钥存入 `auth.json`；也可以通过环境变量设置凭证：

```bash
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 (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` |
| Baseten | `BASETEN_API_KEY` | `baseten` |
| Kimi For Coding | `KIMI_API_KEY` | `kimi-coding` |
| MiniMax | `MINIMAX_API_KEY` | `minimax` |
| MiniMax (China) | `MINIMAX_CN_API_KEY` | `minimax-cn` |
| Qwen Token Plan (existing catalog) | `QWEN_TOKEN_PLAN_API_KEY` | `qwen-token-plan` |
| Qwen Token Plan (Individual) | `QWEN_TOKEN_PLAN_API_KEY` | `qwen-token-plan-individual` |
| 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` |

环境变量与 `auth.json` 键的对照参见 [`packages/ai/src/env-api-keys.ts`](https://github.com/earendil-works/pi/blob/main/packages/ai/src/env-api-keys.ts) 中的 [`const envMap`](https://github.com/earendil-works/pi/blob/main/packages/ai/src/env-api-keys.ts)。

#### 认证文件 {#auth-file}

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

```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`）时，这些值优先于进程环境变量。

```json
{
  "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-resolution}

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

- **Shell 命令：** 以 `"!command"` 开头时，整个值会作为命令执行，并使用其 stdout（在进程生命周期内缓存）
  ```json
  { "type": "api_key", "key": "!security find-generic-password -ws 'anthropic'" }
  { "type": "api_key", "key": "!op read 'op://vault/item/credential'" }
  ```
- **环境变量插值：** `"$ENV_VAR"` 或 `"${ENV_VAR}"` 使用指定变量的值。插值也可以在更长的字面量中使用。
  ```json
  { "type": "api_key", "key": "$MY_ANTHROPIC_KEY" }
  { "type": "api_key", "key": "${KEY_PREFIX}_${KEY_SUFFIX}" }
  ```
  `$FOO_BAR` 指向变量 `FOO_BAR`；如果 `BAR` 是字面文本，请使用 `${FOO}_BAR`。环境变量缺失时该值视为未解析。
- **转义：** `"$$"` 输出字面量 `"$"`；`"$!"` 输出字面量 `"!"` 而不触发命令执行。
  ```json
  { "type": "api_key", "key": "$$literal-dollar-prefix" }
  { "type": "api_key", "key": "$!literal-bang-prefix" }
  ```
- **字面量：** 直接使用。纯大写字符串（如 `MY_API_KEY`）是字面量；要引用环境变量请使用 `$MY_API_KEY`。
  ```json
  { "type": "api_key", "key": "sk-ant-..." }
  { "type": "api_key", "key": "public" }
  ```

OAuth 凭证在 `/login` 之后也会存储在这里，并自动管理。

## 云端提供商 {#cloud-providers}

### Azure OpenAI {#azure-openai}

```bash
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 {#amazon-bedrock}

使用 `/login amazon-bedrock` 存储 Bedrock API 密钥，或配置以下任一 AWS 环境凭证来源：

```bash
# 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`）。

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

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

```bash
export AWS_BEDROCK_FORCE_CACHE=1
pi --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123
```

如果你要连接 Bedrock API 代理，可以使用以下环境变量：

```bash
# 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-ai-gateway}

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

```bash
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 透传路由（`/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-workers-ai}

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

```bash
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`，以享受[前缀缓存](https://developers.cloudflare.com/workers-ai/features/prompt-caching/)折扣。

### Google Vertex AI {#google-vertex-ai}

使用应用默认凭证（Application Default Credentials）：

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

或者将 `GOOGLE_APPLICATION_CREDENTIALS` 指向服务账号密钥文件。

## llama.cpp {#llamacpp}

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

服务器搭建、模型目录布局、环境变量和命令用法参见 [llama.cpp](/book/pi/llama-cpp/)。

## 自定义提供商 {#custom-providers}

**通过 models.json：** 添加 Ollama、LM Studio、vLLM，或任何使用受支持 API（OpenAI Completions、OpenAI Responses、Anthropic Messages、Google Generative AI）的提供商。参见 [models.md](/book/pi/models/)。

**通过扩展：** 对于需要自定义 API 实现或 OAuth 流程的提供商，可以创建扩展。参见 [custom-provider.md](/book/pi/custom-provider/) 和 [examples/extensions/custom-provider-gitlab-duo](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/examples/extensions/custom-provider-gitlab-duo/)。

## 解析顺序 {#resolution-order}

解析某个提供商的凭证时，顺序如下：

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

---

反链：

- [环境变量](/book/pi/environment-variables/)
- [快速开始](/book/pi/quickstart/)