If you’ve ever opened Finder or Explorer, typed a file name you only half-remembered, watched the spinner, sighed, and then manually dug through fifteen sub-folders, this guide is for you. We’ll wire up OpenClaw—yes, the same open-source agent everyone is gluing to Slack—to your local Documents folder so you can type a question like “Where’s my 2024 tax return?” and get the exact PDF in seconds. No cloud upload required unless you want it. The whole thing takes about 20 minutes of actual work and a cup of coffee worth of indexing time, depending on how messy your drive is.

Why make OpenClaw your personal document brain?

macOS Spotlight and Windows Search can find filenames. Sometimes they even manage full-text. But they stop at literal matches. Ask “show me the contract with the startup Peter signed in 2021” and you’ll get blank stares. OpenClaw adds:

  • Semantic search – Vector embeddings so synonyms and fuzzy phrasing still hit.
  • Automatic summaries – Saves opening a 60-page PDF just to remember one clause.
  • Conversational queries – Plain language, no Boolean operators required.
  • Automation hooks – E-mail the file, push to Notion, schedule a reminder, whatever you wire up.

The trade-off: You need to run an indexer, store vectors locally, and think about privacy. That’s what we’ll cover.

The minimum viable setup

Prerequisites

  • Node.js 22 or newer (OpenClaw v0.33.0 tagged last week drops Node 20 support).
  • npm (comes with Node) or pnpm if that’s your vibe.
  • macOS, Linux, or WSL. Windows native works but the file watcher is slower—see notes later.
  • About 3–4 GB of free disk per 10k documents for embeddings. Tweakable.

Install the CLI and gateway

The gateway is the UI you’ll hit in the browser. The daemon does the background work.

# one-liner install a npm install -g openclaw@0.33.0 # or pnpm add -g openclaw # spin up the gateway on http://localhost:4242 openclaw gateway --port 4242 & # start the daemon in a second terminal openclaw daemon --config ~/.config/openclaw/personal.yaml

You don’t have to separate the processes, but keeping the daemon in its own shell makes logs easier to tail.

Pointing OpenClaw at your Documents folder

Create ~/.config/openclaw/personal.yaml (path is arbitrary, pass --config to the daemon) with three sections:

name: personal-agent vectorStore: provider: sqlite # keeps everything local path: ~/Library/OpenClaw/personal-vectors.db indexers: - type: filesystem id: docs path: ~/Documents # or wherever your chaos lives include: - '**/*.pdf' - '**/*.docx' - '**/*.md' - '**/*.txt' exclude: - '**/node_modules/**' - '**/*.tmp' llm: provider: openai # or 'ollama', 'local' – see privacy section model: gpt-3.5-turbo

Hit save, restart the daemon, and it starts crawling. First time is slow—OpenClaw shells out to pdftotext and pandoc for extraction, so install those via Homebrew or apt if missing.

Monitoring progress

openclaw status --id docs --watch

You’ll see something like:

[docs] 0.8% (212/26,500) files processed, ETA 42m

Go get that coffee.

How the indexer works under the hood

Short version:

  1. File watcher notices *.pdf drop or change.
  2. Extractor converts to plain text.
  3. Text is chunked (default 512 tokens with 64 overlap).
  4. Embeddings are generated via OpenAI’s text-embedding-3-small or local all-MiniLM-L6-v2 if you choose offline mode.
  5. Chunks + metadata (path, timestamps, SHA256) land in SQLite or Postgres.

Why SQLite? It’s zero-config and good enough up to a couple million rows. If you outgrow it, point vectorStore at Postgres + pgvector and you’re set.

Ask questions: semantic search and RAG in action

Once the progress bar hits 100 %, flip to the gateway UI (localhost:4242). The chat box is the same one Telegram users know, except the datasource dropdown shows docs.

Example queries the community reports working well:

  • “Where is my tax return from 2024?”
  • “Find the MSA we signed with ACME, clause about termination notice.”
  • “Summarize meeting notes from last August about Kubernetes migration.”

The daemon executes a hybrid search: keyword match first (BM25) and then vector similarity for anything fuzzy. Top 12 chunks feed the RAG prompt. The result comes back with inline citations:

"Your 2024 tax return is in /Users/peter/Documents/Taxes/2024/1040.pdf" ↩︎ [1040.pdf §1]

Click the citation to open the file directly in your OS. OpenClaw’s macOS helper app handles open calls; on Linux it’s xdg-open.

Recipes for automatic document summarization

Sometimes you want short notes, not a single answer. Two patterns:

One-shot summary via chat

Ask:

"Summarize the contract with XYZ Company in bullet points, max 200 words."

OpenClaw streams tokens back. The agent attaches the source path to the message metadata, so you can copy paste with confidence.

Batch summaries with a scheduled task

Use the built-in scheduler so every new file gets a markdown summary next to it.

# in personal.yaml schedules: - cron: "0 */6 * * *" # every 6 hours task: summarize-new-docs # tasks.yaml (referenced implicitly) tasks: summarize-new-docs: forEach: "select path from files where summary is null and mtime > now() - interval '1 day'" run: - type: summarization input: "${path}" output: "${dirname(path)}/${basename(path)}.summary.md"

Under the hood it’s the same chat completion call but headless. The summary files get versioned with your normal Git/Dropbox/Time Machine flow.

Keeping it private: running fully offline

The big question: “Do I really want an AI reading my tax returns?” Fair. You have two knobs:

  1. Local embeddings – Set embeddingProvider: local and OpenClaw uses sentence-transformers/all-MiniLM-L6-v2 via @xenova/transformers. Slower, but nothing leaves disk.
  2. Local LLM – Point llm.provider to ollama and run ollama run mistral or gemma:2b. Expect higher latency and bigger GPU/CPU load.

Hybrid approach many users choose:

  • Local embeddings (cheap CPU) + remote LLM (paid tokens only for final answer).
  • Set openai.baseURL to Azure or your own proxy if you need audit logging.

Opt-in telemetry

OpenClaw phones home by default only for crash dumps. Disable:

telemetry: enabled: false

Your file paths never hit the network either way. The code path for crash dumps scrubs them—and yes, I read reporter.ts to verify.

Maintenance: reindexing, backups, pruning vectors

Two months in you’ll add enough files to blow past the SSD cache:

  • Automatic file watcher handles new and modified docs.
  • Deleted files get purged on the next daily GC run. Tune via gc.frequency.
  • Re-embedding threshold: major LLM releases usually demand re-embedding. Run openclaw reindex --id docs --embeddings-only in a tmux session overnight.
  • Backups: the SQLite DB + ~/.cache/openclaw/extracts. Stick them in Time Machine and you’re good. Restores are file copies.

Troubleshooting common snags

“File system watcher exploded on macOS Ventura”

Ventura hits a hard 256k FSEvents queue. Add:

export OPENCLAW_WATCHER=polling

and live with 5-second latency.

“GPU out of memory with local LLM”

Pass --gpu-memory 4096 to Ollama or pick a smaller model. 2-3 GB cards can barely run mistral-instruct.

“Search is slow after 100k docs”

SQLite scales vertically but not indefinitely. Move to Postgres:

vectorStore: provider: postgres url: postgres://user:pass@localhost:5432/openclaw

Then CREATE EXTENSION pgvector; and rerun the daemon. Expect 3-4× speed-up on cosine search.

Wrapping up and next steps

You now have a local agent that knows every PDF, DOCX, and markdown note on your drive and will answer questions in plain English. The obvious next hacks are:

  • Hook the agent to your phone via WhatsApp so you can grab docs on the go.
  • Add a cron to e-mail yourself summaries of anything tagged “receipt”.
  • Expose the search API over a private VPN to share with family (set auth.jwt first).

OpenClaw is opinionated but not precious—read the code, tweak chunk sizes, swap out models. If you uncover a bug, the maintainers merge well-scoped PRs in under a day. And yes, you can host the whole thing on ClawCloud if you’d rather not babysit the daemon. For my money, keeping the index beside my SSD feels safer, and that’s the beauty of it: choice.