OpenClaw Troubleshooting

---
name: openclaw-troubleshooting
description: "When users encounter OpenClaw-related issues or errors, search official docs and GitHub issues first, then provide solutions. Use for: feature malfunctions, error troubleshooting, version upgrade advice, configuration questions, and known issue verification."
---

# OpenClaw Troubleshooting

## Overview

When handling OpenClaw-related issues, follow the workflow of "check official resources first, then determine fix status."

## Workflow

### Step 1: Information Gathering

Confirm the following with the user (if not already provided):
- Current OpenClaw version (`openclaw --version`)
- Channel/platform being used (Feishu/Telegram/Discord/Slack, etc.)
- Specific problem symptoms (error messages, frequency, reproduction steps)
- Recent upgrades or configuration changes

### Step 2: Official Documentation Search

Search the official documentation for relevant content:
- URL: https://docs.openclaw.ai
- Search keywords: core issue terms (e.g., "feishu notification", "typing indicator", "cron job")

### Step 3: GitHub Issue Search

Search GitHub issues to confirm if this is a known problem:
- Issues URL: https://github.com/openclaw/openclaw/issues?q=is%3Aissue
- Search strategy (try in order):
  1. Exact search: issue keywords + channel name (e.g., "feishu reaction notification")
  2. Fuzzy search: channel name + feature module (e.g., "feishu typing")
  3. Error message search: extract key fields from error messages

### Step 4: Analyze Results and Report

Reply to the user using this structure:

```
**Problem Diagnosis**
- Symptom summary: (one sentence)
- Related GitHub issue: #[number] (if any)
- Fix status:
  - Fixed: version number + upgrade recommendation
  - Not fixed: temporary workaround + official fix progress
  - Configuration issue: provide correct configuration example
```

### Step 5: Record and Follow Up

If the issue is a known bug being fixed:
- Inform user of the expected fix version
- Record in todo list, remind user to verify after release

## Key Resources

### Quick Checklist

| Issue Type | Docs Section | GitHub Search Keywords |
|-----------|-------------|----------------------|
| Feishu notification issues | channels/feishu | feishu notification, reaction |
| Cron job problems | cron | cron job, schedule |
| Channel connection failures | onboarding | [channel] connection, webhook |
| Model invocation failures | models | [provider] error, fallback |
| Sandbox/execution issues | sandbox | sandbox, exec, security |

### CHANGELOG Check

- URL: https://raw.githubusercontent.com/openclaw/openclaw/main/CHANGELOG.md
- Purpose: Confirm whether a specific version includes a particular fix
- Search tip: Search for issue numbers (e.g., #28660) or feature keywords in CHANGELOG

## Response Template

Standard reply format for users:

---
Boss, I've checked. Here's the situation:

**Current version**: `x.x.x`
**Latest available version**: `x.x.x`
**GitHub issue**: [#number] title (if any)

**Fix status**:
- Version `x.x.x`: not fixed / fixed
- Version `x.x.x`: includes fix (CHANGELOG reference)

**Recommended solutions**:
1) Temporary workaround: (e.g., disable certain notification settings)
2) Permanent fix: (upgrade recommendation or wait for fix)

Which step would you like me to help with?
---

## Notes

- Prioritize the Fixes section in CHANGELOG to confirm fix versions
- If issue status is open, the fix is still in development
- For configuration issues, prioritize providing on-site verifiable solutions
- Record user wait decisions (e.g., "wait for next version"), follow up proactively