Provider Sync

核心用法

/provider_sync 是 OpenClaw 生态的模型配置同步中枢，解决多上游 Provider 模型列表与本地配置脱节的痛点。通过标准 OpenAI /v1/models 端点拉取上游模型元数据，自动规范化字段（contextWindow/maxTokens/reasoning 等），并以 dry-run → confirm → apply 的三段式交互确保变更可控。

显著优点

• 零误触设计：默认 dry-run 模式，所有变更先预览再确认，写前自动备份配置
• 智能裁剪：v2 默认 prune agents.defaults.models，消除「菜单有但不可用」的幽灵条目
• 多源适配：内置 generic/gpt/gemini 三种 profile，自动适配 OpenAI/Gemini/类 OpenAI 上游的字段差异
• 全环境兼容：纯文本命令交互，无需依赖 Telegram inlineButtons

潜在局限

• 需上游严格遵循 OpenAI /v1/models 格式，非标准端点可能需手动 mapping
• probe 探测参数为高级功能，配置错误可能导致同步失败
• --no-prune-agent-aliases 遗留模式会累积过期别名，长期可能污染配置

适合人群

• 运维多上游 OpenAI 兼容 API 的 OpenClaw 管理员
• 需要定期对齐模型列表与本地白名单的自动化场景
• 追求「预览-确认-应用」安全闭环的配置变更工作流

常规风险

| 场景 | 风险等级 | 说明 |

|:---|:---|:---|

| 群聊执行 apply | ⚠️ 高 | 默认建议群聊仅 dry-run，私聊才允许 apply |

| 未备份直接 apply | ⚠️ 中 | 虽已自动备份，仍建议关键配置手动异地备份 |

| 上游返回敏感字段 | ✅ 已处理 | 脚本落盘前会剔除认证相关字段，避免缓存污染 |

| 网关重启时机 | ⚠️ 中 | apply 后需手动 `/restart` 生效，避免自动重启导致意外断线 |

核心用法

Provider Sync 是一款专为 OpenClaw 设计的模型配置同步工具，通过聊天命令 /provider_sync 触发。用户可通过交互式命令选项或直参模式，将上游 Provider（如 cli-usa、cliplus、newapi 等）的 /v1/models 接口返回的模型列表同步至本地 openclaw.json 配置。

技能采用三步闭环设计：dry-run 预览差异 → 用户确认 → apply 应用并备份。v2 版本默认启用智能裁剪功能，自动清理 agents.defaults.models 中上游已下架的模型别名，确保 /models 菜单与实际可用模型严格对齐。新增 Provider 支持向导式交互，全程含二次确认机制。

显著优点

极致轻量：纯 Python 标准库实现，零第三方依赖，攻击面极小，部署无负担。

安全优先：敏感字段自动脱敏后才写入缓存；配置文件 600 权限保护；默认 dry-run 模式杜绝误操作。

交互友好：无按钮环境 fallback 到蓝色命令选项，任何终端均可点击复制完成操作。

合规完备：通过 GDPR 数据最小化、备份回滚、用户确认等 6 项合规检查，隐私与可用性兼顾。

潜在缺点与局限

来源可信度受限：T3 级个人/社区项目，无企业组织背书，部分企业场景可能需额外审计。

网络依赖风险：需主动访问用户配置的 Provider 端点，若上游服务异常或网络隔离环境可能影响同步。

功能边界明确：仅支持 OpenAI 兼容接口的模型列表同步，非通用配置管理工具；网关重启需单独执行 /restart。

群聊功能受限：出于安全设计，群聊环境仅开放只读模式，配置变更需私聊完成。

适合的目标群体

• OpenClaw 网关管理员：需要定期同步上游模型列表、维护多 Provider 配置的运维人员。
• AI 服务集成开发者：对接多个 OpenAI 兼容 API（Gemini、GPT、Codex 等），需规范化模型字段的工程师。
• 小型团队技术负责人：追求轻量、安全、零依赖工具，不愿引入复杂配置管理系统的技术决策者。

常规使用风险

配置误覆盖：尽管有 dry-run 和备份机制，若用户跳过预览直接 apply，仍可能因上游异常返回导致配置异常。

网络延迟与超时：多 Provider 全量同步时，任一上游响应缓慢可能拖慢整体流程；建议分 Provider 执行。

缓存残留：长期运行后缓存目录可能累积脱敏数据，建议定期清理 ~/.cache/openclaw/provider-sync/。

权限配置疏忽：若手动修改 openclaw.json 后未保持 600 权限，可能暴露 Provider 配置结构信息。