Initial commit: OpenClaw ops workspace

skills/model-selector/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: model-selector
+description: Safely change an agent's primary and fallback models by validating IDs against the live LLM proxy model list. Use for model switches, fallback chain updates, and model-availability troubleshooting.
+---
+
+# Model Selector
+
+## Core Rules
+
+1. Never edit config files directly; always use `openclaw config` commands.
+2. Validate model IDs against both `/v1/models` and local `openclaw.json` llm-proxy catalog before proposing changes.
+3. Keep at least 2 fallback models (unless user explicitly asks otherwise).
+4. Do not remove a primary model without setting a replacement.
+5. Use exact IDs from the model catalog; do not guess.
+6. Prefer provider diversity in fallbacks.
+7. Get explicit user approval before writing config.
+8. Treat `/model` as temporary; it creates per-session overrides.
+9. After backend default changes, clear session pins and reset active sessions.
+10. Always report back the exact `openclaw config` commands executed.
+
+## Workflow
+
+### 1) Fetch Available Models
+
+```bash
+bash {baseDir}/scripts/list-models.sh
+bash {baseDir}/scripts/list-models.sh --providers
+```
+
+### 2) Validate Candidate IDs
+
+```bash
+bash {baseDir}/scripts/validate-model.sh "nvidia_nim/moonshotai/kimi-k2.5"
+```
+
+### 3) Inspect Current Configuration
+
+```bash
+bash {baseDir}/scripts/show-current.sh
+```
+
+### 4) Apply Backend Model Changes
+
+Preferred (comprehensive) flow:
+
+```bash
+bash {baseDir}/scripts/switch-models.sh \
+  --non-main-primary "nanogpt/zai-org/glm-5" \
+  --non-main-fallbacks "lightning_ai/lightning-ai/kimi-k2.5,nanogpt/zai-org/glm-4.7" \
+  --clear-session-pins \
+  --pattern "gemini-3-flash"
+```
+
+Legacy defaults-only flow (does not migrate runtime session pins by itself):
+
+```bash
+# Primary only
+bash {baseDir}/scripts/update-model.sh --primary "nanogpt/moonshotai/kimi-k2.5"
+
+# Fallbacks only
+bash {baseDir}/scripts/update-model.sh --fallbacks "nvidia_nim/moonshotai/kimi-k2.5,chutes/zai-org/GLM-5-TEE"
+
+# Primary + fallbacks
+bash {baseDir}/scripts/update-model.sh \
+  --primary "nanogpt/moonshotai/kimi-k2.5" \
+  --fallbacks "nvidia_nim/moonshotai/kimi-k2.5,chutes/zai-org/GLM-5-TEE"
+```
+
+### 5) Required Rollout Sequence (Do Not Skip)
+
+1. Update config with a schema-safe path (`agents.list[].model` for per-agent overrides).
+2. Clear per-session model pins so defaults/agent model can apply.
+3. Run model-state audit to confirm no stale references.
+4. Restart gateway so in-memory runtime state reloads config.
+5. In active channels/threads, run `/reset` (or `/new`) before testing.
+
+Use helpers:
+
+```bash
+# Clear all session model pins for an agent
+bash {baseDir}/scripts/clear-session-model-pins.sh --agent home
+
+# Clear only one channel session family
+bash {baseDir}/scripts/clear-session-model-pins.sh --agent home --channel 1470162839284224184
+
+# Audit config + cron + session pins for stale model refs
+bash {baseDir}/scripts/audit-model-state.sh "gemini-3-flash"
+```
+
+## Model ID Format
+
+- Catalog ID format: `<provider>/<model-path>`
+- Config reference format: `llm-proxy/<catalog-id>`
+
+Examples:
+- `nanogpt/moonshotai/kimi-k2.5` -> `llm-proxy/nanogpt/moonshotai/kimi-k2.5`
+- `nvidia_nim/moonshotai/kimi-k2.5` -> `llm-proxy/nvidia_nim/moonshotai/kimi-k2.5`
+
+For `/model` inside a session, use catalog IDs (without `llm-proxy/`).
+
+## Troubleshooting Quick Checks
+
+1. Model missing: rerun `list-models.sh` and validate exact ID.
+2. Old model still used: clear session pins + restart gateway + `/reset`.
+3. Unexpected fallbacks: confirm fallback chain order in `show-current.sh`.