--- name: search-openclaw-docs description: 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. metadata: openclaw: emoji: "📚" homepage: https://github.com/karmanverma/search-openclaw-docs requires: bins: ["node"] install: - id: "deps" kind: "npm" package: "better-sqlite3" label: "Install better-sqlite3 (SQLite bindings)" postInstall: "node scripts/docs-index.js rebuild" ---

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