Model Registry Manager

intent

Use this skill when syncing provider model catalogs into OpenClaw, validating model health, and keeping your registry in sync with upstream changes. The skill detects new models from provider /models endpoints, deduplicates by provider-native id, probes for usability, registers passing models into config, and maintains an audit trail of changes. Run this before enabling scheduled syncs, and re-run it whenever a provider adds/removes models or your config drifts.

inputs

Provider model endpoint

• HTTP GET endpoint at {provider_base_url}/models returning JSON array with id, name, capabilities, context_window, etc.
• No auth required if public, otherwise bearer token or API key via env var

OpenClaw config paths

• agents.defaults.model (current primary model)
• agents.defaults.models (fallback chain, if present)
• models.providers (provider-native model registry)
• file location: config/agents.yml or equivalent in your workspace

Provider credentials (if needed)

• env var: PROVIDER_API_KEY (bearer token format)
• scope: read-only access to /models endpoint
• test: curl the endpoint before running the skill

Probe validation script

• location: scripts/probe-model.js or equivalent
• input: {provider, model_id, endpoint, auth_token}
• output: {status: "pass"|"fail", reason, latency_ms}
• timeout: 5 seconds per model
• required: can invoke from procedure steps

Workspace learnings archive

• location: .learnings/ directory
• format: markdown files, one per discovery/fix
• write permission required

procedure

Step 1: Inspect current config state

• input: file path to config/agents.yml
• action: read and parse the file; extract agents.defaults.model, agents.defaults.models, and models.providers sections
• output: structured dict with current model assignments and provider registry snapshot
• edge case: if file missing or unparseable, halt and report file not found

Step 2: Fetch remote model list

• input: {provider_base_url, auth_token (optional)}
• action: HTTP GET {provider_base_url}/models; parse JSON response as array
• output: list of model objects with at least {id, name, ...}
• edge case: if request times out (>10s), retry up to 2 times; if all retries fail, report network error and halt
• edge case: if response status != 200, report HTTP error code and response body, halt
• edge case: if response is empty array, log warning but continue (provider may have no models)

Step 3: Deduplicate by provider-native id

• input: remote model list from step 2
• action: group models by id field; if duplicates exist, keep first occurrence (stable sort by list order), discard rest
• output: deduplicated list, same structure
• note: document count of duplicates removed in a summary log

Step 4: Probe each remote model for usability

• input: deduplicated model list, provider endpoint, auth token
• action: for each model, invoke probe script with {provider, model_id: id, endpoint, auth_token}; collect probe response
• output: two lists: {usable_models: [...], unusable_models: [{model_id, reason, ...}, ...]}
• timeout: 5 seconds per model; if timeout, treat as unusable with reason "probe_timeout"
• parallelism: probe up to 5 models concurrently to avoid long runs; preserve ordering in output
• edge case: if probe script missing or crashes, treat that model as unusable with reason "probe_unavailable"

Step 5: Cross-reference usable models with current config

• input: usable models from step 4, current registry from step 1
• action: for each usable model, check if models.providers[provider][model.id] exists in config; split into new_models (not in config) and existing_models (already registered)
• output: {new_models: [...], existing_models: [...], retired_models: [...]}
• retired_models = models in config but not in current usable list (i.e., provider removed them or they failed probe)
• note: do not delete retired models in this step; flag them for review

Step 6: Register new usable models

• input: new_models list from step 5, current config
• action: for each new model, add entry to models.providers[provider][model.id] with keys id (provider-native), name (provider-native), capabilities, context_window, etc.; preserve all provider-returned fields
• output: updated config dict with new registrations
• rule: use provider-returned id and name as-is; do not normalize, slug, or rename unless OpenClaw schema explicitly requires it
• edge case: if a new model name conflicts with an existing key in a different provider, log warning but proceed (namespacing is per-provider)

Step 7: Validate gateway/service health

• input: updated config
• action: write config to temp file; reload service or trigger config reload via API endpoint; invoke a simple health check (e.g., GET /health on gateway)
• output: health status {healthy: true/false, response_code, latency_ms}
• timeout: 10 seconds for health check
• edge case: if health check fails, revert config to previous state and halt with error

Step 8: Commit config and archive learnings

• input: validated updated config, execution summary
• action: write updated config to config/agents.yml; create or append to .learnings/{date}-model-sync-{provider}.md with: models added, models probed, count of failures, any corrections or debugging notes discovered during this run
• output: confirmed file write location, learnings entry location
• rule: always archive learnings, even on success; treat this as mandatory, not optional

decision points

If remote model list is empty (step 2 output):

• log warning "no models returned from provider endpoint"
• proceed to step 3 onwards with empty list
• do not treat as failure; provider may legitimately have no models
• do not auto-delete existing models from config; require explicit user confirmation

If all models fail probe (step 4 output):

• log critical warning "all remote models failed usability probe"
• do not register any new models
• do not commit config changes
• halt and require user review before retry
• provide list of failure reasons to guide debugging

If new models exist but gateway health fails (step 7):

• revert config file to pre-sync state
• log error with health check response
• halt and require manual intervention
• do not proceed to step 8 commit

If config file is missing (step 1):

• halt immediately
• report exact file path that was not found
• do not create a new config; require user to provide valid config first

If probe script is missing (step 4):

• halt immediately
• report path to missing probe script
• do not attempt to register models without probe validation

If model name conflicts with existing provider (step 6):

• log warning with conflict details (which providers, which model names)
• proceed with registration (namespacing is per-provider, so conflict is only informational)
• do not block registration

If user has corrected you or you debugged a multi-attempt fix (step 8):

• add correction/fix to .learnings/ file as mandatory next step
• do not skip archiving even if user didn't explicitly ask for it

output contract

Config file

• location: config/agents.yml
• format: YAML with models.providers[{provider}][{model_id}] entries
• each entry: at least {id, name, capabilities, context_window, ...} from provider
• validation: must be parseable YAML and pass OpenClaw schema validation before commit

Sync report

• location: reports/model-registry/{date}-{provider}-sync.json
• format: JSON with fields:
  • timestamp (ISO 8601)
  • provider (string)
  • remote_model_count (int, before dedup)
  • deduplicated_count (int, after dedup)
  • usable_count (int, passed probe)
  • new_registered (int, added to config)
  • retired_flagged (int, no longer in remote or failed probe)
  • gateway_health (true/false)
  • config_committed (true/false)
  • errors (array of error strings, if any)

Learnings archive

• location: .learnings/{date}-model-sync-{provider}.md
• format: markdown
• sections: models added, probe failures (if any), user corrections applied, debugging notes, successful retry path (if multiple attempts)
• mandatory: every run produces or updates one learnings file

outcome signal

The skill worked if:

1. Sync report exists and shows config_committed: true - config was safely written and validated
2. No errors in report - all steps completed without halt conditions
3. Gateway health check passed - service remained healthy after config reload
4. Learnings file created/updated - mandatory archive recorded even on success
5. New models visible in config - open config/agents.yml and confirm new models.providers[{provider}][{id}] entries with provider-native names intact
6. No silent failures - if any model failed probe, it appears in report under errors or retired_flagged, not silently skipped

Run the skill again if:

• sync report shows config_committed: false
• any error in errors array
• gateway health check failed (config was reverted)
• you notice models missing from config that should be there (re-run step 2-5 to diagnose)

Before enabling scheduled syncs (cron jobs), you must complete one full run with config_committed: true and gateway_health: true, then manually verify that agents.defaults.model and agents.defaults.models are correctly set for your use case. Primary/fallback selection is out of scope for this skill; manage routing policy separately.