openclaw-ops/skills/model-selector/SKILL.md

name, description

name	description
model-selector	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 {baseDir}/scripts/list-models.sh
bash {baseDir}/scripts/list-models.sh --providers

2) Validate Candidate IDs

bash {baseDir}/scripts/validate-model.sh "nvidia_nim/moonshotai/kimi-k2.5"

3) Inspect Current Configuration

bash {baseDir}/scripts/show-current.sh

4) Apply Backend Model Changes

Preferred (comprehensive) flow:

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):

# 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:

# 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.