OpenClaw Documentation Search + Config Patterns
MANDATORY before changing openclaw.json - Embedded patterns prevent silent config breakage.
Two modes:
- Embedded references (instant) - Common config patterns with anti-patterns
- Doc search (fallback) - Full OpenClaw documentation index
🚨 CRITICAL: Read AGENTS.md First
Before using this skill:
cat ~/.openclaw/skills/search-openclaw-docs/AGENTS.md
Contains:
- Mandatory workflow for config changes
- Decision tree (which reference to read)
- Critical anti-patterns overview
- When NOT to use this skill
Decision Tree
| Task | Action |
|---|---|
| Adding/removing agent bindings | Read references/config-bindings.md |
| Enabling/disabling channels | Read references/config-channel-management.md |
| Session reset tuning | Read references/config-session-reset.md |
| Heartbeat configuration | Read references/config-heartbeat.md |
| Cron job setup | Read references/config-cron.md |
| Config broke after patch | Read references/troubleshooting-config-breaks.md |
| Best practices overview | Read references/best-practices-config.md |
| Migration (2026.2.9) | Read references/migration-2026-2-9.md |
| Other config questions | Search docs (see below) |
Embedded References (8 files)
Config Patterns:
config-bindings.md- Agent routing (CRITICAL)config-channel-management.md- Enable/disable channels (CRITICAL)config-session-reset.md- Session lifetime policies (HIGH)config-heartbeat.md- Proactive monitoring (MEDIUM)config-cron.md- Scheduled tasks (MEDIUM)
Support:
troubleshooting-config-breaks.md- Fix broken configs (CRITICAL)best-practices-config.md- Safe patterns (HIGH)migration-2026-2-9.md- Version updates (MEDIUM)
Each reference contains:
- ✅ Correct pattern
- ❌ Common anti-patterns
- Why it breaks
- Examples
When to Use
| Scenario | Action |
|---|---|
Before editing openclaw.json |
✅ Read relevant reference first |
| Config changes not working | ✅ Read troubleshooting reference |
| Learning OpenClaw config | ✅ Read best practices reference |
| Personal memory/context | ❌ Use memory_search instead |
| Supabase/database work | ❌ Use supabase-postgres-best-practices |
| Next.js code patterns | ❌ Use next-best-practices |
Doc Search (Fallback)
For topics not in references, search full docs:
# Search
node ~/.openclaw/skills/search-openclaw-docs/scripts/docs-search.js "discord requireMention"
# Check index health
node ~/.openclaw/skills/search-openclaw-docs/scripts/docs-status.js
# Rebuild (after OpenClaw update)
node ~/.openclaw/skills/search-openclaw-docs/scripts/docs-index.js rebuild
Usage Examples
# Config question
node scripts/docs-search.js "discord requireMention"
# Troubleshooting
node scripts/docs-search.js "webhook not working"
# More results
node scripts/docs-search.js "providers" --top=5
# JSON output
node scripts/docs-search.js "heartbeat" --json
Output Format
🔍 Query: discord only respond when mentioned
🎯 Best match:
channels/discord.md
"Discord (Bot API)"
Keywords: discord, requiremention
Score: 0.70
📄 Also relevant:
concepts/groups.md (0.66)
💡 Read with:
cat /usr/lib/node_modules/openclaw/docs/channels/discord.md
How It Works
- FTS5 keyword matching on titles, headers, config keys
- Handles camelCase terms like
requireMention - Porter stemming for flexible matching
- No network calls - fully offline
Index Location
- Index:
~/.openclaw/docs-index/openclaw-docs.sqlite - Docs:
/usr/lib/node_modules/openclaw/docs/
Index is built locally from your OpenClaw version.
Troubleshooting
No results / wrong results
# 1. Check index exists
node scripts/docs-status.js
# 2. Rebuild if stale
node scripts/docs-index.js rebuild
# 3. Try exact config terms (camelCase matters)
node scripts/docs-search.js "requireMention"
# 4. Try broader terms
node scripts/docs-search.js "discord"
Integration
const { search } = require('./lib/search');
const INDEX = process.env.HOME + '/.openclaw/docs-index/openclaw-docs.sqlite';
const results = await search(INDEX, "discord webhook");
// results[0].path → full path to read