跳转至

控制 UI 和 API 密钥

在 Control UI 中配置提供商

在 Control UI 中打开 设置 → 模型，以添加、替换或移除提供商 API 密钥。该页面和 openclaw models auth paste-api-key 使用相同的凭据写入器：密钥材料保留在认证存储中，已配置的提供商引用已保存的配置文件。环境变量提供的密钥仍由 Gateway 进程环境管理。该页面显示凭据来源，但不会泄露密钥。

保存密钥与刷新目录是两件独立的事情。如果刷新失败，已保存的密钥仍然保留；请按照报告的恢复步骤操作。移除已存储的密钥会保留模型默认值和提供商连接设置。查看 Auth 配置文件 了解对应的 CLI 命令。

当凭据、模型目录和配置就绪后，提供商控件会立即出现。使用量和本地成本随后独立加载，因此使用量响应缓慢不会阻止提供商设置。

账户配额恢复后，模型可用性会反映已恢复的账户，即使目录刷新是在其被阻止期间开始的。

从页面头部打开 模型设置 以检查检测到的 AI 访问。可用时，它会显示认证方法（API 密钥或账户登录）以及提供商或本地运行时报告的实际电子邮件地址。API 密钥和令牌保持隐藏。

使用 测试连接 运行实时的提供商探针，查看延迟或分类的认证、速率限制、计费、超时或响应错误。探针会发起真实的提供商请求，并可能消耗少量令牌。还可以从提供商卡片上退出 OAuth 和令牌配置文件。

默认设置 卡片管理已配置模型目录中的主模型、实用模型、第一回退、思考级别和 Fast 模式。更改会自动保存到现有的 agents.defaults 设置中。对于实用模型，自动 会将设置留空，已禁用 会存储空字符串以关闭实用路由。

回退选择器编辑有序回退链中的第一个模型。替换它会保留任何已配置的后续回退；选择 无回退模型 会清空整个链。使用 openclaw models fallbacks 管理完整的有序列表。

插件拥有的提供商行为

大多数提供商特定逻辑位于提供商插件（registerProvider(...)）中，而 OpenClaw 保留通用推理循环。插件负责接入流程、模型目录、认证环境变量映射、传输/配置规范化、工具模式清理、故障转移分类、OAuth 刷新、用量报告、思考/推理配置文件等。

提供商 SDK 钩子的完整列表和捆绑插件示例位于 提供商插件。需要完全自定义请求执行器的提供商属于一个独立且更深入的扩展面。

Note

提供商拥有的运行器行为位于显式的提供商钩子上，例如重放策略、工具模式规范化、流包装以及传输/请求辅助函数。旧版 ProviderPlugin.capabilities 静态属性包仅用于兼容，共享运行器逻辑不再读取它。

API 密钥轮换

密钥来源与优先级

可通过以下方式配置多个密钥：

  • OPENCLAW_LIVE_<PROVIDER>_KEY（单一实时覆盖，优先级最高）
  • <PROVIDER>_API_KEYS（逗号或分号分隔的列表）
  • <PROVIDER>_API_KEY（主密钥）
  • <PROVIDER>_API_KEY_*（编号列表，例如 <PROVIDER>_API_KEY_1）

对于 Google 提供商，GOOGLE_API_KEY 也会作为回退包含在内。密钥选择顺序保留优先级，并去除重复值。

轮换何时触发
  • 仅当收到速率限制响应时，才会使用下一个密钥重试请求（例如 429、rate_limit、quota、resource exhausted、Too many concurrent requests、ThrottlingException、concurrency limit reached、workers_ai ... quota limit exceeded 或周期性的用量限制消息）。
  • 非速率限制失败会立即失败；不会尝试密钥轮换。
  • 当所有候选密钥都失败时，返回最后一次尝试的最终错误。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw