控制 UI 和 API 密钥
在 Control UI 中配置提供商¶
在 Control UI 中打开 设置 → 模型,即可添加、替换或移除提供商 API 密钥。此页面与 openclaw models auth paste-api-key 使用同一个凭据写入器:密钥材料保存在认证存储中,已配置的提供商引用已保存的配置文件。通过环境提供的密钥仍由 Gateway 进程环境管理。该页面会显示凭据来源,但不会显示密钥本身。
保存密钥与刷新目录是相互独立的操作。如果刷新失败,已保存的密钥仍然保留;请按报告中的恢复步骤操作。移除已存储的密钥后,模型默认设置和提供商连接设置仍会保留。有关对应的 CLI 命令,请参阅 认证配置文件。
只要凭据、模型目录和配置就绪,提供商控件就会立即出现。使用量和本地成本随后独立加载,因此使用量响应缓慢不会阻塞提供商设置。
当账户配额恢复后,模型可用性会反映已恢复的账户,即使目录刷新是在账户受限期间开始的也是如此。
从页面头部打开 模型设置,可查看检测到的 AI 访问信息。如果可用,它会显示认证方式(API 密钥或账户登录)以及提供商或本地运行时报告的实际电子邮件地址。API 密钥和 token 始终保持隐藏。
使用 测试连接 可运行一次实时的提供商检查,并查看延迟或分类后的认证、速率限制、计费、超时或响应错误。此类检查会发起真实的提供商请求,并可能消耗少量 token。OAuth 和 token 配置文件也可以从提供商卡片上退出登录。
默认设置 卡片可管理已配置模型目录中的主模型、实用模型、第一个回退模型、思考级别和快速模式。更改会自动保存到现有的 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