Paperclip : workflow multi-agent, guide 2026

Le guide Docker officiel de Paperclip conserve les données de l’application dans /paperclip et expose par défaut le service sur le port 3100 (documentation de déploiement Docker). Ce détail résume bien le produit : Paperclip est moins un agent supplémentaire qu’un plan de contrôle open source pour un workflow multi-agent. Cette semaine, vérifiez d’abord si vos tâches, vos sessions et vos secrets commencent réellement à se disperser. Si vous ne pilotez qu’un ou deux agents pour des demandes ponctuelles, restez sur le terminal ou un tableau de tâches. Si plusieurs agents travaillent durablement avec des validations, des budgets et des contextes persistants, Paperclip devient beaucoup plus pertinent.

Cette présentation s’adresse à trois profils :

les équipes qui coordonnent plusieurs instances de Claude Code, Codex ou d’autres agents personnalisés ;
les responsables qui veulent ajouter des budgets, des validations et une trace des décisions ;
les développeurs qui préparent l’auto-hébergement d’une plateforme de workflow multi-agent.

Le bon niveau de plateforme

Un plan de contrôle, pas un agent universel

Paperclip organise le travail autour d’entreprises ou d’organisations, de projets, d’agents, de tâches, de commentaires et de sessions persistantes. Le dépôt officiel le présente comme une application de gestion d’équipes d’agents, avec isolation des données entre plusieurs organisations sur une même instance (dépôt officiel et présentation du produit ; documentation produit).

La distinction est importante. Paperclip ne remplace pas nécessairement Claude Code, Codex ou un agent interne. Il leur fournit plutôt :

un espace de travail structuré ;
une file de tâches et des fils de discussion ;
un contexte de projet réutilisable ;
des déclenchements planifiés ou liés à des événements ;
une couche de suivi des exécutions ;
des règles d’accès, de budget et de validation.

Vous devez donc le comparer à un outil d’orchestration ou à un centre de contrôle, pas à un modèle de langage.

Un agent lancé dans un terminal peut produire une excellente réponse, mais il ne sait pas naturellement qui doit approuver la suite, quelle tâche dépend d’une autre, quelle limite budgétaire s’applique au projet ou quel contexte doit survivre à la fermeture du terminal. Paperclip intervient précisément sur ces zones.

Les limites d’une approche sans contrôle central

La gestion artisanale devient fragile pour au moins quatre raisons.

Première limite : la visibilité. Plusieurs terminaux ouverts ne constituent pas un historique exploitable. Vous pouvez perdre la relation entre une demande, la sortie produite, la correction demandée et la nouvelle exécution.

Deuxième limite : la continuité. Un agent qui dépend uniquement de l’historique local d’une session perd une partie de son contexte lorsque le processus s’arrête, que la machine redémarre ou que le projet change de répertoire.

Troisième limite : la gouvernance. Les limites de Paperclip, les règles d’approbation et la facturation du fournisseur de modèle sont trois sujets différents. Une enveloppe enregistrée dans Paperclip ne transforme pas automatiquement une facture externe en plafond contractuel.

Quatrième limite : les identifiants. Une clé injectée dans un agent atteint le processus qui exécute cet agent. Elle peut donc devenir visible dans les commandes, les journaux, les fichiers temporaires ou les sorties produites si l’agent ou son environnement se comporte mal.

Paperclip réduit le désordre organisationnel. Il ne supprime pas le risque propre à l’exécution d’un programme doté de privilèges.

La grille de choix

Avant d’installer quoi que ce soit, utilisez cette grille. Elle évite de transformer une demande ponctuelle en projet d’infrastructure.

Si vous lancez un agent pour une tâche unique, choisissez le terminal ou votre outil de suivi habituel. Paperclip ajouterait une couche de configuration sans résoudre un problème durable.
Si plusieurs agents partagent le même projet et doivent reprendre le travail après interruption, choisissez Paperclip. La persistance des tâches, des sessions et des contextes justifie alors la plateforme.
Si un responsable doit approuver certaines actions avant exécution, choisissez Paperclip avec un mode d’authentification adapté. Un simple script ne suffit généralement plus.
Si les agents utilisent des secrets différents selon le projet, choisissez Paperclip, mais concevez d’abord les droits minimaux et les rotations.
Si vous avez besoin d’un environnement toujours disponible, choisissez un serveur ou un Mac distant plutôt qu’un ordinateur portable personnel fréquemment suspendu.
Si l’agent doit accéder à du matériel local, à une interface audio ou à un logiciel graphique macOS, choisissez plutôt un Mac distant dédié. Paperclip peut organiser les tâches, mais il ne transforme pas un serveur générique en poste de production créative.

Le bon critère n’est donc pas le nombre exact d’agents. C’est la combinaison entre durée, dépendances, validation humaine, exposition des secrets et disponibilité de l’hôte.

Les profils d’équipe

Développeur individuel

Pour un développeur seul, Paperclip devient intéressant lorsque les tâches ne sont plus indépendantes. Vous pouvez, par exemple, demander à un agent d’analyser un dépôt, à un autre de préparer des tests, puis à un troisième de rédiger la documentation ou les notes de version.

Si chaque intervention reste courte et manuelle, un terminal avec des fichiers de contexte peut être plus rapide. Le coût caché de Paperclip se trouve dans la première configuration : instance, authentification, stockage, agents, environnements et règles d’exécution.

Votre décision doit donc dépendre de la répétition. Une plateforme se justifie lorsque vous voulez refaire le même circuit plusieurs fois, pas seulement lorsque vous voulez essayer un nouvel agent.

Équipe de projet logiciel

C’est le cas d’usage le plus naturel pour Paperclip. Les tâches deviennent des unités suivies plutôt que des conversations isolées. Les fils permettent de conserver les échanges liés à un sujet. Les sessions persistantes évitent de repartir de zéro après chaque interruption.

Les adaptateurs officiels relient Paperclip à plusieurs environnements, notamment claude_local pour Claude Code, codex_local pour Codex, opencode_local, cursor, process et http (vue d’ensemble des adaptateurs).

L’adaptation ne signifie pas que tous les agents disposent des mêmes capacités. Un adaptateur doit lancer le moteur, transmettre le contexte, récupérer la sortie et, lorsque cela est possible, interpréter l’utilisation ou le coût. Les prérequis d’authentification, les chemins de configuration et les modes d’exécution restent propres à chaque agent.

Pour Claude Code et Codex, la réponse est donc oui, mais avec une nuance essentielle : Paperclip les prend en charge par l’intermédiaire d’adaptateurs locaux. Vous devez encore gérer leur installation, leur connexion, leurs permissions et leur environnement d’exécution.

Élément	Claude Code	Codex	Conséquence pour votre équipe
Type d’adaptateur	`claude_local`	`codex_local`	Le choix se fait agent par agent
Mode local	Exécution de la ligne de commande sur l’hôte ou une cible gérée	Exécution de la ligne de commande sur l’hôte ou une cible gérée	L’hôte doit rester disponible
Configuration d’authentification	Configuration Claude et fichiers de session selon la cible	`auth.json`, connexion hôte ou clé liée à l’agent	Ne mélangez pas les modèles de credentials
Variables d’environnement	Prise en charge des références de secrets	Prise en charge des références de secrets	Préférez les références plutôt que les valeurs en clair
Limite principale	Les prérequis du moteur et de son compte restent externes	Paperclip ne devient pas le fournisseur de modèle	Budget interne et facture fournisseur restent séparés

Dans la documentation Codex, le fichier auth.json joue notamment un rôle dans la connexion de l’agent et peut être matérialisé dans un environnement géré (documentation de l’adaptateur Codex). Ne copiez donc pas une procédure d’authentification Claude dans un profil Codex, ou inversement.

Équipe produit ou opérationnelle

Le deuxième public concerne les agents qui ne produisent pas directement du code. Un agent peut préparer une synthèse client, un autre classer des demandes, un autre transformer un brief en storyboard vidéo ou en plan de production audio.

Dans ce contexte, l’organisation compte autant que le modèle. Vous devez pouvoir transmettre un objectif global à un projet, le diviser en tâches, attribuer chaque tâche au bon agent et conserver une trace des validations. Les déclenchements planifiés peuvent aider à lancer des travaux réguliers, mais ils ne constituent pas une garantie d’autonomie sans surveillance.

Un flux utile ressemble davantage à ceci :

un responsable définit l’objectif et les critères d’acceptation ;
un agent prépare une première analyse ;
un deuxième agent vérifie les données ou le format ;
une validation humaine autorise la publication ou l’action externe ;
Paperclip conserve les tâches et les décisions pour la prochaine itération.

Pour un studio audio ou vidéo, vous pouvez réserver un agent à la transcription, un autre au dérushage textuel et un troisième à la préparation des métadonnées. Le rendu final doit néanmoins rester soumis à une validation humaine, surtout si les agents manipulent des fichiers clients ou publient du contenu.

Équipe soumise à des contraintes

Les budgets et les validations deviennent déterminants lorsque les agents peuvent lancer des tâches coûteuses, modifier un dépôt sensible ou appeler des services externes.

Paperclip peut enregistrer les limites et les règles au niveau de l’organisation, du projet ou de l’agent. Cela vous donne une base de gouvernance. Toutefois, ne confondez pas cette limite applicative avec le plafond réel du fournisseur de modèle. Le fournisseur peut appliquer ses propres tarifs, quotas, restrictions de compte ou règles de facturation.

Le flux recommandé est le suivant :

définir une enveloppe interne par projet ;
associer chaque agent à un périmètre clair ;
exiger une approbation pour les actions irréversibles ;
conserver les sorties et les décisions ;
vérifier la consommation côté fournisseur ;
suspendre ou révoquer l’agent si son comportement sort du périmètre.

Paperclip peut aider à rendre ces opérations visibles. Il ne remplace ni votre contrat fournisseur ni votre procédure d’incident.

Le déploiement Docker

Une base persistante

Oui, Paperclip peut être déployé avec Docker. Le démarrage rapide officiel utilise un conteneur unique avec un répertoire persistant monté sur /paperclip. La documentation indique que cette zone peut contenir la base intégrée, les fichiers importés, la clé locale des secrets et les espaces de travail des agents (guide Docker officiel).

Le port interne documenté est 3100. Vous pouvez le publier sur un autre port côté hôte, mais cela ne change pas la nécessité de conserver le volume de données. Un conteneur supprimé sans sauvegarde peut emporter l’état de l’instance, les configurations et les informations nécessaires à la récupération des secrets.

Option	Atouts	Limites	Choix conseillé
Installation locale	Rapide pour tester un agent et comprendre l’interface	Disponibilité limitée, dépendance à votre session utilisateur	Essai individuel
Docker avec stockage local	Reproductible, isolable, facile à sauvegarder	Gestion du volume, des mises à jour et des clés	Petit serveur ou environnement de test
Docker avec base PostgreSQL	Séparation plus nette entre application et données	Administration supplémentaire	Équipe avec exploitation régulière
Mac distant	Accès à macOS, outils créatifs et environnements Apple	Coût d’hébergement, gestion des accès et de l’alimentation	Agents nécessitant macOS ou logiciels graphiques
Serveur Linux	Bon choix pour les services persistants et les tâches sans interface graphique	Moins adapté aux logiciels exclusivement macOS	Workflow backend ou CI

Le fichier Compose de démarrage prévoit également l’authentification et la persistance du répertoire de données (configuration Compose officielle). Pour un premier test, vous pouvez conserver une exposition privée. Pour un accès distant, définissez une URL publique cohérente et protégez l’instance derrière une authentification correctement configurée.

Une procédure d’installation maîtrisée

Voici une séquence prudente pour passer du test à un environnement stable.

Identifiez le dépôt exact. Utilisez paperclipai/paperclip. Le nom Paperclip peut aussi désigner des projets sans rapport, notamment des outils de recherche ou des bibliothèques portant un nom similaire.
Choisissez l’hôte. Prenez votre poste pour une démonstration courte, un serveur pour les agents backend persistants ou un Mac distant pour les workflows qui exigent macOS.
Préparez le stockage. Montez /paperclip dans un volume sauvegardé. Vérifiez que les sauvegardes couvrent aussi la clé maître des secrets.
Activez l’authentification. Utilisez un secret d’authentification robuste et ne laissez pas une instance de test exposée publiquement.
Installez les agents. Vérifiez séparément Claude Code, Codex ou vos exécutables personnalisés. Paperclip ne corrige pas un binaire absent ni une connexion expirée.
Créez un seul projet pilote. Commencez avec une tâche réversible, sans accès à des données sensibles.
Ajoutez les secrets par référence. Évitez les clés directement écrites dans les fichiers Compose, les scripts ou les descriptions de tâches.
Testez l’arrêt et la reprise. Arrêtez le conteneur, redémarrez-le, puis vérifiez la présence de la tâche, de la session et du contexte.
Ajoutez les validations. Bloquez les publications, les suppressions et les modifications externes jusqu’à ce que le flux soit documenté.
Mesurez avant d’élargir. Contrôlez les journaux, les échecs d’adaptateur, la consommation fournisseur et la durée de disponibilité de l’hôte.

Une instance opérationnelle n’est pas seulement une page web qui s’ouvre. Elle doit survivre à un redémarrage et permettre de comprendre ce qui s’est passé.

Les secrets et les permissions

La documentation officielle recommande de considérer tout secret lié à un agent comme exposé à cet agent. Paperclip peut stocker les secrets de manière chiffrée, imposer des références et injecter la valeur au moment de l’exécution, mais l’agent reçoit bien cette valeur dans son processus (documentation officielle des secrets).

Cette frontière doit guider votre architecture.

Vous pouvez créer un secret d’entreprise, puis le lier à une variable d’environnement d’un agent ou d’un projet. Le nom lisible du secret reste distinct de la clé d’environnement reçue par le processus. Un projet peut appliquer une variable à toutes ses exécutions, tandis qu’un agent peut recevoir une valeur plus spécifique.

Pour limiter le risque :

créez un jeton différent par projet lorsque le fournisseur le permet ;
accordez uniquement les permissions nécessaires ;
préférez les identifiants à durée de vie courte ;
évitez de donner un accès administrateur à un agent de génération de contenu ;
activez le mode strict pour empêcher certaines valeurs sensibles en clair ;
surveillez les journaux et les sorties susceptibles de contenir un secret ;
faites tourner les identifiants lorsqu’un transcript ou un espace de travail a pu les capturer.

Point de sécurité : le chiffrement du stockage protège la donnée au repos. Il ne garantit pas qu’un agent autorisé ne pourra jamais lire, imprimer, transmettre ou enregistrer la valeur après injection dans son environnement.

La clé maître locale doit être sauvegardée avec la base de données. Une sauvegarde de base sans cette clé ne suffit pas à déchiffrer les secrets ; une sauvegarde de clé sans les métadonnées de la base ne suffit pas non plus à reconstruire correctement les versions stockées (documentation sur la base et la persistance).

La décision de production

Votre équipe peut adopter Paperclip lorsque cinq conditions sont réunies :

les tâches doivent rester accessibles après la fin d’une session ;
plusieurs agents interviennent dans un même objectif ;
certaines actions exigent une validation ;
les credentials doivent être liés à un périmètre précis ;
l’hôte doit rester disponible pendant les exécutions.

Revenez à une solution plus simple si vos agents sont occasionnels, si chaque tâche est indépendante ou si vous n’avez pas encore défini les responsabilités humaines. Installer une plateforme avant d’avoir une procédure d’exploitation ne fait que déplacer le désordre.

Pour l’hôte, retenez cette logique :

poste local si vous explorez Paperclip et acceptez les interruptions ;
serveur distant si vos agents travaillent sur des dépôts, des API ou des tâches planifiées sans interface graphique ;
Mac distant si Claude Code, Codex ou vos outils d’automatisation doivent utiliser macOS, Xcode, des logiciels de design, des outils audio ou des applications vidéo ;
architecture séparée si le plan de contrôle et les agents ne doivent pas partager le même niveau de privilège.

Si vous préparez un environnement Mac distant, comparez la disponibilité réelle, la persistance des sessions et les règles d’accès avant de choisir une région. Vous pouvez consulter la présentation de VPSSpark, puis vérifier une option de Mac distant aux États-Unis si votre équipe veut tester un hôte macOS toujours accessible.

Paperclip ou solution plus simple

Paperclip apporte une vraie valeur quand le problème est organisationnel : contexte perdu, tâches mal attribuées, validations absentes, budgets difficiles à suivre et agents qui doivent reprendre un travail interrompu.

En revanche, il ne rend pas automatiquement vos agents fiables. Il ne remplace pas une revue de code, une stratégie de sauvegarde, un gestionnaire d’identités ni le suivi de consommation du fournisseur. Il ne promet pas non plus qu’un workflow pourra fonctionner sans surveillance humaine.

Le gain est donc maximal pour une équipe qui accepte de formaliser ses processus. Si vous refusez de définir les permissions, les critères d’acceptation et les responsables, Paperclip risque d’ajouter une interface sans apporter de contrôle réel.

À la date du 14 août 2026, cette analyse a été vérifiée à partir du dépôt officiel, des documents Docker, des pages consacrées aux adaptateurs, des instructions de persistance et de la documentation des secrets. Les adaptateurs, les modes d’authentification et les options de stockage peuvent évoluer avec les versions ; vérifiez le journal des versions officiel avant une mise en production (versions publiées du projet).

Si vous pilotez aujourd’hui plusieurs agents depuis des terminaux séparés, votre solution actuelle souffre probablement d’un contexte dispersé, d’une disponibilité irrégulière et d’un contrôle limité des secrets. Elle devient aussi difficile à auditer dès qu’une tâche doit être reprise ou approuvée par une autre personne. Dans ce cas, louer un Mac auprès de VPSSpark peut offrir un hôte plus stable pour tester Paperclip, maintenir les agents en ligne et séparer votre ordinateur personnel du workflow. Ce choix reste moins adapté aux charges longues nécessitant une architecture serveur spécialisée, ou aux équipes qui exigent un contrôle physique direct du matériel. Pour un besoin temporaire de calcul, de validation ou d’environnement Mac persistant, commencez par une petite expérience réversible avant de migrer l’ensemble de votre organisation.