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):
- Exact search: issue keywords + channel name (e.g., "feishu reaction notification")
- Fuzzy search: channel name + feature module (e.g., "feishu typing")
- 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:
- Temporary workaround: (e.g., disable certain notification settings)
- 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