OpenClaw Documentation Search + Config Patterns

MANDATORY before changing openclaw.json - Embedded patterns prevent silent config breakage.

Two modes: 1. Embedded references (instant) - Common config patterns with anti-patterns 2. 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