paperless-ngx

What This Skill Does

The paperless-ngx skill empowers OpenClaw to act as a bridge between your digital assistant and your Paperless-ngx document management system. It provides comprehensive control over your personal or professional document archive, enabling full-text searching, metadata retrieval, automated uploads, and document organization via tags, types, and correspondents. By integrating directly with the Paperless-ngx REST API, this skill allows users to treat their document repository as a queryable data source, facilitating tasks like finding specific invoices, retrieving document metadata, or offloading files directly from local storage into the archive with specific tagging rules.

Installation

To install this skill, use the OpenClaw command line interface: clawhub install openclaw/skills/skills/madmantim/paperless-ngx-tools. Once installed, you must configure your instance credentials. This can be done globally by adding your PAPERLESS_URL and PAPERLESS_TOKEN to ~/.clawdbot/clawdbot.json, or locally within the skill configuration entry. To generate your token, navigate to your Paperless web interface under Settings > Users & Groups > [Your User] > Generate Token. Ensure your API token has sufficient permissions to read and write documents to the server.

Use Cases

This skill is ideal for users looking to reduce paper clutter and manual data entry. Common use cases include: 1. Automated Filing: Batch uploading downloaded invoices or receipts from a downloads folder with specific tags and types applied automatically. 2. Contextual Retrieval: Asking the AI to locate a specific document—such as 'Find my latest internet bill from AGL'—and immediately downloading the original PDF for review. 3. System Audit: Listing all correspondents or tags to clean up or reorganize a large archive. 4. Workflow Automation: Using document metadata to trigger external workflows, such as checking if an invoice has been paid based on its 'unpaid' tag status.

Example Prompts

1. "Search for all invoices from the last month tagged with 'tax-deductible' and list their IDs and titles."
2. "Upload the file located at ~/Documents/receipt.pdf, label it as an 'Expense', set the correspondent to 'Coffee Shop', and add the tag 'reimbursable'."
3. "Download the latest document matching 'electricity bill' to my current working directory and tell me the creation date found in the metadata."

Tips & Limitations

• Security: The skill stores your API token in configuration files. Ensure these files have appropriate read/write permissions on your filesystem to prevent unauthorized access.
• Large Archives: When searching, keep queries specific; broad searches on massive archives may result in long response times or truncated result lists.
• File Handling: Ensure the files you are uploading exist locally and are accessible by the OpenClaw agent. The script uses standard file system paths; relative paths are relative to the execution context. If you encounter issues, verify your PAPERLESS_URL is reachable from the network your agent is operating on.