2026 OpenClaw Multi-Model Routing & Degradation Chains: Channel/Task Shunting, 429 vs Timeout Fail-over on ZoneMac Remote Physical Mac (openclaw.json + FAQ)

2. Pain points

1. Limits hidden behind “one model for everyone.” Sharing one expensive model across channels turns peak-hour 429s into a full outage; interactive vs batch and internal vs external traffic should use different profiles and concurrency budgets.
2. Hidden cost when 429 and timeouts are conflated. 429 needs Retry-After and quota respect; read timeouts or TLS failures fit fallback hops or higher stream-idle limits—one generic “retry three times” policy both slows the queue and obscures root cause.
3. Stability and auditability of config. On a remote physical Mac, unreviewed edits to openclaw.json can break the default profile or desync fallback order from finance’s cost model. Name profiles, document primary/secondary order, and assign owners in the runbook.

3. Decision matrix: dimensions × strategy

Sign off on this table before rollout; left column is the tempting shortcut, right column is a sane baseline.

4. Reproducible openclaw.json snippets

The following is illustrative structure: keys must match your OpenClaw version docs; merge into an existing file without overwriting production-only paths (channels, credential references) and always keep a backup.

4.1 Router profiles, channels, and task tags

{
  "gateway": {
    "router": {
      "defaultProfile": "balanced",
      "profiles": {
        "fast": {
          "primaryModel": "gpt-4o-mini",
          "fallbackChain": ["claude-3-5-haiku", "local-qwen-14b"]
        },
        "balanced": {
          "primaryModel": "gpt-4.1",
          "fallbackChain": ["gpt-4o", "gpt-4o-mini"]
        },
        "quality": {
          "primaryModel": "gpt-4.1",
          "fallbackChain": ["claude-3-5-sonnet", "gpt-4o"]
        }
      },
      "routeByChannel": {
        "telegram": { "profile": "fast" },
        "slack_public": { "profile": "balanced" },
        "api_internal": { "profile": "quality" }
      },
      "routeByTaskTag": {
        "ci": { "profile": "fast" },
        "support": { "profile": "quality" },
        "ops_summary": { "profile": "balanced" }
      }
    }
  }
}

4.2 Upstream retries, 429, and timeouts

{
  "gateway": {
    "upstream": {
      "http": {
        "maxRetries": 4,
        "retryOnStatus": [408, 409, 425, 429, 500, 502, 503, 504],
        "respectRetryAfter": true,
        "backoff": { "baseMs": 400, "maxMs": 8000, "jitter": 0.2 }
      },
      "circuitBreaker": {
        "errorRateThreshold": 0.35,
        "minSampleSize": 40,
        "openDurationMs": 60000
      },
      "timeouts": {
        "connectMs": 8000,
        "requestMs": 180000,
        "streamIdleMs": 240000
      },
      "failover": {
        "onTimeout": "nextInFallbackChain",
        "on429": "retryWithBackoffThenFallback",
        "maxFallbackHops": 3
      }
    }
  }
}

streamIdleMs covers long gaps between tokens in streaming mode; keeping on429 and onTimeout in separate blocks lets you build separate SLOs in logs and dashboards—export matching counters into Prometheus or Grafana and alert on fallback depth versus 429 rate separately.

5. Seven-step runbook (remote physical Mac)

1. Freeze traffic dimensions. Align with product and ops on channel IDs and task-tag enums; remove unnamed defaults so traffic does not silently fall back to balanced.
2. Back up JSON. cp openclaw.json openclaw.json.bak.$(date +%Y%m%d%H%M); attach the diff to the ticket.
3. Merge router blocks. Add profiles and fallbackChain first, then routeByChannel / routeByTaskTag.
4. Local golden request. For each profile, run a fixed curl (or tiny SDK script) against 127.0.0.1, record model ID and latency.
5. Inject two fault classes. With a mock or throttle, return 429 and separately stretch time-to-first-byte; 429 should backoff without burning through the whole chain in three tries, while timeouts should advance along the chain.
6. Wire observability. Export at least: requests per profile, 429 rate, fallback depth distribution, read-timeout rate—match panel thresholds to your Prometheus/Grafana runbook.
7. Archive and review. Check in JSON snippets, golden commands, and rollback (restore bak + reload) beside internal docs.

6. 429 vs timeout fail-over triage

7. Quotable numbers (for runbooks)

• Backoff start: baseMs: 400 and maxMs: 8000 as a first-pass magnitude for 429; reconcile with commercial QPS caps.
• Stream idle: streamIdleMs: 240000 (four minutes) suits long answers; shorter values favor snappy interactive chat.
• Fallback cap: maxFallbackHops: 3 avoids latency explosions; beyond that return an explicit error payload and page.

8. FAQ

9. Summary and node choice

Multi-model routing moves cost, latency, and availability from ad-hoc firefighting into an auditable contract: channels and tasks select profiles, 429 and timeouts use different fail-over semantics, and ordered chains give a deterministic last resort when upstreams shake.

Running the gateway on a ZoneMac remote physical Mac pins that path on a long-lived, low-jitter Unix host: native Terminal and SSH, launchd supervision, and alignment with the macOS toolchain reduce environment drift that shows up as mystery timeouts. Apple Silicon unified memory also makes a local backup small model more practical on-box. A Mac mini M4—with roughly 4W idle draw, quiet operation, and stable macOS—is a strong 7×24 gateway footprint; Gatekeeper and SIP also ease operating an exposed service surface.

If you want this routing stack on predictable hardware with minimal ops drag, Mac mini M4 is one of the best price/performance starting points—get a remote physical Mac through ZoneMac and land multi-model traffic on a reproducible gateway config.