Outil PDF

pdf analyse un ou plusieurs documents PDF et renvoie du texte.

Comportement rapide :

• Mode fournisseur natif pour les fournisseurs de modèles Anthropic et Google.
• Mode de repli par extraction pour les autres fournisseurs (extraire d’abord le texte, puis les images de pages si nécessaire).
• Prend en charge une entrée unique (pdf) ou multiple (pdfs), avec un maximum de 10 PDF par appel.

Disponibilité

L’outil n’est enregistré que lorsqu’OpenClaw peut résoudre une configuration de modèle compatible PDF pour l’agent :

1. agents.defaults.pdfModel
2. repli vers agents.defaults.imageModel
3. repli vers le modèle de session/par défaut résolu de l’agent
4. si les fournisseurs PDF natifs reposent sur l’authentification, les préférer aux candidats génériques de repli image

Si aucun modèle utilisable ne peut être résolu, l’outil pdf n’est pas exposé.

Notes de disponibilité :

• La chaîne de repli tient compte de l’authentification. Un provider/model configuré ne compte que si OpenClaw peut réellement authentifier ce fournisseur pour l’agent.
• Les fournisseurs PDF natifs sont actuellement Anthropic et Google.
• Si le fournisseur de session/par défaut résolu dispose déjà d’un modèle vision/PDF configuré, l’outil PDF le réutilise avant de se rabattre sur d’autres fournisseurs authentifiés.

Référence d’entrée

Notes d’entrée :

• pdf et pdfs sont fusionnés et dédupliqués avant le chargement.
• Si aucune entrée PDF n’est fournie, l’outil renvoie une erreur.
• pages est analysé comme des numéros de page commençant à 1, dédupliqués, triés et limités au nombre maximal de pages configuré.
• password s’applique à chaque PDF de la requête et n’est utilisé que par le mode de repli par extraction.
• maxBytesMb vaut par défaut agents.defaults.pdfMaxBytesMb ou 10.

Références PDF prises en charge

• chemin de fichier local (avec expansion de ~)
• URL file://
• URL http:// et https://
• références entrantes gérées par OpenClaw, comme media://inbound/<id>

Notes sur les références :

• Les autres schémas d’URI (par exemple ftp://) sont rejetés avec unsupported_pdf_reference.
• En mode bac à sable, les URL distantes http(s) sont rejetées.
• Lorsque la politique de fichiers limitée à l’espace de travail est activée, les chemins de fichiers locaux hors des racines autorisées sont rejetés.
• Les références entrantes gérées et les chemins rejoués sous le magasin de médias entrants d’OpenClaw sont autorisés avec la politique de fichiers limitée à l’espace de travail.

Modes d’exécution

Mode fournisseur natif

Le mode natif est utilisé pour les fournisseurs anthropic et google. L’outil envoie les octets PDF bruts directement aux API des fournisseurs.

Limites du mode natif :

• pages n’est pas pris en charge. S’il est défini, l’outil renvoie une erreur.
• password n’est pas pris en charge. Utilisez un modèle non natif pour analyser les PDF chiffrés.
• L’entrée multi-PDF est prise en charge ; chaque PDF est envoyé comme bloc de document natif / partie PDF intégrée avant le prompt.

Mode de repli par extraction

Le mode de repli est utilisé pour les fournisseurs non natifs.

Flux :

1. Extraire le texte des pages sélectionnées (jusqu’à agents.defaults.pdfMaxPages, valeur par défaut 20).
2. Si la longueur du texte extrait est inférieure à 200 caractères, convertir les pages sélectionnées en images PNG et les inclure.
3. Envoyer le contenu extrait avec le prompt au modèle sélectionné.

Détails du repli :

• L’extraction d’images de pages utilise un budget de pixels de 4,000,000.
• Les PDF chiffrés peuvent être ouverts avec le paramètre de premier niveau password.
• Si le modèle cible ne prend pas en charge l’entrée image et qu’il n’y a aucun texte extractible, l’outil renvoie une erreur.
• Si l’extraction de texte réussit mais que l’extraction d’images nécessiterait la vision sur un modèle texte uniquement, OpenClaw ignore les images rendues et continue avec le texte extrait.
• Le repli par extraction utilise le Plugin document-extract intégré. Le Plugin possède clawpdf, qui fournit l’extraction de texte et le rendu d’images via PDFium WebAssembly.

Configuration

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

Voir la référence de configuration pour le détail complet des champs.

Détails de sortie

L’outil renvoie le texte dans content[0].text et les métadonnées structurées dans details.

Champs details courants :

• model : référence de modèle résolue (provider/model)
• native : true pour le mode fournisseur natif, false pour le repli
• attempts : tentatives de repli ayant échoué avant la réussite

Champs de chemin :

• entrée PDF unique : details.pdf
• entrées PDF multiples : details.pdfs[] avec des entrées pdf
• métadonnées de réécriture du chemin en bac à sable (le cas échéant) : rewrittenFrom

Comportement en cas d’erreur

• Entrée PDF manquante : lève pdf required: provide a path or URL to a PDF document
• Trop de PDF : renvoie une erreur structurée dans details.error = "too_many_pdfs"
• Schéma de référence non pris en charge : renvoie details.error = "unsupported_pdf_reference"
• Mode natif avec pages : lève une erreur claire pages is not supported with native PDF providers

Exemples

PDF unique :

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

Plusieurs PDF :

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

Modèle de repli avec filtre de pages :

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

PDF chiffré avec repli par extraction :

{  "pdf": "/tmp/locked.pdf",  "password": "example-password",  "model": "openai/gpt-5.4-mini",  "prompt": "Summarize this contract"}

Connexe

• Vue d’ensemble des outils - tous les outils d’agent disponibles
• Référence de configuration - configuration pdfMaxBytesMb et pdfMaxPages