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.

Security Scan

This skill is internally consistent with its stated purpose: an offline OpenClaw docs search and reference helper that reads local docs and builds a local SQLite index — it does not request credentials or make network calls.

Purpose & Capability

The name/description (OpenClaw docs search + config patterns) match the code and instructions: Node scripts and libs build/query a local FTS5 SQLite index of OpenClaw docs and ship embedded reference files. Required binary is 'node', and the only dependency is better-sqlite3 (an SQLite binding) — all proportional to a local docs search tool.

Instruction Scope

SKILL.md restricts runtime actions to local tasks: reading AGENTS.md, running scripts (docs-search.js, docs-index.js, docs-status.js), and reading local doc files (e.g., /usr/lib/node_modules/openclaw/docs/ and files under ~/.openclaw). It explicitly claims 'No network calls - fully offline.' There are no instructions to read unrelated secrets or to transmit data externally.

Install Mechanism

Registry had no formal install spec, but SKILL.md and package.json instruct installing the native npm dependency better-sqlite3 and running a local index rebuild. Using better-sqlite3 is expected for a local SQLite index but requires native build tools on some systems. The installation approach is local (npm) and does not download arbitrary archives or call remote URLs beyond the repo URL in metadata.

Credentials

The skill requires no environment variables, no credentials, and no config paths beyond local locations (HOME-based index and system docs path). Access to ~/.openclaw and /usr/lib/node_modules/openclaw/docs/ is necessary for its function and is proportionate to the stated purpose.

Persistence & Privilege

Skill flags are default (always:false, user-invocable, model invocation allowed). It does not request permanent/always-on presence and does not modify other skills or system-wide agent settings by itself. It recommends optional triggers and adding workflow text to AGENTS.md, which are benign and user-controlled.

Assessment

This skill appears to do what it claims: offline indexing/search of OpenClaw docs and bundled reference files. Before installing or running the scripts: 1) Inspect the scripts (they run locally and read files under your home directory and system docs path). 2) Be prepared to run npm install (better-sqlite3 is a native module and may require build tools). 3) The skill will create a local SQLite index at ~/.openclaw/docs-index/openclaw-docs.sqlite — ensure you are comfortable with it writing there. 4) No credentials or network access are requested, but if you plan to add the skill as a trigger in openclaw.json or follow its post-install suggestions, review those changes before applying. 5) Note a minor incongruence: the registry shows no automated install spec even though SKILL.md/package.json expect an npm install — remember to run the install steps manually or via your normal package workflow.

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