> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerone.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider 配置

> 集中配置模型供应商、端点和凭据。

# 配置 Provider

Provider 描述模型服务的类型、端点、模型和凭据。Hub 内置 Anthropic、OpenAI、GLM、Kimi 与 Bailian 等预设，也支持兼容端点。

首次启动时 Hub 会写入 5 个共享 Provider 模板：`anthropic-thirdparty` / `openai-thirdparty`（自定义兼容 API 模板，填写 `base_url` + `api_key`）、`glm-cn`（GLM Coding Plan）、`kimi-cn`（Kimi Code）、`bailian`（阿里云百炼）。这些模板不预填任何密钥，各租户首次使用时按 copy-on-write 复制后填写。

## 凭据处理

Provider API key 属于敏感数据。Hub 使用 AES-GCM 加密锁定的 key；只有 `admin` 与 `maintainer` 可以读取敏感配置。生产环境应从 secret manager 注入加密密钥，不要提交到仓库。

| 变量                        | 必填 | 默认值 | 说明                                                     |
| ------------------------- | -- | --- | ------------------------------------------------------ |
| `PROVIDER_ENCRYPTION_KEY` | ⚠️ | —   | Provider API key 的加密密钥（32 字节 hex）。**不设置则明文存储**——仅限开发环境 |

生成加密密钥：

```bash theme={null}
openssl rand -hex 32
```

读取接口（`GET /api/v1/providers`、`GET /api/v1/providers/:id` 及管理列表）只返回掩码后的 key；明文仅能通过 `POST /api/v1/admin/providers/:id/reveal-key`（admin/maintainer，按租户隔离）获取。详见 [API Reference](/zh/hub/api-reference)。

<Warning>`PROVIDER_ENCRYPTION_KEY` 一旦泄漏，所有已存储的 API key 都可能被解密。生产环境务必设置并妥善保管。</Warning>

## 租户语义

内置 Provider 作为共享只读种子数据（`tenant_id` 为空串哨兵）。租户编辑共享 Provider 时，Hub 会按 copy-on-write 创建租户自己的记录，不会修改全局种子；不同租户可各自持有同 `key` 的 Provider（`(tenant_id, key)` 复合唯一）。

## 验证连通性

配置后，在 Agent 中选择 Provider 与模型，再进行一次最小连接验证。也可以用探活接口直接测试：

```bash theme={null}
# 测试已保存的 Provider
curl -X POST http://localhost:8081/api/v1/admin/providers/1/probe \
  -H "Authorization: Bearer $TOKEN"

# 测试未保存的配置
curl -X POST http://localhost:8081/api/v1/admin/providers/probe \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "baseUrl": "https://api.anthropic.com",
    "apiKey": "sk-ant-...",
    "protocol": "anthropic",
    "authStyle": "api_key"
  }'
```

连接失败时依次检查端点、认证、模型 ID 和网络出口。

完整环境变量见 [配置](/zh/hub/configuration)，密钥存储模型见 [数据模型](/zh/hub/data-model)。