核心用法
provider-sync 是一款面向 OpenClaw 网关的模型配置同步工具，核心能力是将上游供应商（OpenAI/Gemini 等）的 /v1/models 接口数据拉取至本地配置，实现模型列表的自动化管理。
交互流程：
- 触发：聊天输入
/provider_sync - 预览（默认）：
provider=<id>或provider=all，dry-run 模式显示差异 - 确认应用：追加
mode=apply写入配置，自动备份原文件 - 生效：配置变更后需执行
/restart重启网关
关键特性：
1. 智能字段规范化：自动填充 contextWindow/maxTokens/reasoning 等字段
2. v2 自动裁剪：默认删除 agents.defaults.models 中上游已不存在的模型别名，避免菜单出现"幽灵选项"
3. 多供应商支持：all 参数可批量遍历所有已配置 provider
4. 新增向导：/provider_sync add 提供交互式 provider 接入引导
显著优点
- 防御性设计：dry-run → apply 的两段式确认，配合自动备份，最大限度降低配置误操作风险
- 跨环境兼容：纯文本命令方案，不依赖 Telegram inlineButtons，任何部署环境可用
- 权限分级：群聊默认只读（dry-run/check-only），私聊才开放 apply 权限
- 敏感信息保护：落盘前自动剔除认证相关字段，防止上游异常响应污染缓存
潜在局限
- 非即时生效：配置 apply 后需手动
/restart，无法热更新 - v2 破坏性变更：默认启用
--prune-agent-aliases，旧版白名单条目会被删除；需显式传--no-prune-agent-aliases保留 - 上游依赖：完全依赖供应商
/v1/models接口可用性，异常时同步失败 - 手动重启风险：网关重启会导致短暂断线，生产环境需谨慎选择时机
适合人群
- OpenClaw 网关管理员：需要维护多供应商模型列表的运维人员
- 多模型切换用户：频繁增删模型、调整模型参数的高级用户
- 自动化部署场景：CI/CD 流水线中需要程序化同步模型配置
常规风险
| 风险点 | 说明 | 缓解措施 |
|--------|------|----------|
| 配置覆盖 | apply 模式直接改写 `openclaw.json` | 自动备份 + dry-run 预览 |
| 误删模型别名 | v2 默认裁剪上游不存在的 agent 默认模型 | `--no-prune-agent-aliases` 参数 |
| 敏感信息泄露 | 上游响应可能包含认证字段 | 落盘前字段过滤 |
| 服务中断 | 重启网关导致连接中断 | 私聊二次确认 + 择时执行 |
| 权限扩散 | 群聊中误操作 apply | 默认群聊只读限制 |