Smart Finder

Scope

Primary Commands

# Natural language discovery (main interface)
openclaw smart-finder find "natural language query" [OPTIONS]

# Pattern-based search with AI enhancement
openclaw smart-finder pattern "<regex/pattern>" --context=10 [--type=js|py|sh|yaml|json]

# Smart listing by category
openclaw smart-finder list --category=commands|configs|scripts|workflows|all

# Contextual analysis of a file/directory
openclaw smart-finder analyze PATH [--deep] [--related] [--dependencies]

# Intelligent suggestions based on current context
openclaw smart-finder suggest --from=FILE [--task="description"]

# Build/refresh the semantic index
openclaw smart-finder index --rebuild [--path=DIR] [--exclude=PATTERN]

# History-based command recovery
openclaw smart-finder history "partial command" [--last-hours=24]

# Configuration audit
openclaw smart-finder audit --type=secrets|credentials|tokens [--severity=high|medium|low]

Command Flags

--type, -t        Filter by file type (js,ts,py,sh,bash,yaml,yml,json,env,md)
--path, -p        Search within specific directory (default: workspace root)
--exclude, -e     Exclude patterns (comma-separated globs)
--context, -c     Show N lines of context around matches (default: 3)
--limit, -l       Maximum results to return (default: 20)
--format, -f      Output format: text|json|yaml|table (default: text)
--confidence, -C  Minimum AI confidence score 0.0-1.0 (default: 0.7)
--explain, -x     Include AI-generated explanations for each result
--dry-run         Show what would be searched without executing
--verbose, -v     Detailed logging
--quiet, -q       Suppress non-essential output

Work Process

1. Index Building (Initial/Background)

# Build initial semantic index
openclaw smart-finder index --rebuild --path=~/projects --exclude=node_modules,.git,dist

# Incremental update (runs automatically every 6 hours via cron)
openclaw smart-finder index --incremental

# Check index status
openclaw smart-finder index --status

Index stores:

• File metadata (path, size, modified time, type)
• Embeddings from AI analysis of content
• Symbol/function/class definitions
• Import/require relationships
• Configuration keys and values (masked secrets)
• Command patterns and usage contexts

2. Query Processing

When user runs: openclaw smart-finder find "docker compose file with postgres and redis":

1. Query is sent to AI engine for semantic parsing
2. Extracts key concepts: ["docker", "compose", "postgres", "redis"]
3. Searches index for files matching semantic similarity > 0.7
4. Falls back to pattern matching if AI confidence < 0.5
5. Ranks results by:
   • Semantic relevance (40%)
   • File type priority (yaml > json > env > md) (25%)
   • Recency (20%)
   • Usage frequency (15%)
6. Returns ranked list with confidence scores

3. Result Presentation

# Default output with explanations
$ openclaw smart-finder find "puppeteer launch options" --explain

[1] scripts/scraper.js (Confidence: 0.92)
    const browser = await puppeteer.launch({
      headless: true,
      args: ['--no-sandbox', '--disable-setuid-sandbox']
    });
    → This file uses puppeteer.launch() with standard headless configuration

[2] tests/puppeteer.test.js (Confidence: 0.87)
    await page.setViewport({ width: 1280, height: 800 });
    → Contains puppeteer viewport configuration examples

[3] docs/scraping-guide.md (Confidence: 0.81)
    ## Launch Options
    - `headless: false` for debugging
    - `slowMo: 50` to slow down operations
    → Documentation listing common launch options

4. Contextual Analysis

# Deep analysis of an automation script
$ openclaw smart-finder analyze scripts/deploy.sh --deep --related

File: scripts/deploy.sh (127 lines)
Type: bash script
Purpose: Production deployment automation

Dependencies:
  - Uses aws-cli (configured in ~/.aws/credentials)
  - References docker-compose.yml (2 direct dependencies)
  - Calls scripts/backup-db.sh (1 dependency)

Related files:
  - infra/docker-compose.yml (used by)
  - config/production.env (sourced)
  - .github/workflows/deploy.yml (triggers this script)

Configuration values found:
  - AWS_REGION=us-east-1
  - DOCKER_REGISTRY=registry.example.com
  - ENVIRONMENT=production

Potential issues:
  - Hardcoded AWS region (consider making configurable)
  - No error handling on docker-compose failure

Golden Rules

1. Security First: Automatically redact/mask secrets, tokens, passwords, private keys from results unless explicitly overridden with --show-secrets (requires admin role)
2. Workspace Isolation: Never search outside configured roots (default: ~/projects, ~/.openclaw). Override requires --allow-escape flag
3. Index Freshness: Index must be refreshed after major code changes. Auto-refresh checks every 6h, but manual index --rebuild recommended after batch changes
4. Respect VCS: Honor .gitignore patterns. Never index ignored files even with --force
5. Resource Limits: Max file size for indexing: 10MB. Max total index size: 5GB. Prune old entries automatically
6. AI Privacy: In cloud mode, queries are anonymized. Never send raw file contents to AI - use embeddings only
7. Result Limiting: Default 20 results, max 200 with --limit. Prevent memory exhaustion
8. Error Transparency: If AI service unavailable, fall back to ripgrep with warning. Never fail silently
9. Audit Trail: All queries logged to ~/.openclaw/logs/smart-finder-audit.log with user, timestamp, query, result count
10. Performance SLA: Queries return within 5s for <100k files, 10s for <1M files. Timeout after 30s

Examples

Example 1: Finding Configuration Values

$ openclaw smart-finder find "MongoDB connection string" --type=env

config/mongodb.env (Confidence: 1.0)
MONGODB_URI=mongodb+srv://user:****@cluster.mongodb.net/dbname?retryWrites=true&w=majority
→ Exact match: contains "MONGODB_URI" pattern matching connection string format

infra/docker-compose.yml (Confidence: 0.89)
  mongodb:
    image: mongo:6
    environment:
      - MONGO_INITDB_ROOT_USERNAME=admin
      - MONGO_INITDB_ROOT_PASSWORD=${MONGO_PASSWORD}
→ Uses MongoDB service but connection string external to compose file

Example 2: Command Recovery

$ openclaw smart-finder history "git push with tags"

Found 3 matching commands from shell history:

[1] 2026-03-06 14:22: git push origin main --tags
    → Push commits and all tags (most recent)

[2] 2026-03-05 09:15: git push --follow-tags
    → Push commits and associated tags only

[3] 2026-02-28 16:40: git push origin feature/auth --tags
    → Push feature branch with tags (over 1 week old)

Example 3: Workflow Mapping

$ openclaw smart-finder analyze .github/workflows/ci.yml --related --dependencies

Workflow: CI Pipeline (9 jobs, 15 steps)

Triggers:
  - push to main/develop
  - pull_request

Jobs and dependencies:
  1. lint → depends on: setup-node, uses: .eslintrc.js
  2. test → depends on: lint, uses: jest config in package.json
  3. build → depends on: test, outputs: dist/
  4. docker-build → depends on: build, uses: Dockerfile
  5. deploy-staging → depends on: docker-build, uses: k8s/staging.yaml
  6. integration-test → depends on: deploy-staging, uses: tests/integration/
  7. ... (truncated)

Artifacts:
  - build: dist/ (kept for 7 days)
  - test-reports: coverage/ (kept for 30 days)

Related resources:
  - package.json (scripts, dependencies)
  - Dockerfile (image build)
  - k8s/ (all manifests)
  - .env.example (configuration template)

Example 4: Code Pattern Search

$ openclaw smart-finder find "retry logic with exponential backoff" --type=js,ts --explain

[1] lib/retry.js (Confidence: 0.94)
    const retryWithBackoff = async (fn, maxRetries = 3) => {
      for (let i = 0; i < maxRetries; i++) {
        try {
          return await fn();
        } catch (err) {
          if (i === maxRetries - 1) throw err;
          await delay(2 ** i * 1000); // exponential backoff
        }
      }
    };
    → Implements classic exponential backoff with configurable max retries

[2] services/api-client.js (Confidence: 0.87)
    const result = await retryable(async () => {
      return await fetchWithTimeout(url, { timeout: 5000 });
    }, {
      retries: 5,
      backoff: 'exponential',
      minTimeout: 1000
    });
    → Uses retryable wrapper from lib/retry.js with custom options

[3] utils/exponential.js (Confidence: 0.82)
    function exponentialBackoff(attempt, base = 100, cap = 10000) {
      return Math.min(cap, base * Math.pow(2, attempt));
    }
    → Standalone backoff calculation function

Example 5: Security Audit

$ openclaw smart-finder audit --type=secrets --severity=high

HIGH SEVERITY (3 findings):

[1] .env.local (line 12)
    STRIPE_SECRET_KEY=sk_live_51M... (exposed)
    → Live Stripe secret key in development env file
    Action: Move to production vault, use STRIPE_KEY env var reference

[2] config/database.yml (line 5)
    password: "SuperSecret123!"
    → Hardcoded database password
    Action: Use ENV['DB_PASSWORD'] lookup

[3] src/config.js (line 28)
    const API_KEY = "d+4S!x9@mN#p2z8&";
    → API key committed to source
    Action: Rotate key immediately, use environment variables

MEDIUM SEVERITY (5 findings):
- AWS credentials in test fixtures
- OAuth client_secret in frontend bundle
- JWT secret in backup script
... (truncated)

Recommendations:
1. Rotate all exposed secrets immediately
2. Add pre-commit hook to detect secrets (use git-secrets)
3. Enable OpenClaw secrets manager integration

Example 6: Migration Impact Analysis

$ openclaw smart-finder find "postgres connection" --related

Files directly using PostgreSQL:
- backend/database.js (main connection pool)
- backend/models/user.js (through database.js)
- backend/models/order.js (through database.js)
- scripts/migrate-2.0.sql (direct connection)
- tests/integration/db-test.js (test database)

Configuration sources:
- .env (POSTGRES_CONNECTION_STRING)
- docker-compose.yml (postgres service)
- k8s/postgres-secret.yaml (K8s secret reference)

Scripts affected:
- scripts/backup-db.sh (uses pg_dump)
- scripts/restore-db.sh (uses pg_restore)
- scripts/run-migrations.sh

Documentation:
- docs/database-schema.md
- docs/migration-guide-2.0.md

Estimated impact: HIGH (12 files directly, 25+ indirectly)
Recommended: Blue-green deployment, schema migration tested in staging

Rollback Commands

# 1. Clear query cache (if cached results are stale)
openclaw smart-finder cache --clear --query="your query here"
# OR clear all cache:
openclaw smart-finder cache --clear --all

# 2. Rebuild index from scratch (if index corrupted or after massive changes)
openclaw smart-finder index --rebuild --force --path=.
# Show progress:
openclaw smart-finder index --rebuild --verbose

# 3. Remove specific file from index (if file was indexed by mistake)
openclaw smart-finder index --remove path/to/file.js
# Verify removal:
openclaw smart-finder find "unique string in that file"  # should not find it

# 4. Reset to previous index (if you have index backups)
# Index snapshots stored in: ~/.openclaw/smart-finder-index/backups/
openclaw smart-finder index --restore ~/.openclaw/smart-finder-index/backups/20260306_120000
# List available backups:
ls -la ~/.openclaw/smart-finder-index/backups/

# 5. Disable Smart Finder temporarily (if causing performance issues)
# Toggle via config:
openclaw config set smart-finder.enabled false
# Re-enable:
openclaw config set smart-finder.enabled true

# 6. Clear AI model cache (if using local model and cache corrupted)
rm -rf ~/.cache/openclaw/smart-finder/models/*
# Next query will re-download/reload model

# 7. Rollback specific AI model version (if update broke functionality)
openclaw smart-finder config --model=gpt-4-0613  # pin to previous version
# Check available versions:
openclaw smart-finder config --list-models

# 8. Disable specific scanner (if a file type causes crashes)
openclaw smart-finder config --scanner=typescript=false
# Re-enable:
openclaw smart-finder config --scanner=typescript=true

# 9. Restore default configuration (if config corrupted)
openclaw smart-finder config --reset-defaults
# Backup current config first:
cp ~/.openclaw/config/smart-finder.json ~/.openclaw/config/smart-finder.json.backup

# 10. Stop background indexer (if running)
# Check if process running:
ps aux | grep smart-finder-index
# Kill gracefully (SIGTERM):
pkill -f "smart-finder-index"
# Prevent auto-start:
openclaw config set smart-finder.auto-index false

Troubleshooting

Issue: "No results found" for obvious files

Diagnosis: Index not built or outdated Fix: openclaw smart-finder index --rebuild --verbose Check: openclaw smart-finder index --status

Issue: Slow queries (>30s)

Diagnosis: Index too large or insufficient resources Fix: Increase cache TTL, limit search path: --path=src --path=tests Check: Monitor memory: htop, check index size: du -sh ~/.openclaw/smart-finder-index

Issue: AI service errors

Diagnosis: Cloud AI unavailable or local model corrupted Fix:

• Cloud mode: Check network/API key (echo $SMART_FINDER_API_KEY)
• Local mode: rm -rf ~/.cache/openclaw/smart-finder/models/* && openclaw smart-finder index --rebuild
• Fallback: openclaw config set smart-finder.mode=local (disable cloud)

Issue: False positives/noisy results

Diagnosis: Confidence threshold too low Fix: openclaw smart-finder find "query" --confidence=0.85 Permanent: openclaw config set smart-finder.min_confidence 0.85

Issue: Missing recent files

Diagnosis: Index not updated Fix: openclaw smart-finder index --incremental --path=./new-files Auto: Ensure cron running: crontab -l | grep smart-finder

Issue: Permission denied errors

Diagnosis: Index directory owned by different user Fix: sudo chown -R $USER:$USER ~/.openclaw/smart-finder-index

Issue: Memory exhaustion on large codebases

Diagnosis: Indexing too many large files Fix: Increase max file size limit in config, or exclude patterns: openclaw smart-finder index --exclude="*.min.js,*.bundle.js,*.map"

Issue: Queries return stale results

Diagnosis: Index not refreshed after code changes Fix: Manual rebuild or enable auto-index on git hooks:

# Add to .git/hooks/post-merge:
#!/bin/bash
openclaw smart-finder index --incremental >/dev/null 2>&1 &

Issue: AI model stuck downloading/loading

Diagnosis: Partial download or corrupted cache Fix:

# Clear model cache
rm -rf ~/.cache/openclaw/smart-finder/models
# Set smaller model if resources limited:
openclaw config set smart-finder.ai_model=local-llama-7b
# Or use cloud mode if local RAM insufficient:
openclaw config set smart-finder.mode=cloud

Issue: Search returns actual secret values (RED FLAG)

Diagnosis: Security misconfiguration Fix Immediately:

1. openclaw smart-finder cache --clear --all
2. Rebuild index with secrets filtering: openclaw smart-finder index --rebuild --redact-secrets
3. Audit: openclaw smart-finder audit --type=secrets
4. Rotate all exposed credentials

Performance Optimization

# 1. Limit search scope
openclaw smart-finder find "query" --path=src --path=tests --exclude=node_modules

# 2. Use specific file types
openclaw smart-finder find "query" --type=js,ts,md

# 3. Reduce result set
openclaw smart-finder find "query" --limit=10 --confidence=0.9

# 4. Parallel indexing (for large repos)
openclaw smart-finder index --rebuild --workers=4  # default: CPU count

# 5. Cache frequently used queries
# Cache TTL controlled by SMART_FINDER_CACHE_TTL (default 1 hour)
# Manual cache warmup:
for q in "docker compose", "k8s deployment", "aws s3 sync"; do
  openclaw smart-finder find "$q" >/dev/null &
done
wait

# 6. SSD storage for index (significant speedup)
# Move index to SSD symlink:
mv ~/.openclaw/smart-finder-index /ssd/openclaw-index
ln -s /ssd/openclaw-index ~/.openclaw/smart-finder-index

Integration Examples

Pre-commit Hook Integration

# .git/hooks/pre-commit
#!/bin/bash
# Check for hardcoded secrets before commit
if openclaw smart-finder audit --type=secrets --severity=high --format=json | grep -q '"count":[1-9]; then
  echo "BLOCKED: High severity secrets detected in staged files"
  openclaw smart-finder audit --type=secrets --severity=high
  exit 1
fi

CI/CD Pipeline Integration

# .github/workflows/smart-finder-check.yml