Model Configuration

Everything about configuring models in OpenClaw — providers, routing, sessions, and cron pinning. Learned the hard way through many errors.

Provider setup

Adding a provider

Edit openclaw.json:

{
  "providers": {
    "deepseek": {
      "apiKey": "sk-...",
      "baseUrl": "https://api.deepseek.com"
    }
  }
}

If using API key from file: reference env var or key file. Direct env var injection via ~/.openclaw/openclaw.json.

Never restart gateway and immediately assume the model is live. Check after restart.

Checking what model is active

openclaw status           # shows current model
session_status            # shows session-level model

Provider priority

If multiple providers offer the same model, Gateway resolves via: plugin providers > config providers > default fallback chain. A DeepSeek plugin can sit alongside a MiniMax config provider — the plugin wins if enabled.

The session model lock (most common mistake)

The trap: When you change the default model in config, the current Telegram session stays locked to its birth model — the model that was default when the session was created.

Session created at 18:05 → model = MiniMax (was default)
Gateway restarted at 18:06 → config now says DeepSeek
Session at 18:07 → STILL MiniMax ← TRAP
New session created at 18:08 → DeepSeek ← Correct

The fix:

• Existing sessions keep their model until the session expires or is reset
• /model <provider/model> — force-switches the current session immediately
• For Telegram: sending a message to a brand new session (or after session expiry) picks up the current default
• Closing and reopening a Telegram chat does NOT reset the session (Telegram chats can't be "closed")

Lesson: After changing model config, either:

1. Send /model deepseek/deepseek-v4-flash to switch running session
2. Wait for session to expire naturally (~24h inactivity)
3. Accept that cron sessions (always new) will use new config immediately

Cron model pinning (second most common mistake)

Time-sensitive cron jobs MUST pin the model explicitly. The global default can get stuck on model cold-start resolution (MiniMax especially bad — up to 300s delay).

{
  "payload": {
    "kind": "agentTurn",
    "message": "...",
    "timeoutSeconds": 600,
    "model": "deepseek/deepseek-v4-flash"
  }
}

Crons that ALWAYS need pinning:

Crons that don't need pinning:

• Dashboard regeneration, token tracker, backup, security audit — delay is harmless

Failure symptom: lastDiagnostics.summary = "cron: job execution timed out (last phase: model-call-started)". Fix: pin model.

dmScope (multi-agent routing)

In multi-agent setups (Patch + Muthu), messages can route to the wrong agent's session unless dmScope is set correctly:

{
  "telegram": {
    "dmScope": "per-channel-peer-account"
  }
}

per-channel-peer-account — each Telegram bot + user combo gets its own session. Without this, messages from both bots could land in the same session.

Symptom of wrong dmScope: Hobo messages Patch but Muthu's session receives them, or vice versa.

Plugins vs config providers

• Plugins (installed via ClawHub or openclaw): can introduce new model providers
• Config providers (in openclaw.json): directly configured API endpoints
• Both can coexist. Plugin providers take priority over config providers for same model.

To check loaded providers:

openclaw plugin list | grep -i model
grep -A5 '"providers"' ~/.openclaw/openclaw.json

Model switching during session

Safety checklist (when changing models)

1. Edit openclaw.json → add/change provider + model
2. Restart gateway: openclaw gateway restart
3. CHECK: openclaw status — confirms the new model is live
4. CHECK: Send a test message — verify which model responds
5. If wrong model responds → /model <correct/provider/model>
6. Update cron pinning for any time-sensitive crons
7. Verify cron test runs pick up the new model (check lastRunStatus)