provider-sync

# Provider Sync

**触发方式：在聊天里输入 `/provider_sync`**

Sync upstream provider metadata into local OpenClaw config with a review-first workflow.

## v2.0.0 重要变更（Breaking）
- 默认会**裁剪**（prune）`agents.defaults.models`：让 `/models` 的菜单条目数 **永远与** `models.providers.<provider>.models`（上游真实返回）对齐。
- 如你希望保留旧行为（不删除白名单条目），使用 `--no-prune-agent-aliases`。

## What it does

- fetches upstream provider metadata or model lists
- maps and normalizes model entries for OpenClaw
- previews diffs before any real write
- writes minimal changes to one provider subtree and creates a backup

## Slash command (规范流程)

### Scope / 权限收紧（你已确认启用）

- **群聊**：只允许 `dry-run` / `check-only`（只读）。
- **私聊**：允许 `dry-run` + `apply` + `新增 provider` + `重启`。
- 群聊中如果触发 `apply` / `新增 provider` / `重启`：直接拒绝，并提示“请私聊操作”。

This skill is **user-invocable** as: `/provider_sync` (note the underscore).

Design goals:

- **Always dry-run first** → show diff summary → explicit confirmation → apply.
- Default to **provider-scoped writes only** (`models.providers.<provider-id>`).
- Treat **Gateway restart** as a separate, explicit step.

### Canonical usage

- Interactive wizard (recommended):
  - `/provider_sync`
- Dry-run (default):
  - `/provider_sync provider=<id>`
- Check-only:
  - `/provider_sync provider=<id> mode=check-only`
- Apply (still gated by an explicit confirmation step; button tap is acceptable confirmation):
  - `/provider_sync provider=<id> mode=apply`

Supported args (all optional unless noted):

- `provider=<id>` (required)
- `config=<path>` (default: `/root/.openclaw/openclaw.json`)
- `endpoint=<url>` (default: derived from provider baseUrl: `${baseUrl}/models`)
- `mapping=<path>` (default: `{baseDir}/references/mapping.openai-models.json`)
- `mode=dry-run|check-only|apply` (default: `dry-run`)
- `normalize=1|0` (default: `1`)
- `profile=generic|gemini` (default: `generic`)
- `pres...