Provider 配置指南
Provider 是 AI 模型的接入通道。wesclaw 支持多种 Provider 配置方式，你可以使用 WES 平台提供的模型，也可以接入自己的 API Key。
三种 Provider 来源
| 来源 | 标识前缀 | 说明 |
|---|---|---|
| WES 平台 | wes: | weisyn 平台提供的模型，使用平台余额 |
| 组织托管 | org: | 企业组织统一管理的模型 |
| 自有密钥 | byok: | 你自己的 API Key（Bring Your Own Key） |
BYOK 私有 Provider 配置
在设置页面配置自有 Provider：
- 进入 设置 → Provider 管理
- 点击"添加 Provider"
- 填写以下信息：
- 名称：自定义名称（如"我的 OpenAI"）
- 类型：openai / anthropic / azure_openai 等
- Base URL：API 端点地址
- API Key：你的密钥（通过 SecretRef 安全存储）
- 模型列表：声明可用的模型及其能力（上下文窗口、是否支持 Vision 等）
Provider 策略
每个 Cell 可以配置 Provider 策略，决定如何选择 Provider：
| 策略 | 说明 | 适用场景 |
|---|---|---|
own_only | 只使用自有 Provider | 数据敏感场景 |
shared_only | 只使用平台共享 Provider | 无自有密钥时 |
own_first | 优先自有，fallback 到共享 | 推荐配置 |
shared_first | 优先共享，fallback 到自有 | 平台模型优先 |
桌面版默认为 own_only（个人版通常使用自己的 API Key）。
自动推导：当只有一侧有 Provider 时，策略会自动推导。两侧都有时必须显式声明。
密钥安全
Provider 密钥通过 SecretRef 机制管理：
- inline：密钥经 AES-256-GCM 加密后存储在本地数据库，密钥文件保存在
{DataDir}/secrets/spec.key - env：从环境变量读取，密钥不落盘
- live：运行时动态获取（WES/org Provider 使用此模式）
密钥不会进入子进程环境变量（SanitizeEnv 保护）。
模型能力声明
配置 Provider 时，每个模型需要声明其能力：
- ContextWindow：上下文窗口大小（必填，引擎不猜测）
- SupportsVision：是否支持图片输入
- MaxOutputTokens：最大输出 Token 数
未配置 ContextWindow 的模型会使用经济预算，长会话可能触发 Provider 的 context_length_exceeded 错误。
WES 平台 Provider
使用 WES 平台模型时：
- 登录 weisyn 账号后自动可用
- 消耗平台钱包余额
- 支持的模型列表由平台 catalog 决定（
catalog.yaml） - 欠费时 WES 模型会被标记为
disabled，但自有模型不受影响
测试 Provider 连通性
配置完成后，可以测试 Provider 是否正常工作：
- 在 Provider 管理页面点击"测试连接"
- 支持三种测试模式：Chat（默认）、Embedding、Vision
- 测试成功后才建议在对话中使用
相关文档
- 计费与钱包 →
billing-wallet.md - 多模型切换 →
multi-model.md - 安全与隐私 →
security-privacy.md - 快速开始 →
quickstart.md