🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
πŸ¦€ ClawHub

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.

Versionv1.1.0
Downloads1,635
Installs3
TERMINAL
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:

  • 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

    ⚑ When to Use

    TriggerAction
    |----------|--------|
    | 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` |
    ---

    πŸ“‹ Tips & Best Practices

    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"