问题背景
在 OpenClaw 使用过程中，一个常见痛点是同一个 Provider 可能有多个变体需要接入：
- OpenAI：官方 API、Azure OpenAI、代理端点
- Anthropic：官方 Claude、Bedrock 上的 Claude
- Qwen：DashScope、百炼、阿里云海外
这些变体使用相同的 API Key 或相似的认证方式，但在 v2026.4.8 及之前需要重复配置每一个：
# 旧方式：重复配置
providers:
openai:
apiKey: "sk-xxx"
openai-proxy:
apiKey: "sk-xxx" # 重复
openai-azure:
apiKey: "sk-xxx" # 重复
Provider Auth Aliases 解决方案
OpenClaw v2026.4.9 引入了 providerAuthAliases 机制，允许 Provider 变体声明共享认证配置。
Provider manifest 可以声明它与其他 Provider 共享：
- 环境变量
- 认证 Profile
- 配置文件中的认证信息
- API Key 注入流程
基础用法
场景 1：OpenAI 及其变体
# config.yaml
providers:
openai:
apiKey: "$OPENAI_API_KEY"
baseUrl: "https://api.openai.com/v1"
openai-proxy:
baseUrl: "https://my-proxy.example.com/v1"
authAlias: "openai" # 继承 openai 的 apiKey
openai-forward:
baseUrl: "https://forward.example.com/v1"
authAlias: "openai"
这样三个 Provider 变体共享同一个 API Key，只需更新一处即可影响所有。
场景 2：多区域 Anthropic
providers:
anthropic:
apiKey: "$ANTHROPIC_API_KEY"
anthropic-bedrock:
region: "us-east-1"
authAlias: "anthropic"
anthropic-vertex:
project: "my-gcp-project"
authAlias: "anthropic"
场景 3：Qwen 多平台
providers:
qwen:
apiKey: "$DASHSCOPE_API_KEY"
baseUrl: "https://dashscope.aliyuncs.com/api/v1"
qwen-intl:
baseUrl: "https://dashscope-intl.aliyuncs.com/api/v1"
authAlias: "qwen"
qwen-bailian:
baseUrl: "https://bailian.aliyuncs.com/v1"
authAlias: "qwen"
高级用法
环境变量共享
可以通过环境变量级别共享：
providers:
claude-official:
envAlias: "CLAUDE_KEY"
claude-cn:
envAlias: "CLAUDE_KEY" # 使用相同的环境变量
baseUrl: "https://claude-cn.example.com"
只需设置一次环境变量：
export CLAUDE_KEY=sk-ant-xxx
Auth Profile 共享
如果使用 Auth Profile 机制：
authProfiles:
corporate:
apiKey: "$CORP_KEY"
headers:
X-Company: "acme"
providers:
gpt-corporate:
authProfile: "corporate"
claude-corporate:
authProfile: "corporate" # 共享同一 profile
条件别名
可以根据环境选择不同的别名：
providers:
primary-llm:
authAlias: "${ENV == 'prod' ? 'openai-prod' : 'openai-dev'}"
实际场景
场景：开发/生产环境切换
# config.dev.yaml
providers:
openai-dev:
apiKey: "$OPENAI_DEV_KEY"
baseUrl: "https://api.openai.com/v1"
primary:
authAlias: "openai-dev"
# config.prod.yaml
providers:
openai-prod:
apiKey: "$OPENAI_PROD_KEY"
baseUrl: "https://api.openai.com/v1"
primary:
authAlias: "openai-prod"
Agent 代码始终使用 primary，部署时切换配置文件即可。
场景：多租户隔离
providers:
openai-tenant-a:
apiKey: "$TENANT_A_KEY"
openai-tenant-b:
apiKey: "$TENANT_B_KEY"
openai-tenant-c:
authAlias: "openai-tenant-a" # 租户 C 复用 A 的配额
场景：成本优化路由
providers:
openai:
apiKey: "$OPENAI_KEY"
openai-cheap:
authAlias: "openai"
modelOverride: "gpt-5-nano" # 简单任务用低成本模型
openai-smart:
authAlias: "openai"
modelOverride: "gpt-5-pro" # 复杂任务用高性能模型
调试技巧
查看别名解析
openclaw doctor providers
输出会显示每个 Provider 实际使用的认证来源：
openai → direct (apiKey)
openai-proxy → alias: openai
openai-azure → alias: openai
验证认证链
openclaw providers auth-trace openai-proxy
显示从 openai-proxy 到最终认证源的完整链路。
测试连接
openclaw providers test openai-proxy
最佳实践
- 使用有意义的 alias 名称：避免循环依赖
- 环境变量优先：敏感信息放环境变量而非配置文件
- 文档化别名关系：在配置文件加注释说明别名意图
- 避免深层嵌套：Provider A 的别名指向 B，B 的别名再指向 C 会让调试复杂
- 定期审计：用
openclaw doctor providers检查别名关系
迁移指南
从旧配置迁移到 Auth Aliases：
迁移前
providers:
openai:
apiKey: "sk-xxx"
openai-2:
apiKey: "sk-xxx"
openai-3:
apiKey: "sk-xxx"
迁移后
providers:
openai:
apiKey: "$OPENAI_KEY"
openai-2:
authAlias: "openai"
openai-3:
authAlias: "openai"
运行迁移辅助工具：
openclaw doctor providers --suggest-aliases
注意事项
- Provider Auth Aliases 需要 OpenClaw v2026.4.9 或更高版本
- 别名只影响认证信息共享，不影响 endpoint 和模型选择
- 循环别名（A → B → A）会导致配置加载失败
- 别名关系在网关启动时解析，运行时修改需要重启
- Provider 的能力（支持的模型、功能）仍由各自配置决定