A diagnostic and recovery tool for OpenClaw that automates model switching and restores assistant communication when replies fail.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install openclaw-session-reply-debug
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install openclaw-session-reply-debug using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is OpenClaw Session Reply Debug?
This skill is designed to troubleshoot and resolve the message sent but no assistant reply issue within the OpenClaw ecosystem. It provides developers with a robust framework to diagnose empty assistant rows, interpret runtime errors from JSONL session logs, and execute safe model migrations. By utilizing specialized scripts for primary and fallback model switching, it ensures high availability even when a preferred LLM provider is down.
Furthermore, this Openclaw Skills contribution integrates with the platform's native heartbeat and cron systems. This allows for automated probing of higher-priority models, enabling the agent to downgrade during outages and automatically recover to the best available model once connectivity is restored, maintaining seamless user experiences without manual intervention.
OpenClaw Session Reply Debug Use Cases
- User sends a message but the assistant remains silent or shows an empty row.
- Automatic downgrading from a preferred model to stable fallbacks during API outages.
- Automated recovery to high-priority models via heartbeat-triggered connectivity probing.
- Inspecting session JSONL files and gateway logs to identify root causes like Unknown provider or API key errors.
How OpenClaw Session Reply Debug Works
- Resolve the session key and identify the specific session file (JSONL) causing the failure.
- Inspect the latest assistant rows for stopReason: error and extract the specific errorMessage.
- Run a connectivity test via the provided model runbook to validate potential target models.
- Execute the model switch script with specific --primary and --fallback flags to update the configuration.
- Verify the fix by sending a JSON-based test message to ensure the assistant returns a valid payload and status.
OpenClaw Session Reply Debug Setup
Ensure you have the script package files in your base directory. To perform a dry run for a model switch, use:
node ./scripts/switch-model-with-fallback.js --primary gpt-5.4 --fallback gpt-5.3 --apply
To integrate with the built-in Openclaw Skills cron for auto-recovery, configure a task to execute the script with your priority list.
OpenClaw Session Reply Debug Data Schema & Taxonomy
| File Path | Description |
|---|---|
~/.openclaw/openclaw.json |
Stores active model and provider references. |
~/.openclaw/agents/main/sessions/sessions.json |
The session cache containing model metadata. |
~/.openclaw/agents/main/sessions/<id>.jsonl |
Raw session logs used for diagnosing stopReason errors. |
~/.openclaw/logs/gateway.log |
Runtime logs for identifying API and provider connectivity issues. |
OpenClaw Session Reply Debug Advanced Features
- Multi-model fallback logic: Chain multiple LLM models in an ordered priority list.
- Heartbeat recovery: Automatically switch back to the most powerful model when it becomes available.
- Deterministic rollback scripts: Fast-path scripts for emergency downgrades to specific versions.
- Config-safe updates: Modifies active references while preserving the integrity of the provider catalog.
SKILL.md
Loading
Related Openclaw Skills
arXiv Paper Reviews
A specialized tool for interacting with the arXiv Crawler API to fetch academic papers, read community reviews, and submit comments.
Buzz News Aggregator
A real-time news aggregation engine designed for Openclaw Skills that pushes market-moving updates from RSS, social media, and crypto sources to Discord and Telegram.
AVBUZZ
A high-performance query tool for retrieving real-time adult video metadata, rankings, and actress details from the FANZA GraphQL API.
Star Hotel Search
A smart hotel discovery tool for AI agents that filters accommodations by location, price, and amenities via the Star Hotel MCP.
Lessons Learned
An advanced error-learning and long-term memory system designed to prevent repeated mistakes and store user preferences for AI agents.
News Aggregator Skill
A multi-source news aggregator that fetches, filters, and analyzes real-time global trends across tech, finance, and social platforms.
Featured*
