Guide

OpenClaw + Stirling PDF: A Self-Hosted PDF Toolbox for Agents

Q: Can an OpenClaw agent edit PDFs?

Yes. Connect a self-hosted Stirling PDF server from Dashboard Tools; the agent then calls its HTTP API for conversion, OCR, redaction, signing, splitting, and merging.

Q: Do my documents get uploaded to a third party?

No. Stirling PDF is self-hosted, so files move only between your instance and your own server.

Q: How does the agent get a processed file back?

post-file uploads a document as multipart form data but prints the response with a 5 MB cap; post-save writes a response body to a path up to 50 MB but sends JSON rather than a file. Use an upload call that returns an identifier, then a JSON call with post-save to retrieve the result.

Reading a PDF and operating on one are different problems. Stirling PDF handles the second — split, merge, OCR, redact, sign, convert — on a server you own, called by your agent through a scoped client.

Why this belongs on a separate server

PDF operations are memory-hungry and bursty. OCR on a hundred-page scan, or rasterising a design-heavy document, will happily consume more RAM than an agent instance has to spare. Stirling PDF keeps that work on its own host: the instance holds a small HTTP client, and the spike lands where you sized for it.

The other reason is jurisdictional. Contracts, invoices, and identity documents are exactly the files people are least willing to post to a third-party API. Self-hosting removes the question entirely.

1. Run Stirling PDF with API access

Deploy Stirling PDF following the official API documentation, pin the image version, and expose it through an authenticated TLS reverse proxy. Confirm it answers before you connect anything:

# The status endpoint our connector probes on recent Stirling builds
curl -fsS https://stirling-pdf.example.com/api/v1/info/status

2. Connect it from Dashboard Tools

Open Dashboard Tools, select a running OpenClaw or Hermes instance, and connect the Stirling PDF card. The placeholder endpoint is https://stirling-pdf.example.com; add a scoped token if your proxy requires one. The connector installs a client plus a managed skill so the agent knows the endpoint and the safe call patterns. The client lives at a managed path — tools/dashboard-api-connectors/stirling-pdf/tool — and the examples below use tool as shorthand for it.

# Confirm the target without revealing the token
tool info

# Health and capability discovery
tool get /api/v1/info/status
tool discover /swagger-ui/index.html

Stirling publishes an OpenAPI surface, so discovery is genuinely useful here — the agent can read the available operations rather than guessing endpoint names.

3. Understand the two file calls before you design the flow

This is the part worth reading twice, because the two binary-capable calls do not compose the way you would expect:

post-file uploads a local document as multipart form data — but it prints the response, capped at 5 MB. It cannot write the result to disk.
post-save writes a response body to a path, up to 50 MB — but its request is JSON. It cannot upload a file.
The multipart field name the client sends is file. Stirling's own request model names the upload fileInput, so a direct one-shot upload-and-convert against an operation that expects fileInput will not bind.

The pattern that actually works is two calls: use an operation that accepts an upload and returns an identifier or URL, then fetch the processed result with a JSON call and post-save. For small text-shaped results — extracted metadata, page counts, a JSON report — post-file alone is fine, because printing is what you wanted anyway.

# Small, text-shaped result: printing is fine
tool post-file /api/v1/<category>/<operation> /path/to/input.pdf '{"field":"value"}'

# Retrieve a large processed result to disk
tool post-save /api/v1/<category>/<operation> '{"fileId":"..."}' /path/to/output.pdf

Stirling documents the shape as /api/v1/<category>/<operation> and treats its Swagger UI as the authoritative list — operation names and their field names change between versions. Read them from the discovery output rather than hardcoding a path from a blog post. Printed responses cap at 5 MB and saved bodies at 50 MB; the client sets a 120-second socket timeout, which bounds a stalled connection but not a server that keeps trickling bytes, so put a real request deadline on the Stirling side too.

Destructive operations need confirmation

Redaction, signing, page removal, and overwrite-in-place are not reversible in any way the agent can undo. Keep the source file intact and write results to a new path, and have the agent confirm before anything that changes a document a human will rely on. This is a place where an over-eager agent does real damage quietly.

Production hardening

Authenticate the endpoint; a PDF server that accepts arbitrary uploads is a file-processing service open to the internet.
Size the host for OCR peaks and cap request concurrency so one large scan cannot starve the rest.
Set retention on any temporary storage Stirling uses — processed copies of sensitive documents should not linger.
Log operations and file identifiers, never document contents.

Choosing between the document tools

Use MarkItDown when the agent needs to read a document, Stirling PDF when it needs to transform one, and PaddleOCR when the pages are scans and you want structured text extraction rather than a PDF-shaped result.

Frequently asked questions

Can an OpenClaw agent edit PDFs?

Yes, by connecting a Stirling PDF server. Stirling exposes a broad server-side PDF API — conversion, OCR, redaction, signing, splitting, merging — and the dashboard installs a scoped HTTP client so the agent can call it on your documents.

Do my documents get uploaded to a third party?

No. Stirling PDF is self-hosted, so documents go from your instance to your Stirling server and nowhere else. That is the main reason to choose it over a hosted PDF API for anything contractual, financial, or personal.

How does the agent get a processed file back?

Plan for it, because the two file calls do different halves of the job. post-file uploads a local document as multipart form data but prints the response, capped at 5 MB. post-save writes a response body straight to a path, up to 50 MB, but sends a JSON request rather than a file. So the reliable pattern is a Stirling flow where the upload returns an identifier or URL and a second JSON call retrieves the result.