{ "schemaVersion": "1.0", "item": { "slug": "claw-drive", "name": "Claw Drive", "source": "tencent", "type": "skill", "category": "效率提升", "sourceUrl": "https://clawhub.ai/zhiyuanw101/claw-drive", "canonicalUrl": "https://clawhub.ai/zhiyuanw101/claw-drive", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/claw-drive", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=claw-drive", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "CHANGELOG.md", "README.md", "SKILL.md", "docs/security.md", "docs/sync.md", "docs/tags.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-23T16:43:11.935Z", "expiresAt": "2026-04-30T16:43:11.935Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/claw-drive" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/claw-drive", "agentPageUrl": "https://openagent3.xyz/skills/claw-drive/agent", "manifestUrl": "https://openagent3.xyz/skills/claw-drive/agent.json", "briefUrl": "https://openagent3.xyz/skills/claw-drive/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "Claw Drive", "body": "Organize and retrieve personal files with auto-categorization and a searchable index." }, { "title": "⚠️ Privacy — Read This First", "body": "File contents are personal data. Treat them accordingly.\n\nNEVER read file contents without explicit user consent. Always ask first. Always.\nIf the user doesn't reply → default to SENSITIVE. Silence = no consent.\nidentity/ files are ALWAYS sensitive — never read, never extract, never log contents.\nExtracted content enters the conversation transcript which is logged permanently to .jsonl files. Once you read a file, its contents are in the logs forever.\nDescriptions in INDEX.jsonl are also persistent. Don't put sensitive details (SSNs, account numbers, passwords) in descriptions even for non-sensitive files — use redacted/partial forms (e.g. \"account ending ****4321\").\nWhen in doubt, don't read. A vague index entry is better than leaked personal data.\n\nData locality: All data stays on your machine. INDEX.jsonl, stored files, and hash ledger are local. Conversation transcripts (.jsonl) are also local to your OpenClaw instance. Nothing is sent to external servers unless you explicitly enable Google Drive sync (optional, and only syncs the files you choose)." }, { "title": "Dependencies", "body": "claw-drive CLI — brew install dissaozw/tap/claw-drive (or make install from skill directory for manual setup)\npymupdf — PDF text extraction (uv run --with pymupdf — no global install needed)\nrclone — Google Drive sync (optional): brew install rclone\nfswatch — file watch daemon (optional): brew install fswatch" }, { "title": "⚠️ CLI Usage — Read This Before Running Anything", "body": "ALWAYS use the claw-drive CLI. NEVER use cp, mv, or direct file writes to ~/claw-drive/.\n\nThe CLI handles copying, hashing, deduplication, and index updates atomically. Bypassing it causes:\n\nFiles stored without hash registration → dedup breaks silently\nINDEX.jsonl out of sync with actual files\nVersion confusion when replacing files\n\nPATH note: If installed via Homebrew (brew install dissaozw/tap/claw-drive), the binary is in /opt/homebrew/bin/ and should be in PATH automatically. If installed manually, ~/.local/bin may not be in the agent shell's PATH — use the full path:\n\nclaw-drive store ...\n\nIf the manual symlink is broken, re-run make install from ~/.openclaw/skills/claw-drive/ to fix it." }, { "title": "Setup", "body": "claw-drive init [path]\n\nThis creates the directory structure, INDEX.jsonl, and hash ledger. Default path: ~/claw-drive." }, { "title": "Storing a file", "body": "When receiving a file (email attachment, Telegram upload, etc.):\n\nPrivacy check — ask the user gracefully if the file contains sensitive/personal data:\n\nSomething like: \"Should I read the contents to index it better, or would you prefer I keep it private and just use the filename?\"\nIf user says sensitive, or if user doesn't reply → treat as sensitive (default-safe)\nIf user confirms it's fine to read → proceed with full extraction\nFiles going to identity/ are always sensitive — never read contents\nSensitive flow: classify by filename/metadata only. If that's not enough for a good description, ask the user for a brief description. Never read file contents into the conversation.\n\n\n\nExtract (normal files only) — read file contents:\n\nPDFs: extract text via uv run --with pymupdf python3 -c \"import pymupdf; ...\" or use the image tool\nImages: use the image tool to read/describe contents\nOther formats: read directly if possible\nPull out key entities: names, dates, amounts, account/policy numbers, addresses, etc.\n\n\n\nClassify — determine the best category from the categories table below\n\n\nInspect category structure — after choosing a category, examine existing subfolders in that category (e.g. with tree/find) before finalizing destination\n\n\nChoose destination path\n\nIf an existing subfolder is a clear semantic match, store there\nIf multiple existing subfolders could match (conflicting/ambiguous), store at category root\nStore at category root when the file is only generally related to the category and lacks specific detail\nCreate a new subfolder only when no existing subfolder fits and the file has clear specific detail that justifies one\n\n\n\nName — choose a descriptive filename: --.\n\n\nDescribe — write a rich description using extracted content (or user-provided description for sensitive files). Include key details (dates, amounts, IDs, names) so the file is findable by any relevant search term. Don't be vague — \"insurance card\" is bad, \"Acme Insurance ID cards - 2024 Honda Civic, Policy ****3441, effective 1/21/2026–7/21/2026\" is good.\n\n\nTag — include specific tags from extracted content (model names, policy numbers, VINs, entity names) in addition to category tags\n\n\nStore — run the CLI (use full path if claw-drive not in PATH):\nclaw-drive store --category --name 'clean-name.ext' --desc 'Rich description with key details' --tags 'tag1, tag2' --source telegram\n\n\nShell quoting safety: Prefer single quotes for --desc/--tags/--name when constructing shell commands. This avoids $ expansion (e.g. currency amounts like $941.39) and prevents metadata corruption.\n⚠️ Do NOT use cp or write files directly to ~/claw-drive/. The CLI is the only correct way to store files — it handles copying, hashing, dedup, and index updates atomically.\n\n\n\nReport — tell the user: path, category, tags, key extracted details, and what was indexed\n\nThe CLI handles copying, hashing, deduplication, and index updates automatically. If the file is a duplicate, it will be rejected.\n\nThe --name flag lets you override the original filename (which may be ugly like file_17---8c1ee63d-...) with a clean, descriptive name." }, { "title": "Retrieving a file", "body": "Do NOT read INDEX.jsonl directly in the main session. Spawn a search sub-agent instead. This keeps the index out of your context window and scales to large file collections.\n\nWhy sub-agent?\n\nThe index grows with every stored file (~300 bytes/entry). At 1000+ files, reading the full index into the main agent's context wastes tokens and may hit context limits. A sub-agent runs in its own isolated session with a cheap model, reads the index, and returns only the matching entries.\n\nHow to spawn\n\nUse sessions_spawn with:\n\nmode: run\nmodel: A lightweight model is recommended (the search task is simple). Resolution order:\n\nExplicit model param on sessions_spawn (if provided)\nagents.defaults.subagents.model in config (if set)\nFalls back to the main agent's model\n\n\ntask: The prompt below, with the user's query filled in\n\nYou are a file search agent. Read ~/claw-drive/INDEX.jsonl and find entries matching this query:\n\n\"\"\n\nReturn ONLY valid JSON, no explanation:\n\n{\n \"matches\": [\n {\n \"path\": \"\",\n \"desc\": \"\",\n \"date\": \"\",\n \"tags\": [\"\"],\n \"confidence\": \"high|medium|low\"\n }\n ],\n \"total_indexed\": ,\n \"query\": \"\"\n}\n\nRules:\n- Max 5 matches, sorted by relevance\n- confidence: high = exact match, medium = likely relevant, low = tangential\n- If no matches, return {\"matches\": [], \"total_indexed\": N, \"query\": \"...\"}\n- Only read INDEX.jsonl, never read file contents\n\nReceive and deliver\n\nThe sub-agent auto-announces its result back to your session\nParse the JSON from the announce message\nPrepend ~/claw-drive/ to each path to get the full file path\nSend the file: The claw-drive directory may not be in the message tool's allowed paths. If sending fails with \"not under an allowed directory\", copy the file to a temp location first (e.g. workspace), send it, then clean up:\ncp ~/claw-drive/ ~/.openclaw/workspace/\n# send via message tool\nrm ~/.openclaw/workspace/\n\n\nNever show raw sub-agent JSON to the user. The announce message is internal — immediately process it and deliver the file. The user should only see the file and a brief description, not search internals.\nFor multiple matches, send the most relevant one and list the rest — let the user pick\n\nTroubleshooting: pairing required\n\nIf sessions_spawn returns pairing required, the sub-agent's exec harness needs device pairing approval. Run:\n\nopenclaw devices list # find the pending request\nopenclaw devices approve \n\nThis is a one-time setup — once approved, subsequent spawns work without re-pairing.\n\nIndex format\n\nINDEX.jsonl is a JSONL file — one JSON object per line. Each entry has: date, path, desc, tags (array), source, and optional fields metadata (JSON), original_name, correspondent." }, { "title": "Updating an entry", "body": "claw-drive update --desc \"new description\" --tags \"new, tags\"\n\nBoth --desc and --tags are optional (at least one required). Uses jq for atomic rewrite." }, { "title": "Deleting a file", "body": "claw-drive delete --force\n\nWithout --force, shows what would be deleted (dry run). With --force, removes file + index entry + dedup hash." }, { "title": "Tagging", "body": "Tags add cross-category searchability. A file lives in one folder but can have multiple tags.\n\nGuidelines:\n\n1-5 tags per file, comma-separated\nLowercase, single words or short hyphenated phrases\nAlways include the category name as a tag (e.g. medical for files in medical/)\nAdd cross-cutting tags for things like: entity names (my-cat), document type (invoice, receipt, report), context (emergency, tax-2025)\nReuse existing tags when possible — read INDEX.jsonl to see existing tags before inventing new ones\n\nExamples:\n\n# Insurance PDF — after extracting: policy number, vehicle, VIN, dates, agent\nclaw-drive store file.pdf -c insurance -n \"acme-auto-id-cards.pdf\" \\\n -d \"Acme Insurance ID cards - 2024 Honda Civic, VIN 1HGBH41JXMN109186, Policy ****3441, effective 1/21/2026–7/21/2026, agent Jane Smith (555) 123-4567\" \\\n -t \"insurance, auto, acme, id-card, honda-civic, california\" -s telegram\n\n# Vet invoice — after extracting: clinic, amount, diagnosis, pet name\nclaw-drive store invoice.pdf -c medical -n \"my-cat-vet-invoice-2026-02-15.pdf\" \\\n -d \"VEG emergency visit invoice - Max (cat), $1,234.56, bronchial pattern diagnosis, prednisolone prescribed\" \\\n -t \"medical, invoice, max, emergency, vet\" -s email\n\n# W-2 — after extracting: employer, tax year, wages\nclaw-drive store w2.pdf -c finance -n \"w2-2025.pdf\" \\\n -d \"W-2 tax form 2025 - Employer: Acme Corp, wages $120,000\" \\\n -t \"finance, tax-2025, w2\" -s email\n\n# Sensitive file — user said \"keep it private\" or didn't reply\nclaw-drive store scan.pdf -c identity -n \"passport-scan-2026.pdf\" \\\n -d \"Passport scan\" \\\n -t \"identity, passport\" -s telegram\n\n# Sensitive file — user provided brief description\nclaw-drive store doc.pdf -c contracts -n \"apartment-lease-2026.pdf\" \\\n -d \"Apartment lease agreement, signed Jan 2026\" \\\n -t \"contracts, lease, housing\" -s email" }, { "title": "Naming conventions", "body": "Lowercase, hyphens between words: my-cat-vet-invoice-2026-02-15.pdf\nInclude date when relevant\nInclude subject/entity name for clarity\nKeep it human-readable — no UUIDs or timestamps" }, { "title": "Categories", "body": "Categories are not fixed — the agent can create any category that makes sense. The CLI does mkdir -p automatically. These are the defaults created by init, but use whatever fits:\n\nCategoryUse fordocumentsGeneral docs, letters, forms, manualsfinanceTax returns, bank statements, investment docs, pay stubsinsuranceInsurance policies, claims, coverage documentsmedicalHealth records, lab results, prescriptions, pet healthtravelBoarding passes, itineraries, hotel bookings, visasidentityPassport scans, birth certs, SSN docs (⚠️ sensitive)receiptsPurchase receipts, warranties, service invoicescontractsLeases, employment agreements, legal docsphotosPersonal photos, document scansmiscAnything that doesn't fit above\n\nNeed housing/, work/, pets/? Just use it — the directory is created on first store.\n\nWhen in doubt: misc/ is fine. Better to store it somewhere than not at all." }, { "title": "Migration", "body": "Bulk-import files from an existing directory:\n\n# 1. Scan source directory into a plan\nclaw-drive migrate scan ~/messy-folder plan.json\n\n# 2. Agent classifies each file (fills in category, name, tags, description in the JSON)\n\n# 3. Review\nclaw-drive migrate summary plan.json\n\n# 4. Dry run\nclaw-drive migrate apply plan.json --dry-run\n\n# 5. Execute\nclaw-drive migrate apply plan.json\n\nThe plan JSON contains one entry per file with category, name, tags, description fields (initially null). The agent fills these in using the same extract-first approach, then apply copies files with full dedup and indexing." }, { "title": "Sync (Optional)", "body": "Claw Drive can auto-sync to Google Drive (or any rclone-supported backend) via a background daemon." }, { "title": "Prerequisites", "body": "brew install rclone fswatch" }, { "title": "Authorization", "body": "Run claw-drive sync auth. It opens a browser on the machine for Google sign-in.\n\nWhat happens:\n\nrclone requests Google Drive file access only (not full Google account)\nOAuth token is stored locally at ~/.config/rclone/rclone.conf — never sent to any third party\nData flows directly from your machine to Google Drive — no intermediary servers\nYou can revoke access anytime via Google Account → Security → Third-party apps\n\nAgent behavior during auth:\n\nRun claw-drive sync auth in background\nTry the OpenClaw browser tool to click through the Google consent screen\nIf browser tool is unavailable, send the auth URL to the user and ask them to complete sign-in on the machine (e.g. via Screen Sharing)\nWait for rclone to capture the token" }, { "title": "Commands", "body": "claw-drive sync setup # verify deps and config\nclaw-drive sync start # start background daemon (fswatch + rclone)\nclaw-drive sync stop # stop daemon\nclaw-drive sync push # manual one-shot sync\nclaw-drive sync status # show sync status\n\nThe daemon watches the drive directory for file changes and syncs to the remote within seconds. It runs as a launchd service — starts on login, restarts on failure.\n\nLogs: ~/Library/Logs/claw-drive/sync.log" }, { "title": "Per-category privacy", "body": "Use the exclude list in .sync-config to keep sensitive directories local-only. identity/ is excluded by default." }, { "title": "Verify", "body": "Check index ↔ disk ↔ hash consistency:\n\nclaw-drive verify # report issues\nclaw-drive verify --fix # auto-repair what's fixable\n\nAuto-fixable: missing on disk (removes stale index entry), missing hash (re-registers).\nManual review: orphan files (no metadata to index), hash mismatches (possible corruption).\n\nRun verify after manual file operations or when something seems off." }, { "title": "Tips", "body": "The CLI maintains INDEX.jsonl automatically — don't edit it manually\nPDF text extraction: uv run --with pymupdf python3 -c \"import pymupdf; ...\"\nUse claw-drive status to see file counts, size, and sync status" }, { "title": "Privacy Checklist (every store)", "body": "Before storing any file, verify:\n\nDid I ask the user about privacy? (not optional)\n If no reply: am I treating it as sensitive? (must be yes)\n If sensitive: am I skipping content extraction? (must be yes)\n If identity/: am I skipping extraction regardless? (must be yes)\n Are there SSNs, full account numbers, or passwords in my description? (must be no)\n Would I be comfortable if this INDEX.jsonl entry leaked? (must be yes)" } ], "body": "Claw Drive\n\nOrganize and retrieve personal files with auto-categorization and a searchable index.\n\n⚠️ Privacy — Read This First\n\nFile contents are personal data. Treat them accordingly.\n\nNEVER read file contents without explicit user consent. Always ask first. Always.\nIf the user doesn't reply → default to SENSITIVE. Silence = no consent.\nidentity/ files are ALWAYS sensitive — never read, never extract, never log contents.\nExtracted content enters the conversation transcript which is logged permanently to .jsonl files. Once you read a file, its contents are in the logs forever.\nDescriptions in INDEX.jsonl are also persistent. Don't put sensitive details (SSNs, account numbers, passwords) in descriptions even for non-sensitive files — use redacted/partial forms (e.g. \"account ending ****4321\").\nWhen in doubt, don't read. A vague index entry is better than leaked personal data.\n\nData locality: All data stays on your machine. INDEX.jsonl, stored files, and hash ledger are local. Conversation transcripts (.jsonl) are also local to your OpenClaw instance. Nothing is sent to external servers unless you explicitly enable Google Drive sync (optional, and only syncs the files you choose).\n\nDependencies\nclaw-drive CLI — brew install dissaozw/tap/claw-drive (or make install from skill directory for manual setup)\npymupdf — PDF text extraction (uv run --with pymupdf — no global install needed)\nrclone — Google Drive sync (optional): brew install rclone\nfswatch — file watch daemon (optional): brew install fswatch\n⚠️ CLI Usage — Read This Before Running Anything\n\nALWAYS use the claw-drive CLI. NEVER use cp, mv, or direct file writes to ~/claw-drive/.\n\nThe CLI handles copying, hashing, deduplication, and index updates atomically. Bypassing it causes:\n\nFiles stored without hash registration → dedup breaks silently\nINDEX.jsonl out of sync with actual files\nVersion confusion when replacing files\n\nPATH note: If installed via Homebrew (brew install dissaozw/tap/claw-drive), the binary is in /opt/homebrew/bin/ and should be in PATH automatically. If installed manually, ~/.local/bin may not be in the agent shell's PATH — use the full path:\n\nclaw-drive store ...\n\n\nIf the manual symlink is broken, re-run make install from ~/.openclaw/skills/claw-drive/ to fix it.\n\nSetup\nclaw-drive init [path]\n\n\nThis creates the directory structure, INDEX.jsonl, and hash ledger. Default path: ~/claw-drive.\n\nWorkflow\nStoring a file\n\nWhen receiving a file (email attachment, Telegram upload, etc.):\n\nPrivacy check — ask the user gracefully if the file contains sensitive/personal data:\n\nSomething like: \"Should I read the contents to index it better, or would you prefer I keep it private and just use the filename?\"\nIf user says sensitive, or if user doesn't reply → treat as sensitive (default-safe)\nIf user confirms it's fine to read → proceed with full extraction\nFiles going to identity/ are always sensitive — never read contents\nSensitive flow: classify by filename/metadata only. If that's not enough for a good description, ask the user for a brief description. Never read file contents into the conversation.\n\nExtract (normal files only) — read file contents:\n\nPDFs: extract text via uv run --with pymupdf python3 -c \"import pymupdf; ...\" or use the image tool\nImages: use the image tool to read/describe contents\nOther formats: read directly if possible\nPull out key entities: names, dates, amounts, account/policy numbers, addresses, etc.\n\nClassify — determine the best category from the categories table below\n\nInspect category structure — after choosing a category, examine existing subfolders in that category (e.g. with tree/find) before finalizing destination\n\nChoose destination path\n\nIf an existing subfolder is a clear semantic match, store there\nIf multiple existing subfolders could match (conflicting/ambiguous), store at category root\nStore at category root when the file is only generally related to the category and lacks specific detail\nCreate a new subfolder only when no existing subfolder fits and the file has clear specific detail that justifies one\n\nName — choose a descriptive filename: --.\n\nDescribe — write a rich description using extracted content (or user-provided description for sensitive files). Include key details (dates, amounts, IDs, names) so the file is findable by any relevant search term. Don't be vague — \"insurance card\" is bad, \"Acme Insurance ID cards - 2024 Honda Civic, Policy ****3441, effective 1/21/2026–7/21/2026\" is good.\n\nTag — include specific tags from extracted content (model names, policy numbers, VINs, entity names) in addition to category tags\n\nStore — run the CLI (use full path if claw-drive not in PATH):\n\nclaw-drive store --category --name 'clean-name.ext' --desc 'Rich description with key details' --tags 'tag1, tag2' --source telegram\n\nShell quoting safety: Prefer single quotes for --desc/--tags/--name when constructing shell commands. This avoids $ expansion (e.g. currency amounts like $941.39) and prevents metadata corruption. ⚠️ Do NOT use cp or write files directly to ~/claw-drive/. The CLI is the only correct way to store files — it handles copying, hashing, dedup, and index updates atomically.\n\nReport — tell the user: path, category, tags, key extracted details, and what was indexed\n\nThe CLI handles copying, hashing, deduplication, and index updates automatically. If the file is a duplicate, it will be rejected.\n\nThe --name flag lets you override the original filename (which may be ugly like file_17---8c1ee63d-...) with a clean, descriptive name.\n\nRetrieving a file\n\nDo NOT read INDEX.jsonl directly in the main session. Spawn a search sub-agent instead. This keeps the index out of your context window and scales to large file collections.\n\nWhy sub-agent?\n\nThe index grows with every stored file (~300 bytes/entry). At 1000+ files, reading the full index into the main agent's context wastes tokens and may hit context limits. A sub-agent runs in its own isolated session with a cheap model, reads the index, and returns only the matching entries.\n\nHow to spawn\n\nUse sessions_spawn with:\n\nmode: run\nmodel: A lightweight model is recommended (the search task is simple). Resolution order:\nExplicit model param on sessions_spawn (if provided)\nagents.defaults.subagents.model in config (if set)\nFalls back to the main agent's model\ntask: The prompt below, with the user's query filled in\nYou are a file search agent. Read ~/claw-drive/INDEX.jsonl and find entries matching this query:\n\n\"\"\n\nReturn ONLY valid JSON, no explanation:\n\n{\n \"matches\": [\n {\n \"path\": \"\",\n \"desc\": \"\",\n \"date\": \"\",\n \"tags\": [\"\"],\n \"confidence\": \"high|medium|low\"\n }\n ],\n \"total_indexed\": ,\n \"query\": \"\"\n}\n\nRules:\n- Max 5 matches, sorted by relevance\n- confidence: high = exact match, medium = likely relevant, low = tangential\n- If no matches, return {\"matches\": [], \"total_indexed\": N, \"query\": \"...\"}\n- Only read INDEX.jsonl, never read file contents\n\nReceive and deliver\nThe sub-agent auto-announces its result back to your session\nParse the JSON from the announce message\nPrepend ~/claw-drive/ to each path to get the full file path\nSend the file: The claw-drive directory may not be in the message tool's allowed paths. If sending fails with \"not under an allowed directory\", copy the file to a temp location first (e.g. workspace), send it, then clean up:\ncp ~/claw-drive/ ~/.openclaw/workspace/\n# send via message tool\nrm ~/.openclaw/workspace/\n\nNever show raw sub-agent JSON to the user. The announce message is internal — immediately process it and deliver the file. The user should only see the file and a brief description, not search internals.\nFor multiple matches, send the most relevant one and list the rest — let the user pick\nTroubleshooting: pairing required\n\nIf sessions_spawn returns pairing required, the sub-agent's exec harness needs device pairing approval. Run:\n\nopenclaw devices list # find the pending request\nopenclaw devices approve \n\n\nThis is a one-time setup — once approved, subsequent spawns work without re-pairing.\n\nIndex format\n\nINDEX.jsonl is a JSONL file — one JSON object per line. Each entry has: date, path, desc, tags (array), source, and optional fields metadata (JSON), original_name, correspondent.\n\nUpdating an entry\nclaw-drive update --desc \"new description\" --tags \"new, tags\"\n\n\nBoth --desc and --tags are optional (at least one required). Uses jq for atomic rewrite.\n\nDeleting a file\nclaw-drive delete --force\n\n\nWithout --force, shows what would be deleted (dry run). With --force, removes file + index entry + dedup hash.\n\nTagging\n\nTags add cross-category searchability. A file lives in one folder but can have multiple tags.\n\nGuidelines:\n\n1-5 tags per file, comma-separated\nLowercase, single words or short hyphenated phrases\nAlways include the category name as a tag (e.g. medical for files in medical/)\nAdd cross-cutting tags for things like: entity names (my-cat), document type (invoice, receipt, report), context (emergency, tax-2025)\nReuse existing tags when possible — read INDEX.jsonl to see existing tags before inventing new ones\n\nExamples:\n\n# Insurance PDF — after extracting: policy number, vehicle, VIN, dates, agent\nclaw-drive store file.pdf -c insurance -n \"acme-auto-id-cards.pdf\" \\\n -d \"Acme Insurance ID cards - 2024 Honda Civic, VIN 1HGBH41JXMN109186, Policy ****3441, effective 1/21/2026–7/21/2026, agent Jane Smith (555) 123-4567\" \\\n -t \"insurance, auto, acme, id-card, honda-civic, california\" -s telegram\n\n# Vet invoice — after extracting: clinic, amount, diagnosis, pet name\nclaw-drive store invoice.pdf -c medical -n \"my-cat-vet-invoice-2026-02-15.pdf\" \\\n -d \"VEG emergency visit invoice - Max (cat), $1,234.56, bronchial pattern diagnosis, prednisolone prescribed\" \\\n -t \"medical, invoice, max, emergency, vet\" -s email\n\n# W-2 — after extracting: employer, tax year, wages\nclaw-drive store w2.pdf -c finance -n \"w2-2025.pdf\" \\\n -d \"W-2 tax form 2025 - Employer: Acme Corp, wages $120,000\" \\\n -t \"finance, tax-2025, w2\" -s email\n\n# Sensitive file — user said \"keep it private\" or didn't reply\nclaw-drive store scan.pdf -c identity -n \"passport-scan-2026.pdf\" \\\n -d \"Passport scan\" \\\n -t \"identity, passport\" -s telegram\n\n# Sensitive file — user provided brief description\nclaw-drive store doc.pdf -c contracts -n \"apartment-lease-2026.pdf\" \\\n -d \"Apartment lease agreement, signed Jan 2026\" \\\n -t \"contracts, lease, housing\" -s email\n\nNaming conventions\nLowercase, hyphens between words: my-cat-vet-invoice-2026-02-15.pdf\nInclude date when relevant\nInclude subject/entity name for clarity\nKeep it human-readable — no UUIDs or timestamps\nCategories\n\nCategories are not fixed — the agent can create any category that makes sense. The CLI does mkdir -p automatically. These are the defaults created by init, but use whatever fits:\n\nCategory\tUse for\ndocuments\tGeneral docs, letters, forms, manuals\nfinance\tTax returns, bank statements, investment docs, pay stubs\ninsurance\tInsurance policies, claims, coverage documents\nmedical\tHealth records, lab results, prescriptions, pet health\ntravel\tBoarding passes, itineraries, hotel bookings, visas\nidentity\tPassport scans, birth certs, SSN docs (⚠️ sensitive)\nreceipts\tPurchase receipts, warranties, service invoices\ncontracts\tLeases, employment agreements, legal docs\nphotos\tPersonal photos, document scans\nmisc\tAnything that doesn't fit above\n\nNeed housing/, work/, pets/? Just use it — the directory is created on first store.\n\nWhen in doubt: misc/ is fine. Better to store it somewhere than not at all.\n\nMigration\n\nBulk-import files from an existing directory:\n\n# 1. Scan source directory into a plan\nclaw-drive migrate scan ~/messy-folder plan.json\n\n# 2. Agent classifies each file (fills in category, name, tags, description in the JSON)\n\n# 3. Review\nclaw-drive migrate summary plan.json\n\n# 4. Dry run\nclaw-drive migrate apply plan.json --dry-run\n\n# 5. Execute\nclaw-drive migrate apply plan.json\n\n\nThe plan JSON contains one entry per file with category, name, tags, description fields (initially null). The agent fills these in using the same extract-first approach, then apply copies files with full dedup and indexing.\n\nSync (Optional)\n\nClaw Drive can auto-sync to Google Drive (or any rclone-supported backend) via a background daemon.\n\nPrerequisites\nbrew install rclone fswatch\n\nAuthorization\n\nRun claw-drive sync auth. It opens a browser on the machine for Google sign-in.\n\nWhat happens:\n\nrclone requests Google Drive file access only (not full Google account)\nOAuth token is stored locally at ~/.config/rclone/rclone.conf — never sent to any third party\nData flows directly from your machine to Google Drive — no intermediary servers\nYou can revoke access anytime via Google Account → Security → Third-party apps\n\nAgent behavior during auth:\n\nRun claw-drive sync auth in background\nTry the OpenClaw browser tool to click through the Google consent screen\nIf browser tool is unavailable, send the auth URL to the user and ask them to complete sign-in on the machine (e.g. via Screen Sharing)\nWait for rclone to capture the token\nCommands\nclaw-drive sync setup # verify deps and config\nclaw-drive sync start # start background daemon (fswatch + rclone)\nclaw-drive sync stop # stop daemon\nclaw-drive sync push # manual one-shot sync\nclaw-drive sync status # show sync status\n\n\nThe daemon watches the drive directory for file changes and syncs to the remote within seconds. It runs as a launchd service — starts on login, restarts on failure.\n\nLogs: ~/Library/Logs/claw-drive/sync.log\n\nPer-category privacy\n\nUse the exclude list in .sync-config to keep sensitive directories local-only. identity/ is excluded by default.\n\nVerify\n\nCheck index ↔ disk ↔ hash consistency:\n\nclaw-drive verify # report issues\nclaw-drive verify --fix # auto-repair what's fixable\n\n\nAuto-fixable: missing on disk (removes stale index entry), missing hash (re-registers). Manual review: orphan files (no metadata to index), hash mismatches (possible corruption).\n\nRun verify after manual file operations or when something seems off.\n\nTips\nThe CLI maintains INDEX.jsonl automatically — don't edit it manually\nPDF text extraction: uv run --with pymupdf python3 -c \"import pymupdf; ...\"\nUse claw-drive status to see file counts, size, and sync status\nPrivacy Checklist (every store)\n\nBefore storing any file, verify:\n\n Did I ask the user about privacy? (not optional)\n If no reply: am I treating it as sensitive? (must be yes)\n If sensitive: am I skipping content extraction? (must be yes)\n If identity/: am I skipping extraction regardless? (must be yes)\n Are there SSNs, full account numbers, or passwords in my description? (must be no)\n Would I be comfortable if this INDEX.jsonl entry leaked? (must be yes)" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/zhiyuanw101/claw-drive", "publisherUrl": "https://clawhub.ai/zhiyuanw101/claw-drive", "owner": "zhiyuanw101", "version": "0.4.4", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/claw-drive", "downloadUrl": "https://openagent3.xyz/downloads/claw-drive", "agentUrl": "https://openagent3.xyz/skills/claw-drive/agent", "manifestUrl": "https://openagent3.xyz/skills/claw-drive/agent.json", "briefUrl": "https://openagent3.xyz/skills/claw-drive/agent.md" } }