OpenClaw PDF-Tool: Dokumente effizient analysieren

Hand aufs Herz: PDFs programmatisch zu verarbeiten ist oft nervig. Entweder fehlen die richtigen Libraries oder das Modell versteht das Layout nicht, was die Datenextraktion zu einem Ratespiel macht.

Mit dem pdf Tool integrierst du Dokumenten-Analyse direkt in deinen Workflow. Es nimmt dir das mühsame Parsing ab und bereitet die Inhalte so vor, dass dein Modell sofort damit arbeiten kann.

PDF tool

pdf analysiert ein oder mehrere PDF-Dokumente und gibt Text zurück.

Kurzüberblick:

• Native Provider Mode für Anthropic und Google Modell-Provider.
• Extraction Fallback Mode für andere Provider (extrahiert zuerst Text, bei Bedarf dann Seitenbilder).
• Unterstützt einzelne (pdf) oder mehrere (pdfs) Eingaben, maximal 10 PDFs pro Aufruf.

Verfügbarkeit

Das Tool wird nur registriert, wenn OpenClaw eine PDF-fähige Modell-Konfiguration für den Agent auflösen kann:

1. agents.defaults.pdfModel
2. Fallback auf agents.defaults.imageModel
3. Fallback auf Best-Effort Provider-Defaults basierend auf der verfügbaren Authentifizierung

Wenn kein nutzbares Modell gefunden wird, ist das pdf Tool nicht sichtbar.

Eingabereferenz

• pdf (string): Ein PDF-Pfad oder eine URL.
• pdfs (string[]): Mehrere PDF-Pfade oder URLs, insgesamt bis zu 10.
• prompt (string): Analyse-Prompt, Standard ist Analyze this PDF document..
• pages (string): Seitenfilter wie 1-5 oder 1,3,7-9.
• model (string): Optionaler Modell-Override (provider/model).
• maxBytesMb (number): Größenbeschränkung pro PDF in MB.

Hinweise zur Eingabe:

• pdf und pdfs werden vor dem Laden zusammengeführt und Duplikate entfernt.
• Wenn keine PDF-Eingabe erfolgt, gibt das Tool einen Fehler aus.
• pages wird als 1-basierte Seitenzahlen interpretiert, dedupliziert, sortiert und auf die konfigurierte maximale Seitenzahl begrenzt.
• maxBytesMb nutzt standardmäßig agents.defaults.pdfMaxBytesMb oder 10.

Unterstützte PDF-Referenzen

• Lokaler Dateipfad (inklusive ~ Expansion).
• file:// URL.
• http:// und https:// URL.

Hinweise zu Referenzen:

• Andere URI-Schemata (zum Beispiel ftp://) werden mit unsupported_pdf_reference abgelehnt.
• Im Sandbox-Modus werden externe http(s) URLs abgelehnt.
• Wenn die Workspace-only File Policy aktiv ist, werden lokale Pfade außerhalb der erlaubten Roots abgelehnt.

Ausführungsmodi

Native Provider Mode

Der Native Mode wird für die Provider anthropic und google genutzt. Das Tool sendet die rohen PDF-Bytes direkt an die Provider-APIs.

Einschränkungen im Native Mode:

• pages wird nicht unterstützt. Falls gesetzt, gibt das Tool einen Fehler zurück.

Extraction Fallback Mode

Der Fallback Mode wird für Nicht-Native Provider verwendet.

Ablauf:

1. Text von den ausgewählten Seiten extrahieren (bis zu agents.defaults.pdfMaxPages, Standard 20).
2. Wenn die Länge des extrahierten Textes unter 200 Zeichen liegt, werden die Seiten als PNG-Bilder gerendert und beigefügt.
3. Der extrahierte Inhalt und der Prompt werden an das gewählte Modell gesendet.

Fallback-Details:

• Die Bildextraktion nutzt ein Pixel-Budget von 4,000,000.
• Wenn das Zielmodell keinen Image-Input unterstützt und kein extrahierbarer Text vorhanden ist, bricht das Tool mit einem Fehler ab.
• Der Extraction Fallback benötigt pdfjs-dist (und @napi-rs/canvas für das Rendering von Bildern).

Konfiguration

{
  agents: {
    defaults: {
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5-mini"],
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
    },
  },
}

Details zu den Feldern findest du in der Configuration Reference.

Ausgabe-Details

Das Tool gibt Text in content[0].text und strukturierte Metadaten in details zurück.

Gängige details Felder:

• model: Aufgelöste Modell-Referenz (provider/model).
• native: true für Native Provider Mode, false für Fallback.
• attempts: Fehlgeschlagene Fallback-Versuche vor dem Erfolg.

Pfad-Felder:

• Einzelne PDF-Eingabe: details.pdf.
• Mehrere PDF-Eingaben: details.pdfs[] mit pdf Einträgen.
• Sandbox Path Rewrite Metadaten (falls zutreffend): rewrittenFrom.

Fehlerverhalten

• Fehlende PDF-Eingabe: Wirft pdf required: provide a path or URL to a PDF document.
• Zu viele PDFs: Gibt strukturierten Fehler in details.error = "too_many_pdfs" zurück.
• Nicht unterstütztes Referenz-Schema: Gibt details.error = "unsupported_pdf_reference" zurück.
• Native Mode mit pages: Wirft den Fehler pages is not supported with native PDF providers.

Beispiele

Einzelne PDF:

{
  "pdf": "/tmp/report.pdf",
  "prompt": "Summarize this report in 5 bullets"
}

Mehrere PDFs:

{
  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
  "prompt": "Compare risks and timeline changes across both documents"
}

Fallback-Modell mit Seitenfilter:

{
  "pdf": "https://example.com/report.pdf",
  "pages": "1-3,7",
  "model": "openai/gpt-5-mini",
  "prompt": "Extract only customer-impacting incidents"
}

Verwandte Themen

• Tools Overview — Alle verfügbaren Agent-Tools.
• Configuration Reference — Details zu pdfMaxBytesMb und pdfMaxPages.

Nächste Schritte

• Schau dir an, wie du Modelle konfigurierst, um das Beste aus dem Native Mode rauszuholen.
• Erfahre mehr über die Sandbox-Umgebung, um lokale Dateien sicher zu verarbeiten.

AI Setup Assistant