# Provider 一览

本页列出仓库内置的 provider 实现（`openprogram/providers/` 下每个子目录一个）、各自的接入方式，以及在 Python 代码里直接使用 provider 的方法。内置实现之外，`openprogram providers available` 还能列出几百个走 OpenAI 兼容协议的社区 provider 目录，配置方式相同。

## 内置 provider

接入方式说明：**API key** = 存入凭据库的密钥（`providers login <id>`，也可从环境变量导入）；**OAuth** = 浏览器 / 设备码登录订阅账号；**CLI 凭据** = 直接读外部 CLI 已登录的凭据文件；**云凭据链** = 运行时自动走云厂商的标准凭据链。

| Provider | 协议 | 接入方式 | 备注 |
|---|---|---|---|
| `anthropic` | Anthropic Messages | API key（`ANTHROPIC_API_KEY`） | 显式 prompt caching（`cache_control`，支持 1h TTL） |
| `openai` | OpenAI Responses | API key（`OPENAI_API_KEY`） | Responses 协议自动缓存（`prompt_cache_key`） |
| `openai_responses` / `openai_completions` | OpenAI Responses / Chat Completions | —（共享协议实现，被众多 provider 复用） | |
| `openai_codex` | ChatGPT 后端 | OAuth（ChatGPT 订阅）：浏览器 PKCE 登录；已有的 `codex` CLI 登录态也可用 `providers discover` 导入 | 模型清单从官方端点实时拉取 |
| `azure_openai_responses` | Azure OpenAI Responses | API key（`AZURE_OPENAI_API_KEY`）+ 自填 base URL | |
| `google` | Google Generative AI | API key（`GEMINI_API_KEY` / `GOOGLE_API_KEY`） | thinking 用 token budget 控制 |
| `google_gemini_cli` | Cloud Code Assist | CLI 凭据：直接读 `~/.gemini/oauth_creds.json`，刷新由 Gemini CLI 负责 | |
| `gemini_subscription` | Cloud Code Assist | CLI 凭据：导入 `~/.gemini/oauth_creds.json`（先用 Gemini CLI 登录） | 别名 `gemini`、`gemini-cli` |
| `amazon_bedrock` | Bedrock Converse Stream | 云凭据链（`AWS_PROFILE` / access key / bearer token 等，运行时自动识别） | 显式 prompt caching（`cachePoint`） |
| `github_copilot` | OpenAI Responses 等 | GitHub 浏览器设备码登录，或导入 `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` 环境变量；按需换取 Copilot 短期 token，不落盘 | 不支持 thinking 档位 |
| `deepseek` | OpenAI Completions | API key（`DEEPSEEK_API_KEY`） | reasoner 型号推理不可调档 |
| `openrouter` | OpenAI Completions | API key（`OPENROUTER_API_KEY`) | 聚合网关 |
| `vercel_ai_gateway` | Anthropic Messages | API key（`AI_GATEWAY_API_KEY`） | 聚合网关 |
| `groq` | OpenAI Completions | API key（`GROQ_API_KEY`） | |
| `cerebras` | OpenAI Completions | API key（`CEREBRAS_API_KEY`） | |
| `mistral` | OpenAI Completions | API key（`MISTRAL_API_KEY`） | |
| `xai` | OpenAI Completions | API key（`XAI_API_KEY`） | |
| `xai_subscription` | OpenAI Responses | OAuth（SuperGrok / X Premium+）：浏览器 PKCE 登录 | 模型与 `xai` 相同，走 `cli-chat-proxy.grok.com`（不是 `api.x.ai`） |
| `zai` | OpenAI Completions | API key（`ZAI_API_KEY`） | |
| `huggingface` | OpenAI Completions | API key（`HF_TOKEN`） | |
| `minimax` / `minimax_cn` | Anthropic Messages | API key（`MINIMAX_API_KEY` / `MINIMAX_CN_API_KEY`） | 国际 / 国内两个端点 |
| `minimax_cn_coding_plan` | Anthropic Messages | API key（`MINIMAX_CN_API_KEY` / `MINIMAX_API_KEY`，与 `minimax_cn` 同账号同密钥） | "MiniMax Token Plan (CN)" coding 套餐 |
| `kimi_coding` | Anthropic Messages | API key（`KIMI_API_KEY` / `MOONSHOT_API_KEY`） | |
| `alibaba_token_plan_cn` | OpenAI Completions | 套餐 API key | 别名 `bailian` |
| `opencode` | OpenAI Completions 等 | API key（`OPENCODE_API_KEY`） | |

流式输出所有 provider 都支持（整个层建立在流式接口上）。多模态输入按模型而非按 provider 决定，来自各 provider 的模型目录数据，界面上以模型实际标注为准。prompt caching 只在上表标注处经代码核实。


## 本地模型服务

Ollama、LM Studio、vLLM、llama.cpp 和通用本地服务作为内置 Provider 提供，支持地址配置、可选 API key、模型发现和手动模型 ID。连接多个服务时，可将自定义 Provider 标记为本地服务。配置方式和部署相关 token 限制见[本地模型](local-models.zh.md)。

## 自定义 provider

上表没覆盖的 OpenAI 兼容端点可以在 Web UI 的 Settings → Providers 里添加：必填项只有显示名和 base URL（不填 id 时从名字自动派生）。之后同一个 Fetch 按钮就能浏览该端点 `/models` 返回的模型列表，启用后无需改代码即可使用。自定义 provider 记在配置的 `providers.<id>` 下，标记 `source: "custom"`。

## 库方式使用

在自己的 Python 代码里创建 runtime，首选自动检测：

```python
from openprogram.providers.registry import create_runtime

runtime = create_runtime()                                        # 自动选第一个可用 provider
runtime = create_runtime(provider="anthropic", model="claude-sonnet-4-6")
```

六个 provider 在 `create_runtime` 背后有专属 runtime 行为（OAuth / CLI 凭据接管、按 provider 的约定）：

```python
runtime = create_runtime(provider="anthropic", model="claude-sonnet-4-6")  # Anthropic API key
runtime = create_runtime(provider="openai", model="gpt-4.1")               # OpenAI Responses API
runtime = create_runtime(provider="gemini", model="gemini-2.5-flash")      # Google Generative AI
runtime = create_runtime(provider="anthropic")   # 需要 Anthropic API key
runtime = create_runtime(provider="openai-codex")  # ChatGPT 订阅（Codex OAuth）
runtime = create_runtime(provider="gemini-cli")    # 复用 Gemini CLI 登录态
```

上表其余 provider：`create_runtime(provider=..., model=...)` 会按该模型的协议自动路由，与聊天界面走同一条路径。

Grok Subscription 在代理路由请求头中保留所选模型 ID。选择 `grok-4.6` 时请求该模型，不替换成 `grok-build` 别名。