Model Switchboard

Safely configure OpenClaw AI models by validating roles, autoloading backups, blocking unsafe changes, and managing via CLI or Canvas UI.

Security Scan

The skill's files, runtime instructions, and required access are coherent with its stated purpose (safe model management) — notable high-severity issues were reported in the audit but the changelog claims they were fixed; I could not fully verify every fix because some files were truncated in the submission.

Purpose & Capability

Name/description match the code and SKILL.md: the bundle contains a validation engine, CLI wrapper, redundancy generator, UI, model registry and setup script. Files access the OpenClaw config (~/.openclaw/openclaw.json) and provider auth artifacts — expected for a model-management tool. No unrelated cloud creds or unrelated binaries are requested.

Instruction Scope

SKILL.md confines runtime actions to model validation, backups, uses the OpenClaw CLI and the provided switchboard.sh/ui. It explicitly forbids direct editing of openclaw.json and prescribes dry-runs and confirmations. The SKILL.md does suggest editing model-registry.json to add new models (this changes the skill bundle's data), which is within the tool's domain but worth noting as it requires modifying shipped files.

Install Mechanism

No install spec / no external downloads. This is instruction-first with bundled scripts (Python + Bash + HTML). That lowers install-time risk compared to fetching remote archives. No evidence of remote code pulls or unusual installers in included files.

Credentials

The skill itself declares no required env vars; at runtime it conditionally reads provider API keys and OpenClaw auth files (ANTHROPIC_API_KEY, OPENAI_API_KEY, ~/.openclaw/auth/*) to detect available providers — this is proportional to model/provider discovery and redundancy features. It does read/write the user's OpenClaw config and creates backups under ~/.openclaw — expected for this purpose.

Persistence & Privilege

No 'always: true' privilege. The skill reads/writes user-level config (~/.openclaw/openclaw.json and backups) and runs a UI server locally; these are appropriate for a model-management tool. It does not request system-wide privileges or modify other skills' configs in the provided excerpts.

Scan Findings in Context

[H-1_XSS_innerHTML] unexpected: Audit found severe XSS in ui/index.html where innerHTML was used with an inadequate esc() function; the CHANGELOG claims this was fixed (replaced with safe DOM APIs). A UI that renders model/provider names must be XSS-safe; if fixes are present this finding should be resolved — verify the UI uses textContent/createElement and no inline onclick string interpolation before deployment.

[H-2_Shell_injection_import_config] unexpected: Audit reported shell interpolation of a CLI argument into inline Python (import_config) enabling code injection. The CHANGELOG claims the pattern was replaced by passing file paths via environment variables. Confirm switchboard.sh's import path uses environment-variable passing (SWITCHBOARD_IMPORT_FILE) rather than direct shell interpolation before trusting imports.

[M-1_Cron_model_validation_missing] unexpected: Audit flagged absence of cron-job model validation. The SKILL.md and CHANGELOG claim a new validate-cron-models command was added. This validation is important for the tool's safety guarantees; confirm the validate-cron-models implementation is present and exercised (unit/functional test) if you rely on automated cron validation.

[M-3_Backup_pruning_race] unexpected: Audit pointed out a race in backup pruning (ls/tail/xargs rm). CHANGELOG says flock-based locking was added. Backups and rollback are central to the tool's promise; verify locking exists in the live switchboard.sh and test concurrent operations.

Assessment

This skill appears coherent and appropriate for managing OpenClaw models: it only needs access to your OpenClaw config and any provider API keys you already use, and it implements validation, backups and a UI. However, the included security audit flagged two HIGH issues (XSS in the UI and a shell-injection vector in the import flow). The changelog states those issues were fixed, but some files in the submission were truncated so I could not fully verify every fix. Before installing or enabling this skill in production: 1) Inspect switchboard.sh (import_config) to ensure file paths are passed via environment variables (no unescaped shell interpolation). 2) Open ui/index.html and confirm user/model strings are rendered using textContent/createElement (no innerHTML with unescaped values or inline onclick string interpolation). 3) Run the tool in a non-production environment, exercise import/export and UI flows, and confirm backups and rollback work as advertised. 4) If you must trust it in production, run a local security test (attempt model names with special characters, simulate concurrent operations) and ensure backup directory permissions and lockfiles are present. If you want, I can (a) search the provided switchboard.sh and ui files for the exact patterns and report lines that still look risky, or (b) provide a short checklist of commands/tests to run to validate the fixes on your machine.

Model Switchboard v3.0 — Safe AI Model Configuration for OpenClaw

⛔ HARD RULE: NEVER edit openclaw.json model fields directly. Always use this skill's commands. No exceptions. Ever.

Why This Exists

Editing openclaw.json directly for model changes is the #1 cause of OpenClaw gateway crashes. Wrong model type in wrong slot = instant death. No backup = hours rebuilding. This skill eliminates that entirely.

How It Works

1. Validates model format and role compatibility before any change
2. Auto-backs up config before every modification (30 rolling backups)
3. Uses OpenClaw CLI (openclaw models set) — never raw JSON
4. Blocks unsafe assignments (image-gen model as primary LLM = blocked)
5. Instant rollback if anything goes wrong
6. Canvas UI for visual model management

Quick Reference

SWITCHBOARD="$SKILL_DIR/scripts/switchboard.sh"

# View current setup
$SWITCHBOARD status

# Change models
$SWITCHBOARD set-primary "anthropic/claude-opus-4-6"
$SWITCHBOARD set-image "google/gemini-3-pro-preview"
$SWITCHBOARD add-fallback "openai/gpt-5.2"
$SWITCHBOARD remove-fallback "openai/gpt-5.2"
$SWITCHBOARD add-image-fallback "openai/gpt-5.1"

# Preview before applying
$SWITCHBOARD dry-run set-primary "openai/gpt-5.2"

# Discovery & recommendations
$SWITCHBOARD discover          # List all available models
$SWITCHBOARD recommend         # Get optimal suggestions

# Redundancy (3-deep failover)
$SWITCHBOARD redundancy        # Assess current redundancy
$SWITCHBOARD redundancy-deploy # Preview optimal config
$SWITCHBOARD redundancy-apply  # Apply optimal config
$SWITCHBOARD redundancy-apply 4  # Custom depth

# Backup & restore
$SWITCHBOARD backup            # Manual backup
$SWITCHBOARD list-backups      # Show all backups
$SWITCHBOARD restore latest    # Undo last change

# Import/Export (portable model configs)
$SWITCHBOARD export config.json
$SWITCHBOARD import config.json

# Cron model validation
$SWITCHBOARD validate-cron-models  # Check cron jobs use valid models

# Diagnostics
$SWITCHBOARD health            # Gateway + provider status
$SWITCHBOARD validate <model> <role>  # Test compatibility

Model Roles

Role	Purpose	Config Key
Primary	Main LLM for all conversations	agents.defaults.model.primary
Fallback	Ordered backup LLMs	agents.defaults.model.fallbacks
Image	Vision/image processing	agents.defaults.imageModel.primary
Image Fallback	Backup vision models	agents.defaults.imageModel.fallbacks
Heartbeat	Low-cost polling model	agents.defaults.heartbeat.model
Coding	Sub-agent code generation	Spawn-time model param

Validation Rules

The validation engine (scripts/validate.py) enforces:

• Format: Must be provider/model-name (e.g., anthropic/claude-opus-4-6)
• Capability match: LLM roles require llm + tools capabilities
• Image roles: Require vision capability
• Hard blocks: Image-generation-only models (DALL-E, Stability) blocked from ALL LLM roles
• Registry warnings: Unknown models get a caution warning but are allowed (for OpenRouter/new models)

Known Providers

• anthropic — Claude family (Opus, Sonnet, Haiku)
• openai — GPT family
• openai-codex — Codex OAuth models
• google — Gemini family
• opencode — Zen proxy (routes to various models)
• zai — GLM family
• xai — Grok family
• openrouter — Multi-provider gateway
• groq, cerebras — Fast inference

Canvas UI

To show the visual dashboard:

# Get UI data
DATA=$($SWITCHBOARD ui)

# Present via canvas
# The UI reads window.__switchboardData JSON

The Canvas UI at ui/index.html shows:

• Primary LLM and Image model with color coding
• Fallback chains (ordered)
• Provider auth status (green/red indicators)
• Model allowlist
• Config issues with severity levels
• Backup count

For Agents: Operating Protocol

When a user asks to change model assignments:

1. Read this SKILL.md first
2. Show current status: $SWITCHBOARD status
3. Preview the change: $SWITCHBOARD dry-run <action> <model>
4. Confirm with user before applying
5. Apply: $SWITCHBOARD <action> <model>
6. Verify: Check gateway health after change

NEVER:

• Edit openclaw.json directly for model fields
• Skip the dry-run for primary model changes
• Apply without user confirmation
• Ignore validation failures

Troubleshooting

Gateway won't start:

$SWITCHBOARD restore latest
openclaw gateway restart
# Or: openclaw doctor --fix

"Model is not allowed" error: Model isn't in the allowlist. Add it or clear the list:

openclaw config set 'agents.defaults.models."provider/model"' '{"alias":"Name"}'
# Or clear: openclaw config unset agents.defaults.models

Unknown model warning: The model isn't in model-registry.json. Add it for future validation:

# Edit model-registry.json to add the model entry

File Structure

model-switchboard/
├── SKILL.md              # This file — agent instructions
├── README.md             # ClawHub publishing readme
├── model-registry.json   # Known model capabilities database
├── scripts/
│   ├── switchboard.sh    # Main CLI tool (bash)
│   └── validate.py       # Validation engine (python3, no deps)
└── ui/
    └── index.html        # Canvas dashboard (single-file, no deps)