Paperclip Multi-Agent Workflow: Komplettanleitung 2026

Das offizielle Repository von Paperclip weist bereits rund 67.900 GitHub-Sterne aus. (GitHub-Repository) Das ist kein Beweis für Produktreife, aber ein klares Signal für Aufmerksamkeit. Ihre Entscheidung für den Paperclip Multi-Agent Workflow sollte trotzdem nicht von Popularität abhängen: Nutzen Sie Paperclip erst dann, wenn mehrere Agenten, dauerhafte Aufgaben, Budgets oder Freigaben im Alltag unübersichtlich werden. Für einen einzelnen kurzfristigen Agenten ist ein Terminal oder eine einfache Aufgabenliste meistens schneller.

Diese Woche sollten Sie zuerst Ihre laufenden Agenten zählen, ihre Ausführungsdauer prüfen und alle benötigten Zugangsdaten dokumentieren. Liegen mehrere dauerhafte Prozesse, menschliche Freigaben und getrennte Projekte vor, testen Sie Paperclip in einer isolierten Umgebung. Andernfalls verschieben Sie die Plattformmigration und verbessern zunächst Ihre bestehende Einzel-Agent-Struktur.

Diese Anleitung richtet sich an Sie, wenn Sie mehrere Claude-Code-, Codex- oder eigene Agenten koordinieren, ein selbst gehostetes Multi-Agent-System planen oder Budget- und Sicherheitsregeln nachvollziehbar durchsetzen müssen. Wenn Sie nur gelegentlich einen Coding-Agenten starten, können Sie die Abschnitte zur Entscheidungshilfe direkt lesen und Paperclip wahrscheinlich überspringen.

Stand: 14.08.2026. Die Angaben wurden anhand des offiziellen Repositorys, der Adapter-Dokumentation, der Docker-Hinweise, der Secrets-Dokumentation und der veröffentlichten Versionshinweise geprüft.

1. Zuerst die Rolle von Paperclip richtig einordnen

Paperclip ist im Repository paperclipai/paperclip als Open-Source-Anwendung zur Verwaltung von Agenten positioniert. Die Plattform steht unter der MIT-Lizenz. (Offizielle Repository-Beschreibung) Gemeint ist nicht ein einzelnes Sprachmodell und auch kein eigenständiger Coding-Agent.

Die bessere technische Beschreibung lautet: Paperclip ist eine Kontroll- und Verwaltungsebene für Agententeams.

Die einzelnen Ausführungen erledigen angebundene Laufzeiten. Der offizielle Adapter-Überblick nennt unter anderem:

• Claude Code über claude_local
• Codex über codex_local
• OpenCode über opencode_local
• Cursor im Hintergrundmodus
• Pi und Hermes
• HTTP-Webhooks
• beliebige Shell-Prozesse über process
• externe Adapter als Plugins

Ein Adapter kennt die jeweilige Laufzeit, startet sie oder ruft einen Dienst auf, sammelt die Ausgabe und übergibt strukturierte Ergebnisse an Paperclip. (Offizielle Adapter-Dokumentation) Damit trennt das System die Organisation der Arbeit von der Ausführung des Agenten.

Diese Trennung ist der wichtigste Unterschied zu einem gewöhnlichen Agenten-Framework. Paperclip definiert nicht automatisch die beste Planung für Ihren Geschäftsprozess. Es stellt vielmehr Objekte und Regeln bereit, mit denen Sie Agenten, Aufgaben, Projekte, Zuständigkeiten und Laufzeitumgebungen verwalten.

2. Prüfen, ob Ihr Team überhaupt eine Kontrollebene braucht

Der Verwaltungsaufwand beginnt nicht bei der Installation. Er beginnt bei Rollen, Projekten, Adapterkonfiguration, Berechtigungen, Backups und der Überwachung des Hosts. Bei einem einzelnen Agenten kann das unnötige Reibung erzeugen.

Ein persönlicher Workflow ohne Paperclip ist häufig ausreichend, wenn:

• Sie nur eine Aufgabe nach der anderen bearbeiten.
• Agenten höchstens kurzzeitig laufen.
• keine menschliche Freigabe vor einem Schreib- oder Deploy-Schritt erforderlich ist.
• keine getrennten Projektkontexte existieren.
• Zugangsdaten ausschließlich lokal und manuell verwaltet werden.
• ein fehlgeschlagener Lauf keine dauerhaften Folgekosten erzeugt.

Paperclip wird interessanter, sobald mindestens drei Probleme gleichzeitig auftreten:

1. Mehrere Terminal-Sitzungen verlieren den Kontext.
   Ein Agent arbeitet in einem Fenster, ein zweiter Agent in einem anderen. Nach einigen Stunden ist unklar, welche Aufgabe bereits abgeschlossen wurde, welcher Prozess noch läuft und welche Änderung auf welcher Arbeitskopie basiert.

2. Aufgaben bleiben nicht dauerhaft nachvollziehbar.
   Ein Chatverlauf ist kein belastbarer Projektstatus. Für laufende Multi-Agent-Projekte benötigen Sie Status, Threads, Abhängigkeiten und wiederauffindbare Artefakte.

3. Freigaben werden informell.
   Wenn ein Agent Änderungen, Käufe, Deployments oder externe Nachrichten vorbereiten darf, reicht ein mündliches „Schauen Sie später darüber“ nicht aus. Sie benötigen eine sichtbare Entscheidungskette.

4. Kosten und Nutzung lassen sich schwer zuordnen.
   Paperclip kann Nutzungs- und Laufdaten aus Adaptern verarbeiten. Das bedeutet jedoch nicht, dass Paperclip die Rechnung des jeweiligen Modellanbieters ersetzt oder vollständig kontrolliert. Provider-Abrechnung und interne Budgetregeln sind zwei getrennte Ebenen.

5. Der Ausführungsort bleibt ständig online.
   Ein dauerhafter Agent benötigt nicht nur Software, sondern einen erreichbaren Host, stabile Netzwerkverbindungen, persistente Daten und einen kontrollierten Neustartprozess.

3. Die Architektur anhand Ihrer Teamgröße bewerten

Die folgende Tabelle ist keine Hersteller-Spezifikation, sondern eine Entscheidungshilfe für typische Einsatzsituationen. Die Bewertung bezieht sich auf den zusätzlichen Nutzen einer zentralen Kontrollebene.

Redaktionelle Bewertung: 4,2 von 5 Punkten für Teams mit dauerhaftem Multi-Agent-Betrieb; 2,0 von 5 Punkten für gelegentliche Einzelaufgaben. Die Abwertung kleiner Setups ist beabsichtigt. Mehr Plattformfunktionen lösen kein Problem, das noch nicht existiert.

4. Coding-Agenten mit Aufgaben, Threads und Kontext verbinden

Für ein Entwicklerteam liegt der praktische Vorteil nicht primär in einer schöneren Oberfläche. Entscheidend ist, dass ein Agentenlauf als Teil eines längeren Arbeitsobjekts behandelt wird.

Ein mögliches Muster sieht so aus:

1. Sie legen ein Projekt mit einem klar abgegrenzten Repository oder Arbeitsbereich an.
2. Sie definieren Agentenrollen, etwa Analyse, Implementierung, Test und Dokumentation.
3. Sie erstellen eine Aufgabe mit Ziel, Akzeptanzkriterien und benötigtem Kontext.
4. Paperclip weist die Aufgabe einem Adapter und damit einer Laufzeit zu.
5. Der Agent arbeitet in seinem vorgesehenen Workspace.
6. Ergebnisse, Kommentare, Statusänderungen und Artefakte bleiben dem Vorgang zugeordnet.
7. Ein weiterer Agent übernimmt erst nach einer klaren Übergabe oder nach erfüllter Abhängigkeit.

Die Adapter-Dokumentation beschreibt Heartbeats als Auslöser, bei denen Paperclip den Adaptertyp und die Konfiguration auflöst, die Laufzeit aufruft und das Ergebnis strukturiert verarbeitet. Das reduziert die Abhängigkeit von einzelnen Terminalfenstern.

Die Grenze bleibt wichtig: Paperclip garantiert nicht, dass Agenten eine gute technische Entscheidung treffen. Es stellt auch keine automatische Codeprüfung bereit. In der Produktdokumentation wird ausdrücklich zwischen Aufgaben- und Kommunikationsmodell einerseits sowie Chatbot oder Code-Review-Tool andererseits unterschieden. (Offizielle Produktdokumentation)

Für Claude Code und Codex bedeutet das konkret:

• Die jeweilige CLI muss am Ausführungsort verfügbar sein.
• Anmeldung und Provider-Berechtigung müssen funktionieren.
• Arbeitsverzeichnisse müssen korrekt erreichbar sein.
• Der Adapter muss zur installierten Paperclip-Version passen.
• Ein Fehler in der CLI-Umgebung erscheint nicht automatisch als Fehler in Ihrer fachlichen Aufgabenplanung.

Gerade der letzte Punkt wird häufig unterschätzt. Ein sauberer Task-Status kann neben einem fehlgeschlagenen Prozess stehen. Ihre Betriebsprüfung muss daher sowohl Paperclip als auch den Adapter und die eigentliche Agentenlaufzeit prüfen.

5. Cross-funktionale Agententeams mit Rollen statt Terminal-Chaos organisieren

Ein Multi-Agent-Team für Entwicklung, Marketing, Support oder Recherche benötigt andere Strukturen als drei parallele Coding-Prozesse. Die zentrale Frage lautet nicht nur „Welcher Agent ist verfügbar?“, sondern „Welche Rolle darf welches Ziel verfolgen?“

Eine sinnvolle Organisationsstruktur trennt:

• übergeordnete Ziele,
• Projekte und Verantwortungsbereiche,
• einzelne Aufgaben,
• Delegation,
• wiederkehrende Routinen,
• menschliche Freigaben.

Die Versionshinweise des Projekts dokumentieren unter anderem mehrstufige Review- und Freigabepolitiken sowie blockierende Aufgabenabhängigkeiten. Das ist für Teams relevant, in denen ein Agent nicht direkt vom Entwurf zur Veröffentlichung springen soll.

Beispiel:

1. Ein Recherche-Agent sammelt Quellen.
2. Ein Analyse-Agent strukturiert die Ergebnisse.
3. Ein Schreib-Agent erstellt einen Entwurf.
4. Ein Mensch prüft Fakten, Tonalität und Rechte.
5. Ein Veröffentlichungs-Agent übernimmt erst nach der Freigabe.

Das ist eine kontrollierte Übergabe. Es ist keine Garantie für einen unbeaufsichtigten Betrieb. Auch wenn Routinen und Heartbeats vorhanden sind, bleiben externe Dienste, Prompt-Injection, fehlerhafte Annahmen, kaputte Zugangsdaten und unvollständige Ergebnisse reale Risiken.

Paperclip hilft dabei, diese Risiken sichtbar zu machen. Es beseitigt sie nicht.

6. Budgets, Freigaben und Modellkosten sauber trennen

Für Management-Teams ist die Budgetfunktion nur dann nützlich, wenn Sie ihre Bedeutung korrekt abgrenzen.

Paperclip kann interne Regeln, Laufdaten und Freigabeprozesse abbilden. Ein gesetztes Limit in der Plattform ist aber nicht automatisch identisch mit einer harten Ausgabenbremse beim Modellanbieter. Der Anbieter kann Gebühren nach eigenen Zählweisen, Konten und Abrechnungszeiträumen berechnen.

Sie sollten deshalb drei Ebenen getrennt dokumentieren:

• Interne Planung: Welches Team oder Projekt darf wie viele Läufe starten?
• Technische Durchsetzung: Verhindert Paperclip einen weiteren Lauf oder verlangt es eine Freigabe?
• Provider-Abrechnung: Welche Kosten entstehen beim jeweiligen Modell- oder API-Anbieter?

Diese Trennung verhindert eine gefährliche Fehlannahme: Ein Paperclip-Budget schützt nicht automatisch vor allen Providerkosten. Es muss mit Provider-Limits, API-Schlüsseln mit eingeschränkten Rechten und regelmäßiger Abrechnungskontrolle kombiniert werden.

Für produktive Teams sind Freigabestufen besonders wichtig bei:

• Änderungen an Produktionscode,
• externen E-Mails oder Veröffentlichungen,
• kostenpflichtigen API-Aufrufen,
• Zugriff auf Kundendaten,
• Infrastrukturänderungen,
• Lösch- oder Migrationsvorgängen.

7. Docker und dauerhafte Daten korrekt planen

Paperclip kann mit Docker betrieben werden. Die offizielle Entwicklungsdokumentation zeigt sowohl docker run als auch eine Compose-Variante und weist auf das Persistieren des Verzeichnisses /paperclip hin. (Offizielle Docker- und Entwicklungsdokumentation)

Für einen Test genügen fünf Schritte:

1. Klonen Sie das offizielle Repository und prüfen Sie die gewünschte Version.
2. Erstellen Sie ein separates Datenverzeichnis außerhalb des kurzlebigen Containers.
3. Starten Sie Paperclip mit einem persistenten Mount für /paperclip.
4. Führen Sie das Onboarding aus und kontrollieren Sie den tatsächlich verwendeten Instanzpfad.
5. Starten Sie einen ungefährlichen Test-Agenten ohne produktive Zugangsdaten.

Für einen produktionsnahen Test ergänzen Sie:

• Reverse Proxy oder internes Netzwerksegment,
• Authentifizierung,
• regelmäßige Datenbank-Backups,
• Wiederherstellungstest,
• getrennte Arbeitsbereiche,
• Protokollrotation,
• Prozessüberwachung,
• feste Version statt unkontrolliertem latest-Tag.

Die offizielle lokale Verzeichnisstruktur umfasst unter anderem Konfiguration, eingebettete PostgreSQL-Daten, Uploads, Backups, Logs, Arbeitsbereiche und den Schlüssel für lokal verschlüsselte Secrets. Ein Backup nur der Datenbank reicht daher nicht aus, wenn der zugehörige Verschlüsselungsschlüssel fehlt.

Ein praktischer Docker-Fallstrick ist der Container-Benutzer. Ein öffentlich dokumentiertes GitHub-Issue beschreibt Probleme, wenn der Container als root läuft und der Claude-Adapter dadurch nicht wie erwartet funktioniert. (Dokumentierter Docker- und Claude-Adapter-Fehler) Prüfen Sie deshalb vor dem eigentlichen Agententest Benutzerrechte, Schreibrechte und die Identität des Prozesses.

8. Secrets so behandeln, als würde der Agent sie sehen

Paperclip verschlüsselt lokale Secrets standardmäßig mit einem lokalen Master-Key. Die Dokumentation beschreibt außerdem Bindings, Versionen, externe Referenzen und einen Strict Mode für sensible Variablen. (Offizielle Secrets-Dokumentation)

Der entscheidende Sicherheitsgrundsatz lautet jedoch: Sobald Sie ein Secret an einen Agenten binden, müssen Sie davon ausgehen, dass der Agent es verwenden und möglicherweise indirekt offenlegen kann.

Das bedeutet:

• Keine globalen API-Schlüssel für alle Agenten verwenden.
• Nur die für eine Aufgabe erforderlichen Variablen binden.
• Wenn möglich kurzlebige oder eingeschränkte Tokens einsetzen.
• Secrets nicht in Prompts oder frei lesbare Konfigurationsdateien schreiben.
• Rotation einplanen, wenn ein Transcript, Log oder nachgelagertes System den Wert gesehen haben könnte.
• Den Host selbst als Vertrauensgrenze behandeln.

Die Adapter-Sicherheitsdokumentation empfiehlt, Secrets über die Prozessumgebung statt über Prompt-Inhalte bereitzustellen. Sie warnt außerdem davor, Agentenausgaben blind als vertrauenswürdig zu behandeln. (Offizielle Adapter-Sicherheitsrichtlinien) Das ist besonders relevant bei externen Dokumenten, Webseiten, Pull Requests und automatisch eingelesenen Tickets.

Für die DSGVO- beziehungsweise GDPR-Bewertung müssen Sie zusätzlich klären:

• Welche personenbezogenen Daten in Aufgaben und Transcripts landen.
• In welchem Rechenzentrum der Agent ausgeführt wird.
• Welche Provider die Daten verarbeiten.
• Wie lange Logs und Artefakte gespeichert bleiben.
• Wer Zugriff auf Backups und Master-Keys besitzt.

9. Mit dieser Entscheidungslogik vom Test zur Produktion gehen

Nutzen Sie folgende Bedingungen. Sie verhindern, dass Sie eine Plattform nur wegen ihrer Funktionsliste einführen.

• Wenn Sie nur einen Agenten für einzelne Aufgaben starten, bleiben Sie zunächst beim Terminal oder einer einfachen Aufgabenverwaltung.
• Wenn mehrere Agenten über wiederkehrende Projekte hinweg arbeiten, testen Sie Paperclip mit nicht sensitiven Daten.
• Wenn Aufgaben länger als eine Sitzung bestehen bleiben müssen, bevorzugen Sie eine Umgebung mit persistentem Speicher und stabiler Netzwerkverbindung.
• Wenn menschliche Freigaben vor externen Aktionen notwendig sind, prüfen Sie Paperclip als Kontrollebene.
• Wenn Agenten produktive Secrets benötigen, führen Sie zuerst Secret-Bindings, Rotation und minimale Berechtigungen ein.
• Wenn der Host nicht dauerhaft online sein kann, planen Sie keinen Heartbeat-basierten Dauerbetrieb auf diesem Gerät.
• Wenn Sie physische Apple- oder macOS-Schnittstellen benötigen, ist ein Remote-Mac geeigneter als ein beliebiger Linux-Server.
• Wenn Ihre Workloads dauerhaft schwer und planbar sind, kann ein eigener Server wirtschaftlicher sein als eine flexible Mietumgebung.
• Wenn Sie nur für einen begrenzten Zeitraum testen, ist eine gemietete, isolierte Umgebung oft schneller als der Kauf und die Einrichtung zusätzlicher Hardware.

Für lokale Tests eignet sich ein Mac, den Sie selbst kontrollieren und während des Versuchs online halten. Für ein Team mit festen Wartungsfenstern kann ein eigener Server die bessere Wahl sein. Für kurzfristige Experimente, wechselnde Agentenanzahl oder einen externen Zugriff ohne Hardwarekauf kann ein gemieteter Remote-Mac sinnvoll sein. Informationen zu den verfügbaren VPSSpark-Standorten finden Sie beispielsweise auf der Übersicht der US-Ost-Umgebung.

10. Die häufigsten Fehlentscheidungen vor dem produktiven Start

Erstens: Paperclip mit einem Agenten-Framework verwechseln.
Paperclip organisiert Agenten. Es macht aus einem schwachen Agenten keinen zuverlässigen Prozess und ersetzt keine fachliche Qualitätskontrolle.

Zweitens: den Container ohne persistente Daten starten.
Nach einem Neustart fehlen dann je nach Setup Daten, Arbeitsbereiche oder Konfiguration. Testen Sie Wiederherstellung, nicht nur den ersten Start.

Drittens: Budgetkontrolle mit Provider-Abrechnung gleichsetzen.
Interne Limits und externe Gebühren müssen separat überwacht werden.

Viertens: Secrets zu breit binden.
Ein Agent für Dokumentation benötigt normalerweise keinen Produktionsschlüssel. Begrenzen Sie Zugriff nach Agent, Projekt und Aufgabe.

Fünftens: Dauerbetrieb ohne Host-Planung.
Ein geplanter Agent benötigt einen erreichbaren Rechner, stabile Laufzeit, Speicher, Logs und einen Neustartplan. Ein geschlossenes Notebook ist keine Produktionsinfrastruktur.

11. Ihr Fazit für die Auswahl der Infrastruktur

Paperclip lohnt sich nicht, weil es mehrere Agenten in einer Oberfläche zeigt. Es lohnt sich, wenn Sie die Folgen paralleler Agentenarbeit kontrollieren müssen: Aufgaben bleiben sichtbar, Rollen werden trennbar, Freigaben werden nachvollziehbar und Laufzeitdaten erhalten einen gemeinsamen Kontext.

Wenn Sie heute nur einzelne Claude-Code- oder Codex-Aufgaben ausführen, ist eine direkte lokale Arbeitsweise meist schlanker. Sobald jedoch mehrere Agenten dauerhaft Projekte bearbeiten, Secrets benötigen und vor bestimmten Aktionen auf eine Entscheidung warten müssen, wird die fehlende Kontrollebene selbst zum Betriebsrisiko.

Ein klassischer Server ist für dauerhaft planbare, Linux-kompatible Lasten oft die nüchternere Lösung. Ein lokaler Mac ist angenehm für Entwicklung, aber für dauerhafte Agentenläufe anfällig für Schlafmodus, Netzwechsel und persönliche Nutzung. Ein gemieteter Mac kann diese Nachteile für zeitlich begrenzte Tests oder Mac-spezifische Workflows reduzieren, ohne dass Sie sofort Hardware kaufen und selbst warten müssen. Prüfen Sie vorab trotzdem Datenschutz, Standort, Zugriffsschutz und die Anforderungen Ihrer Agenten. Für einen strukturierten Einstieg können Sie die Informationen zu VPSSpark sowie den direkten Kontakt zur Infrastrukturplanung heranziehen.

Der sinnvollste nächste Schritt ist kein unkontrollierter Produktivstart. Erstellen Sie eine kleine Testorganisation, verbinden Sie zunächst einen Claude-Code- oder Codex-Agenten, verwenden Sie nicht sensitive Secrets und simulieren Sie eine Freigabe. Wenn Aufgabenstatus, Persistenz und Hostbetrieb danach tatsächlich Zeit sparen, skalieren Sie auf weitere Agenten und definieren erst dann Ihre produktiven Sicherheits- und Budgetregeln.