OpenClaw Docs Search + Config Patterns
by @karmanverma
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.
clawhub install search-openclaw-docsπ About This Skill
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:
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:
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.jsRebuild (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=5JSON 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
requireMentionIndex Location
~/.openclaw/docs-index/openclaw-docs.sqlite/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.js2. Rebuild if stale
node scripts/docs-index.js rebuild3. 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
β‘ When to Use
π Tips & Best Practices
No results / wrong results
# 1. Check index exists
node scripts/docs-status.js2. Rebuild if stale
node scripts/docs-index.js rebuild3. Try exact config terms (camelCase matters)
node scripts/docs-search.js "requireMention"4. Try broader terms
node scripts/docs-search.js "discord"