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
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
1---2name: openclaw-troubleshooting3description: 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.4---5
6# OpenClaw Troubleshooting
7
8## Overview
9
10When handling OpenClaw-related issues, follow the workflow of "check official resources first, then determine fix status."
11
12## Workflow
13
14### Step 1: Information Gathering
15
16Confirm the following with the user (if not already provided):
17- Current OpenClaw version (`openclaw --version`)
18- Channel/platform being used (Feishu/Telegram/Discord/Slack, etc.)
19- Specific problem symptoms (error messages, frequency, reproduction steps)
20- Recent upgrades or configuration changes
21
22### Step 2: Official Documentation Search
23
24Search the official documentation for relevant content:
25- URL: https://docs.openclaw.ai
26- Search keywords: core issue terms (e.g., "feishu notification", "typing indicator", "cron job")
27
28### Step 3: GitHub Issue Search
29
30Search GitHub issues to confirm if this is a known problem:
31- Issues URL: https://github.com/openclaw/openclaw/issues?q=is%3Aissue
32- Search strategy (try in order):
33 1. Exact search: issue keywords + channel name (e.g., "feishu reaction notification")
34 2. Fuzzy search: channel name + feature module (e.g., "feishu typing")
35 3. Error message search: extract key fields from error messages
36
37### Step 4: Analyze Results and Report
38
39Reply to the user using this structure:
40
41```
42**Problem Diagnosis**
43- Symptom summary: (one sentence)
44- Related GitHub issue: #[number] (if any)
45- Fix status:
46 - Fixed: version number + upgrade recommendation
47 - Not fixed: temporary workaround + official fix progress
48 - Configuration issue: provide correct configuration example
49```
50
51### Step 5: Record and Follow Up
52
53If the issue is a known bug being fixed:
54- Inform user of the expected fix version
55- Record in todo list, remind user to verify after release
56
57## Key Resources
58
59### Quick Checklist
60
61| Issue Type | Docs Section | GitHub Search Keywords |
62|-----------|-------------|----------------------|
63| Feishu notification issues | channels/feishu | feishu notification, reaction |
64| Cron job problems | cron | cron job, schedule |
65| Channel connection failures | onboarding | [channel] connection, webhook |
66| Model invocation failures | models | [provider] error, fallback |
67| Sandbox/execution issues | sandbox | sandbox, exec, security |
68
69### CHANGELOG Check
70
71- URL: https://raw.githubusercontent.com/openclaw/openclaw/main/CHANGELOG.md
72- Purpose: Confirm whether a specific version includes a particular fix
73- Search tip: Search for issue numbers (e.g., #28660) or feature keywords in CHANGELOG
74
75## Response Template
76
77Standard reply format for users:
78
79---
80Boss, I've checked. Here's the situation:
81
82**Current version**: `x.x.x`
83**Latest available version**: `x.x.x`
84**GitHub issue**: [#number] title (if any)
85
86**Fix status**:
87- Version `x.x.x`: not fixed / fixed
88- Version `x.x.x`: includes fix (CHANGELOG reference)
89
90**Recommended solutions**:
911) Temporary workaround: (e.g., disable certain notification settings)
922) Permanent fix: (upgrade recommendation or wait for fix)
93
94Which step would you like me to help with?
95---
96
97## Notes
98
99- Prioritize the Fixes section in CHANGELOG to confirm fix versions
100- If issue status is open, the fix is still in development
101- For configuration issues, prioritize providing on-site verifiable solutions
102- Record user wait decisions (e.g., "wait for next version"), follow up proactively
modbender