Provider Sync

核心用法

Provider Sync 用于将上游 OpenAI 兼容端点（/v1/models）的模型列表同步到 OpenClaw 的本地配置文件。通过命令 /provider_sync 触发，支持纯文本参数运行，无需依赖按钮交互。

推荐流程：先执行 /provider_sync provider=all 预览变更，确认无误后执行 /provider_sync provider=all mode=apply 写入配置。写入前会自动备份原配置。

关键功能

• 规范化字段：自动填充 contextWindow、maxTokens、input、reasoning 等模型元数据
• dry-run 预览：默认模式，仅展示差异不写入，安全可控
• 自动清理别名：v2 默认删除 agents.defaults.models 中上游已不存在的条目，避免菜单出现不可用模型
• 多 provider 支持：支持遍历全部或指定单个 provider（如 cli-usa、cliplus、newapi）

权限与安全建议

• 群聊环境：仅限 dry-run / check-only（只读），禁止写入操作
• 私聊环境：允许 apply（写入），重大操作需二次确认
• 敏感信息：写缓存前自动剔除 token、apiKey、authorization 等字段

显著优点

• 操作安全：dry-run → confirm → apply 三段式流程，误操作风险极低
• 配置一致性：自动裁剪过期别名，解决「菜单很多但不可用」的痛点
• 无环境依赖：纯文本命令即可完整操作，适配所有部署环境
• 自动备份：写入前自动备份，便于回滚

潜在缺点与局限性

• 破坏性变更：v2 默认 prune 行为会删除本地白名单中的过期别名，若需保留必须使用 --no-prune-agent-aliases
• 单点写入：仅支持单配置文件路径，分布式配置场景需额外处理
• 上游依赖：完全依赖上游 /v1/models 接口的可用性与数据准确性
• 权限粒度粗：仅区分群聊/私聊，无法细粒度控制到用户角色

适合人群

• OpenClaw 服务器管理员：需要定期维护模型列表
• 多 provider 切换用户：频繁切换上游源时保持配置同步
• 追求配置一致性者：希望 /models 菜单与实际可用模型严格对齐

常规风险

• 配置覆盖：apply 模式直接修改 openclaw.json，错误 provider 参数可能导致配置损坏
• 服务中断：模型别名被误删可能导致相关 agent 暂时不可用
• 缓存泄露：虽然已做敏感字段剔除，但缓存文件权限仍需确保仅 root 可读

核心用法

provider-sync 是一个面向 OpenClaw 生态的配置同步工具，通过 /provider_sync 命令触发，用于将上游 OpenAI 兼容 Provider 的 /v1/models 端点数据同步到本地 openclaw.json 配置。核心工作流遵循「预览→确认→执行」的三段式安全模式：默认 dry-run 模式仅展示差异而不写入；确认后使用 mode=apply 执行同步，自动创建配置备份；v2 版本新增智能裁剪功能，自动清理 agents.defaults.models 中上游已失效的模型别名，避免菜单冗余。

使用方式高度灵活，既支持 provider=all 一键遍历全量 Provider，也支持指定单个 Provider 如 cli-usa、cliplus 进行精准同步。纯文本命令设计确保在任何环境（无按钮面板支持时）均可完整操作。

显著优点

安全防护体系完善：内置敏感字段过滤器，缓存时自动剔除 token/cookie/apiKey/authorization 等关键字；缓存文件强制 chmod 600 权限；网络层采用 TLS 1.2+ 加密，并支持 ETag/Last-Modified 条件缓存减少重复请求。

操作可控性极高：dry-run/check-only/apply 三级模式分层授权，群聊场景默认只读、私聊才开放写入；写入前强制备份原配置，损坏可一键回滚；v2 智能裁剪避免「菜单很多但不可用」的用户体验陷阱。

零依赖纯净实现：纯 Python 标准库构建（urllib/json/subprocess），彻底消除第三方供应链攻击风险，部署维护成本极低。

潜在缺点与局限性

环境依赖限制：需预先配置 Provider 的 baseUrl 与认证信息，对完全零配置的新用户不够友好；多 Provider 批量模式下依赖 subprocess 递归调用，虽经参数过滤仍存在理论上的进程边界风险。

功能边界约束：作为配置同步工具而非模型市场，不具备模型能力评分、价格对比、使用统计等高级管理功能；智能裁剪默认开启且需显式 --no-prune-agent-aliases 关闭，误操作可能导致自定义别名丢失。

审计能力待加强：当前仅 stdout 输出操作摘要，缺乏可选的审计日志持久化，大规模团队使用时变更追溯不够便利。

适合的目标群体

• OpenClaw 运维管理员：需要维护多 Provider、上百模型配置的规模化部署场景
• AI 平台集成工程师：频繁对接新 Provider、需要快速验证模型列表可用性的技术团队
• 安全意识优先的组织：对配置变更备份、敏感信息脱敏有合规要求的金融、医疗、政务领域

使用风险与建议

常规风险：配置损坏（已通过自动备份缓解）、上游 API 临时不可用（建议配合监控告警）、子进程递归参数传递边界（建议生产环境启用参数白名单）。

性能注意：provider=all 模式下串行遍历，Provider 数量过多时同步耗时较长；大模型列表场景下 JSON 解析内存占用需关注。

权限建议：严格遵循「群聊 dry-run、私聊 apply」的分级策略，避免在公开频道暴露配置写入能力；定期清理 ~/.cache/openclaw/provider-sync 缓存目录，防止历史敏感信息残留。