Model Config

Configure and troubleshoot OpenClaw model providers, routing, session model locks, cron model pinning, and provider switching. Lessons from real failures.

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:

Cron	Why
Expense check-ins (10am, 1:30pm, 10pm)	Time-sensitive, Hobo waits for them
Expense sync (9:30am)	Must run on schedule
News briefings (7:30am, 3pm, 10pm)	Hobo expects them on time
Investment check-in (Sat 10am)	Weekly, must fire
Investment sync (Sat 11am)	Same
Transport check-in (9am)	Previous-day ask

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

Method	Scope	Persistence
/model deepseek/deepseek-v4-flash	Current session only	Until session expires
Change "model" in openclaw.json	All new sessions	Permanent (requires gateway restart)
Pin "model" in cron payload	That cron only	Permanent until changed

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)