OpenClaw Docs Search + Config Patterns

MANDATORY before any openclaw.json changes. Prevents config breakage via embedded anti-patterns and correct patterns. Use when configuring OpenClaw (bindings, channels, sessions, cron, heartbeat) or troubleshooting config issues.

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