OpenClaw Session Reply Debug & Model Fallback

Diagnose OpenClaw "message sent but no assistant reply" issues, then safely switch active model references with primary + multi-fallback support, including h...

Security Scan

The skill's code and instructions are consistent with its stated purpose: diagnosing OpenClaw reply failures and safely switching model references (with probe + fallback); it reads and updates local OpenClaw config/session files and probes provider endpoints using credentials already stored in openclaw.json.

Purpose & Capability

The name/description (diagnose no-reply and switch models with fallbacks) aligns with the included scripts and runbook. The scripts read openclaw.json, session caches and logs, probe provider endpoints, and rewrite model references — all actions you would expect for a model-switching/diagnostic tool.

Instruction Scope

SKILL.md explicitly instructs reading session JSONL, openclaw.json, and runtime logs, running provider probes, and invoking the provided JS scripts (dry-run vs --apply). Those instructions stay within the stated troubleshooting and switching scope; they do not request unrelated secrets or system-wide data beyond OpenClaw files and provider probes.

Install Mechanism

There is no install spec or external download; the skill is instruction-only with local JS scripts included. No packages are fetched during install, so there is no external-install risk from package downloads.

Credentials

The scripts read provider configuration (baseUrl and apiKey) from $HOME/.openclaw/openclaw.json and use that to probe model endpoints — this is proportional to probing provider availability. The package does not request additional environment variables or credentials beyond the existing OpenClaw config.

Persistence & Privilege

The skill does not force permanent inclusion (always:false). The scripts will modify local OpenClaw config and session files when run with --apply and create timestamped backups; that file-write behavior is expected for a model-switching tool. Heartbeat/cron integration is advisory and reuses OpenClaw's mechanisms rather than installing daemons.

Assessment

This skill appears coherent and does what it claims, but exercise normal caution before applying changes: 1) Run the scripts without --apply first (dry-run) to see planned edits. 2) Inspect the generated backups (.bak.<timestamp>) before overwriting. 3) Review openclaw.json and ensure provider.baseUrl is the expected upstream and you trust that endpoint — the scripts will use the apiKey stored there to perform probe requests. 4) If you plan to run via heartbeat/cron, verify the exact command the cron will run and that you want automatic periodic re-probing and potential reconfiguration. 5) Only run --apply on machines you control and have backups of your OpenClaw data if you need to be extra cautious.

OpenClaw Session Reply Debug

Use this skill when OpenClaw shows only agent identity (for example "Orchestrator") or no assistant text after /new or /reset.

Skill Package Files

• {baseDir}/SKILL.md: entry workflow for diagnosing reply failures and model switching.
• {baseDir}/openclaw-model-connectivity-test.md: mandatory runbook for model connectivity/availability validation.
• {baseDir}/scripts/switch-model-to-gpt-5.2.js: deterministic model-reference switch script.
• {baseDir}/scripts/switch-model-with-fallback.js: generic primary + fallback switch script.

When To Use

• User reports: "I sent a message but got no reply."
• Assistant rows exist but content is empty.
• Session shows repeated retries with runtime errors.
• You need to switch active model references from a preferred model to one or more ordered fallback models.
• You want OpenClaw heartbeat / cron to keep probing higher-priority models and switch back automatically when they recover.

How Users May Ask For This

Users do not need to mention the script name. Natural-language requests should be interpreted into primary + fallbacks.

Typical examples:

• OpenClaw，为我切换到 gpt-5.4，备用 gpt-5.3 和 gpt-5.2。
• 帮我把主模型设为 gpt-5.4，降级顺序 gpt-5.3 -> gpt-5.2。
• 让 heartbeat 自动探测 gpt-5.4，不可用就切到 gpt-5.3，再不行就 gpt-5.2。
• 如果 gpt-5.4 恢复可用，就自动切回最高模型。

Interpretation rule:

• gpt-5.4 => --primary gpt-5.4
• gpt-5.3, gpt-5.2 => repeated --fallback
• heartbeat 自动探测 / 自动切回 => reuse OpenClaw heartbeat / cron, do not build a custom daemon

For the example:

OpenClaw，为我切换 gpt-5.4，备用 gpt-5.3、gpt-5.2。

the effective command is:

node {baseDir}/scripts/switch-model-with-fallback.js \
  --primary gpt-5.4 \
  --fallback gpt-5.3 \
  --fallback gpt-5.2 \
  --apply

If the user only wants an emergency narrow rollback, the fixed script is still valid:

• 把 gpt-5.3 回滚到 gpt-5.2

Fast Path (3-5 minutes)

1. Resolve session key -> sessionId -> sessionFile.
2. Inspect latest assistant rows in session JSONL.
3. If stopReason=error, read errorMessage directly.
4. Check active model/provider references in config + sessions cache.
5. Apply the narrow rollback script or the generic primary/fallback script.
6. Verify with the same session.

Find This Chat's JSONL

Known session key:

rg -n '"agent:main:main"' "$HOME/.openclaw/agents/main/sessions/sessions.json" -S
node -e 'const d=require(process.env.HOME+"/.openclaw/agents/main/sessions/sessions.json"); console.log(d["agent:main:main"])'

Unknown session key:

ls -lt "$HOME/.openclaw/agents/main/sessions" | head -n 20
tail -n 80 "$HOME/.openclaw/agents/main/sessions/<candidate>.jsonl"

Evidence Checklist

Session JSONL:

tail -n 120 "$HOME/.openclaw/agents/main/sessions/<session-id>.jsonl"

Look for:

• "content":[]
• "stopReason":"error"
• "errorMessage":"..."

Model references:

rg -n "openai/gpt-5\\.3|\"model\"\\s*:\\s*\"gpt-5\\.3\"|\"primary\"\\s*:\\s*\"openai/gpt-5\\.3\"" \
  "$HOME/.openclaw/openclaw.json" \
  "$HOME/.openclaw/agents/main/sessions/sessions.json" -S

Runtime logs:

rg -n "unknown provider|Unknown provider|api key|embedded run start|agent model" \
  "$HOME/.openclaw/logs/gateway.log" \
  "$HOME/.openclaw/logs/gateway.err.log" \
  "/tmp/openclaw/openclaw-$(date +%F).log" -S

Apply Rollback To gpt-5.2

Before applying, read and execute the runbook in {baseDir}/openclaw-model-connectivity-test.md.

Dry run:

node {baseDir}/scripts/switch-model-to-gpt-5.2.js

Apply changes:

node {baseDir}/scripts/switch-model-to-gpt-5.2.js --apply

What this changes:

• Active references openai/gpt-5.3 -> openai/gpt-5.2
• Session-level bare refs gpt-5.3 -> gpt-5.2 (for keys like model)
• Keeps provider catalog entries (id/name) untouched to avoid accidental model list corruption

Apply Primary + Fallback Switching

Use the generic script when the user wants a preferred model plus ordered fallback models:

Dry run:

node {baseDir}/scripts/switch-model-with-fallback.js \
  --primary gpt-5.4 \
  --fallback gpt-5.3 \
  --fallback gpt-5.2

Apply:

node {baseDir}/scripts/switch-model-with-fallback.js \
  --primary gpt-5.4 \
  --fallback gpt-5.3 \
  --fallback gpt-5.2 \
  --apply

Behavior:

• Probe candidates in priority order on every run
• Select the first available model
• Rewrite active model references in OpenClaw config + session cache
• Preserve provider catalog id / name
• Automatically switch back to the highest-priority available model on a later run

Example:

• Current model is gpt-5.2
• A heartbeat run later finds gpt-5.4 available again
• The same command will switch active references back to gpt-5.4

Heartbeat / Cron Integration

Do not write a custom daemon for this workflow. Reuse OpenClaw's built-in heartbeat / cron, and let heartbeat trigger the existing JS script.

Recommended pattern:

1. Create a cron job with wakeMode: "next-heartbeat"
2. Put the desired priority list in the task parameters
3. Have heartbeat execute the existing JS with those parameters

Current repo support is the CLI contract, so the stable mapping is:

• task primary -> --primary
• task fallbacks[] -> repeated --fallback
• task provider -> --provider
• task probeTimeoutMs -> --probe-timeout-ms
• task apply=true -> --apply

If your current OpenClaw cron payload only supports text, pass the parameters by expanding them into the command itself:

node {baseDir}/scripts/switch-model-with-fallback.js \
  --primary gpt-5.4 \
  --fallback gpt-5.3 \
  --fallback gpt-5.2 \
  --apply

This is enough to achieve:

• automatic downgrade when gpt-5.4 is unavailable
• automatic recovery to gpt-5.4 once the next heartbeat sees it become available again

Mandatory Model Availability Validation

When switching models, this validation is required:

1. Pre-switch availability check (from runbook):
   • Validate the intended target candidates can pass Provider probe + Agent probe.
2. Apply the switch script (--apply) or the generic fallback script.
3. Post-switch availability check (from runbook):
   • Re-run Provider probe + Agent probe using the selected active model.
4. Only declare success when probes pass and session reply is non-empty.

Verify Before Claiming Fix

Send test message to the same session:

openclaw agent \
  --session-id <session-id> \
  --message "connectivity check: reply OK only" \
  --json \
  --timeout 120

Success criteria:

• Exit code 0
• "status":"ok"
• Non-empty assistant payload
• agentMeta.model is the selected target model (for example gpt-5.4, gpt-5.3, or gpt-5.2)

Notes

• Archived message hooks do not prove reply generation succeeded.
• UI can hide root cause; JSONL + logs are source of truth.
• For emergencies, the fixed gpt-5.3 -> gpt-5.2 script remains valid.
• For normal operations, prefer the generic primary/fallback script so heartbeat can downgrade and recover automatically.