openclaw-model-switch

Switch and repair OpenClaw gateway model configurations by editing openclaw.json with backup and verification.

1.4k|216|Updated Oct 22, 2025
One-click install
npx skills add https://github.com/daymade/claude-code-skills --skill openclaw-model-switch
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: openclaw-model-switch
Source: https://github.com/daymade/claude-code-skills/tree/main/openclaw-model-switch
Command: npx skills add https://github.com/daymade/claude-code-skills --skill openclaw-model-switch

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

Switching or upgrading the model on an OpenClaw instance often fails in confusing ways: 401 "Invalid token" errors despite valid keys, "No available channel" errors, thinking-level rejections, or config edits that silently never take effect. This Skill diagnoses the real cause before editing and safely switches the model configuration.

Core Features & Use Cases

  • Safe model switching: A Python script discovers all openclaw.json config locations, backs them up, adds known model definitions (k3, k2p6, kimi-k2.7-code), updates the default model, syncs mirror configs, and restarts the gateway.
  • Diagnosis-first troubleshooting: A trap catalog covers env-var API key hijacking, provider-plugin thinking-level restrictions, relay group/network availability, and wrong-file edits, with probe commands to prove each cause.
  • End-to-end verification: Mandatory real agent-turn verification checks for fallback usage so a masked failure is never mistaken for success.
  • Use Case: Your OpenClaw bot falls back or errors on LLM calls after you tried upgrading from k2p6 to k3. The Skill probes the endpoint, finds that an env KIMI_API_KEY is hijacking the wire key, fixes the config, and verifies a clean agent turn.

Quick Start

Ask the assistant to switch the OpenClaw default model to k3 and restart the gateway, then verify the change with a real agent turn.

Frequently Asked Questions about openclaw-model-switch

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I switch the default model on an OpenClaw gateway?

Run the switch-model.py script with the target model id, for example python3 scripts/switch-model.py k3 --restart. It discovers all openclaw.json locations, backs them up, adds the model definition if known, updates agents.defaults.model.primary, syncs mirrors, and restarts the gateway.

Why does OpenClaw return 401 Invalid token when my API key works in curl?

A non-empty environment variable such as KIMI_API_KEY overrides the provider apiKey on the wire, so the gateway sends a different key than the one you configured. Empty the hijacking env var in the config env block or use a custom provider id that the secrets registry does not map.

How do I fix Thinking level not supported errors on OpenClaw?

The provider plugin hardcodes a binary off/on thinking profile that overrides model definitions. Move the model to a custom provider id the plugin does not claim, or set params.canonicalModelId to a model family whose profile includes the level you need, then probe the exact thinking payload.

Why did my openclaw.json edit not take effect after restart?

Multiple openclaw.json files can exist as mirrors, and editing only one gets overwritten by the next sync. Run openclaw gateway status to find the live config path, edit all mirror copies identically, and confirm a new gateway pid after restart.

Can I trust the /v1/models listing to check model availability on a relay?

No. On new-api style relays the listing is frequently incomplete, and availability depends on token group and network. Probe with a real POST completion request from the host that will run the bot; a 200 response is the only reliable test.