Provider Sync

核心功能

provider-sync 是 OpenClaw 生态的模型列表同步中枢，用于拉取上游 OpenAI 兼容 API 的 /v1/models 端点，将最新模型信息同步到本地 openclaw.json 配置。其核心工作流遵循 dry-run → confirm → apply 的三段式安全模型，确保配置变更可预览、可回退。

显著优点

1. 防御性默认设计：所有操作默认 dry-run 模式，写入前强制二次确认并自动备份原配置
2. 智能模型治理：v2 版本自动裁剪 agents.defaults.models，消除"菜单存在但模型不可用"的幽灵条目
3. 多环境兼容：纯文本命令交互，无依赖 inline button 的 Telegram 扩展，适配所有部署环境
4. 敏感信息脱敏：缓存写入前自动剔除 token/cookie/apiKey/authorization 等字段
5. 灵活参数体系：支持单 provider、全量同步、新增 provider 向导等多种模式

潜在局限与风险

| 局限/风险 | 说明 |

|-----------|------|

| 破坏性变更 | v2 默认 `--prune-agent-aliases` 会删除白名单中上游不存在的模型条目，误操作可能导致 agent 配置丢失 |

| 权限边界模糊 | 群聊默认可执行 dry-run，但"群聊/私聊"权限控制依赖外层 bot 实现，本 skill 本身无强制约束 |

| 上游依赖 | 同步质量取决于 provider `/v1/models` 端点的规范程度，非标准字段可能映射失败 |

| 配置路径硬编码 | 默认路径 `/root/.openclaw/openclaw.json` 需 root 权限，非容器环境可能遇到权限问题 |

适合人群

• OpenClaw 管理员：需要维护多 provider、数十至上百模型的复杂配置场景
• CI/CD 集成者：希望将模型列表同步纳入自动化发布流程
• 多租户运营者：频繁增删 provider、需保持 agents 模型菜单与上游一致

常规风险防控

• ✅ 首次使用务必先 dry-run 预览差异
• ✅ 生产写入前确认备份文件生成（默认自动）
• ⚠️ 如需保留旧白名单行为，显式添加 --no-prune-agent-aliases
• ⚠️ 群聊环境建议通过外层 bot 禁用 mode=apply

核心用法

provider-sync 是一款专为 OpenClaw 设计的配置同步技能，通过 /provider_sync 命令触发。其核心功能是从上游 OpenAI 兼容 API（/v1/models）拉取模型列表，并同步到本地 openclaw.json 配置文件中。

该技能提供三种使用方式：交互式向导（无参数触发，返回可点击蓝色命令选项）、直接参数调用（如 /provider_sync provider=cli-usa）、以及新增 Provider 向导（/provider_sync add）。默认启用 dry-run 预览模式，用户可先查看变更差异，确认后再执行 mode=apply 写入操作。

v2 版本引入重要改进：同步时会自动裁剪 agents.defaults.models 中上游已不存在的模型条目，避免 /models 菜单出现"僵尸选项"。如需保留旧行为，可使用 --no-prune-agent-aliases 参数。

显著优点

1. 安全优先设计：默认 dry-run 模式，写入前强制二次确认，自动创建 .bak.{timestamp} 备份，文件权限设为 600。

2. 敏感数据保护：实现 redact_sensitive_fields() 函数，缓存前自动剔除 apiKey、token、authorization 等敏感字段；缓存 key 使用 SHA256 哈希而非明文存储。

3. 零第三方依赖：纯 Python 标准库实现（urllib、json、pathlib 等），供应链攻击面极小，依赖审计评分 95。

4. 智能网络优化：支持 ETag/Last-Modified 条件请求，30 秒超时机制，600 秒缓存 TTL，减少不必要的 API 调用。

5. 权限分级管控：群聊默认仅允许 dry-run/check-only（只读），私聊才开放 apply 写入权限，防止误操作扩散。

潜在缺点与局限性

• 审计日志待完善：当前仅输出变更摘要，缺乏结构化审计日志记录操作者、会话 ID、变更前后哈希等追溯信息。

• Provider URL 无白名单：用户可配置任意 endpoint，存在 SSRF 理论风险（如访问内网 IP 或元数据地址）。

• 交互确认可强化：当前 dry-run 后需用户手动发送 apply 命令，建议增加更严格的交互式确认（如输入特定文本）。

• 缓存清理策略缺失：未自动清理过期缓存，长期运行可能累积冗余文件。

• 只读配置检测不足：未检测配置文件是否处于版本控制中，可能直接修改受控配置。

适合的目标群体

• OpenClaw 管理员：需要维护多 Provider 模型配置的技术运维人员。
• AI 平台运营者：管理多个上游 API（如 OpenAI、Claude、Gemini 等）的模型接入与下线。
• 开发者与极客：追求配置自动化、厌恶手动编辑 JSON 的进阶用户。
• 团队协作场景：需要标准化模型配置、避免"本地配置漂移"的中小型技术团队。

使用风险与注意事项

| 风险类别 | 说明 | 缓解措施 |

|---------|------|---------|

| 配置覆盖 | apply 模式可能覆盖用户自定义配置 | 自动备份 + dry-run 默认 + 私聊限制 |

| API Key 泄露 | HTTP 请求携带 Authorization header | 缓存前自动脱敏 + 仅请求可信 Provider |

| SSRF 攻击 | 未限制可配置的 endpoint URL | 用户自担风险，建议仅配置官方 API |

| 缓存敏感数据 | 本地缓存可能残留脱敏前数据 | SHA256 缓存 key + 600 权限 + 自动脱敏 |

| 误删模型别名 | v2 默认 prune 可能删除仍需要的别名 | 使用 `--no-prune-agent-aliases` 保留 |

使用建议：生产环境务必先 dry-run 预览；定期备份 openclaw.json；仅配置经过验证的 Provider URL；关注技能更新日志以获取安全补丁。