Paperclip Tutorial: So baust du dein eigenes AI-Agenten-Team

Was du in diesem Tutorial lernst

In diesem Tutorial bauen wir gemeinsam ein komplettes AI-Agenten-Team mit Paperclip auf. Am Ende hast du ein laufendes System mit mehreren Agents, die koordiniert zusammenarbeiten – zum Beispiel für deinen eigenen Blog, ein SaaS-Projekt oder Content-Marketing.

Was du brauchst:

• Einen Computer mit Node.js 20+ installiert
• Claude Code oder ein anderer KI-CLI-Client (Codex, Aider, etc.)
• Einen gültigen API-Schlüssel (z.B. für Anthropic Claude API)
• Etwa 30 Minuten Zeit

Hinweis zu den Kosten: Paperclip selbst ist kostenlos (Open Source). Die Agents verbrauchen aber API-Tokens. Für dieses Tutorial solltest du mit etwa 5–10 € an Token-Kosten rechnen, je nach gewähltem Modell.

Schritt 1: Paperclip installieren

Öffne dein Terminal und führe den Onboarding-Befehl aus:

npx paperclipai onboard --yes

Das --yes Flag überspringt die interaktive Bestätigung und startet direkt mit den Standard-Einstellungen. Der Befehl lädt Paperclip herunter und startet den Setup-Wizard.

Du wirst durch folgende Schritte geführt:

1. Company Name – Gib deinem virtuellen Unternehmen einen Namen (z.B. "KI Blog GmbH")
2. Mission – Beschreibe in einem Satz, was dein Team tun soll
3. Adapter wählen – Wähle "Claude Code" als Standard-Adapter
4. API Key – Gib deinen Anthropic API-Schlüssel ein

Nach erfolgreichem Setup siehst du diese Ausgabe:

✓ Company "KI Blog GmbH" created
✓ Default adapter: Claude Code
✓ Dashboard available at http://localhost:4269

Öffne das Dashboard im Browser. Du siehst eine leere Übersicht – Zeit, dein Team aufzubauen.

Schritt 2: Deine Company definieren

Bevor du Agents erstellst, solltest du dir über die Struktur klar sein. Paperclip arbeitet mit einem Organigramm – genau wie ein echtes Unternehmen. Jeder Agent hat einen Vorgesetzten und kann Untergebene haben.

Für einen KI-Blog empfehle ich diese Struktur:

CEO (Strategie & Planung)
├── CTO (Technik & Code)
│   └── Dev (Implementierung)
├── Head of Content (Redaktionsplan)
│   └── SEO Writer (Artikel schreiben)
└── QA (Qualitätskontrolle)

Fange aber klein an. Starte mit dem CEO und füge nach und nach weitere Agents hinzu.

Schritt 3: Den CEO erstellen

Der CEO ist der wichtigste Agent. Er plant, priorisiert und delegiert Aufgaben an sein Team. Erstelle ihn über das Dashboard oder per CLI:

paperclip agent create \
  --name "CEO" \
  --role "Chief Executive Officer" \
  --adapter "claude-code" \
  --model "opus" \
  --budget 100000

Warum Opus für den CEO? Der CEO trifft strategische Entscheidungen: Welche Aufgaben haben Priorität? Wie sollen sie aufgeteilt werden? Welcher Agent ist am besten geeignet? Diese Entscheidungen erfordern das stärkste verfügbare Modell. Spare nicht am CEO – seine Qualität bestimmt die Qualität des gesamten Teams.

Das Budget von 100.000 Tokens ist ein guter Startwert. Der CEO verbraucht typischerweise mehr als andere Agents, weil er den Gesamtkontext verstehen muss.

Schritt 4: Den ersten Task erstellen und starten

Jetzt wird es spannend. Erstelle einen Task für deinen CEO:

paperclip task create \
  --title "Redaktionsplan erstellen" \
  --description "Erstelle einen Redaktionsplan mit 10 Artikeln für den KI Coach Blog. Themen: KI-News, Tutorials, Tool-Reviews. Plane Veröffentlichungsdaten für die nächsten 2 Wochen." \
  --assignee "CEO" \
  --priority "high"

Starte den Task:

paperclip task start --id 1

Beobachte im Dashboard, wie der CEO den Task bearbeitet. Du siehst in Echtzeit:

• Welche Dateien er anlegt oder ändert
• Welche Entscheidungen er trifft
• Wie viele Tokens er verbraucht

Tipp: Formuliere Tasks so spezifisch wie möglich. Statt "Mach was mit dem Blog" schreibe genau, was du erwartest, in welchem Format und bis wann.

Schritt 5: Weitere Agents einstellen

Sobald der CEO seinen Plan hat, braucht er ein Team zur Umsetzung. Erstelle weitere Agents:

CTO (technische Leitung)

paperclip agent create \
  --name "CTO" \
  --role "Chief Technology Officer" \
  --adapter "claude-code" \
  --model "sonnet" \
  --reports-to "CEO" \
  --budget 80000

Head of Content (Redaktion)

paperclip agent create \
  --name "Head of Content" \
  --role "Redaktionsleitung" \
  --adapter "claude-code" \
  --model "sonnet" \
  --reports-to "CEO" \
  --budget 60000

SEO Writer (Autor)

paperclip agent create \
  --name "SEO Writer" \
  --role "SEO-optimierte Artikel schreiben" \
  --adapter "claude-code" \
  --model "haiku" \
  --reports-to "Head of Content" \
  --budget 40000

Beachte die Modell-Strategie:

• CEO → Opus (stärkstes Modell, strategische Entscheidungen)
• CTO, Head of Content → Sonnet (gute Balance aus Qualität und Kosten)
• SEO Writer, Dev → Haiku (kostengünstig, für klar definierte Aufgaben)

Schritt 6: Best Practices

Nie mehr als 2 Agents gleichzeitig laufen lassen

Das ist die wichtigste Regel. Jeder aktive Agent verbraucht kontinuierlich Tokens durch Heartbeats und Task-Bearbeitung. Bei 3+ parallelen Agents explodieren die Kosten. Starte Tasks nacheinander oder höchstens paarweise.

# Gut: CEO plant, dann CTO implementiert
paperclip task start --id 1  # CEO plant
# Warte bis fertig
paperclip task start --id 2  # CTO implementiert

# Schlecht: Alle gleichzeitig
paperclip task start --id 1 --id 2 --id 3 --id 4  # 💸

Budget-Limits pro Agent setzen

Setze immer ein Token-Budget. Ohne Limit kann ein Agent in einer Endlosschleife Tausende von Tokens verbrennen. Starte konservativ und erhöhe bei Bedarf:

• CEO: 100.000 Tokens pro Task
• CTO/Heads: 80.000 Tokens pro Task
• Writer/Dev: 40.000 Tokens pro Task

Tasks klar und spezifisch formulieren

Schlechter Task:

"Mach den Blog besser"

Guter Task:

"Schreibe einen Artikel mit dem Titel 'KI für Freelancer' (mindestens 600 Wörter, Kategorie Tutorials, mit 3 H2-Überschriften, Code-Beispielen und Fazit). Speichere als Markdown in /content/articles/ki-fuer-freelancer.md"

Je präziser der Task, desto besser das Ergebnis und desto weniger Tokens werden verschwendet.

Agents pausieren wenn nicht gebraucht

# Agent pausieren (stoppt Heartbeats)
paperclip agent pause --name "SEO Writer"

# Wieder aktivieren
paperclip agent resume --name "SEO Writer"

Pausierte Agents verbrauchen keine Tokens. Aktiviere sie nur, wenn tatsächlich Tasks für sie anstehen.

Beispiel-Setup: KI-Blog Company

Hier ist mein konkretes Setup für den KI Coach Blog:

| Agent | Modell | Budget/Task | Aufgabe | |-------|--------|-------------|---------| | CEO | Opus | 100.000 | Strategie, Redaktionsplan, Qualitätskontrolle | | CTO | Sonnet | 80.000 | Blog-Technik, neue Features, Bug-Fixes | | Content Lead | Sonnet | 60.000 | Artikel planen, Briefings erstellen | | Writer | Haiku | 40.000 | Artikel nach Briefing schreiben | | SEO | Haiku | 30.000 | Meta-Tags, Keywords, Optimierung |

Typischer Workflow:

1. Ich erstelle einen Task für den CEO: "Plane 5 Artikel für nächste Woche"
2. CEO erstellt einen Redaktionsplan und delegiert an Content Lead
3. Content Lead erstellt Briefings für jeden Artikel und weist sie dem Writer zu
4. Writer schreibt die Artikel
5. SEO optimiert die Meta-Daten
6. CEO prüft die Ergebnisse

Kosten pro Woche: Etwa 15–25 € bei diesem Setup, abhängig von der Artikelanzahl und Komplexität.

Häufige Fehler und wie du sie vermeidest

Fehler 1: Heartbeat-Leerlauf

Problem: Agents wachen durch ihren Heartbeat-Mechanismus regelmäßig auf, prüfen ihren Status und verbrauchen dabei Tokens – auch wenn es nichts zu tun gibt. Bei 5 aktiven Agents über Nacht können das leicht 5–10 € unnötige Kosten sein.

Lösung: Pausiere alle Agents am Ende des Arbeitstages:

paperclip agent pause --all

Und aktiviere morgens nur die, die du brauchst.

Fehler 2: Zu viele Agents parallel

Problem: Du startest begeistert 4 Agents gleichzeitig. Innerhalb einer Stunde hast du 20 € verbrannt, und die Ergebnisse sind chaotisch, weil die Agents sich gegenseitig in die Quere kommen.

Lösung: Maximal 2 Agents gleichzeitig. Sequentielles Arbeiten ist fast immer effizienter als paralleles bei KI-Agents.

Fehler 3: CEO der selbst codet

Problem: Du weist dem CEO einen Implementierungs-Task zu. Er fängt an zu coden, anstatt zu delegieren – und verbraucht dabei die teuersten Opus-Tokens für Arbeit, die Haiku genauso gut erledigen könnte.

Lösung: Formuliere CEO-Tasks immer als Planungs- und Delegationsaufgaben, nie als Implementierungsaufgaben. Der CEO soll entscheiden was getan wird, nicht wie.

Fehler 4: Keine Budget-Limits

Problem: Ein Agent gerät in eine Schleife und verbraucht unbegrenzt Tokens.

Lösung: Setze immer ein Budget-Limit. Lieber zu niedrig starten und erhöhen als ungebremst laufen lassen.

Dashboard-Übersicht

Das Paperclip Dashboard zeigt dir auf einen Blick:

• Org-Chart – Dein Organigramm als interaktives Diagramm. Du siehst, welcher Agent wem unterstellt ist und wer gerade aktiv ist (grüner Punkt) oder pausiert (grauer Punkt)
• Agent-Karten – Jede Karte zeigt: Name, Rolle, Modell, Status, verbrauchtes Budget, letzter Heartbeat, aktiver Task
• Task-Board – Kanban-ähnliche Übersicht mit Spalten: Offen, In Arbeit, Erledigt, Fehlgeschlagen
• Kosten-Dashboard – Tägliche, wöchentliche und monatliche Kostenübersicht mit Breakdown pro Agent

Tipp: Schaue mindestens einmal pro Stunde auf das Kosten-Dashboard, wenn Agents aktiv sind. So erkennst du früh, wenn ein Agent ineffizient arbeitet.

Fazit

Paperclip macht Multi-Agent-Orchestrierung zugänglich und strukturiert. Mit dem richtigen Setup – CEO auf Opus, Team auf Sonnet/Haiku, klare Tasks, Budget-Limits – kannst du beeindruckende Ergebnisse erzielen.

Meine Empfehlung für den Einstieg:

1. Starte mit nur 2 Agents (CEO + ein Spezialist)
2. Lerne, wie Tasks, Budgets und Heartbeats funktionieren
3. Erweitere schrittweise auf 3–5 Agents
4. Pausiere immer, wenn du nicht aktiv überwachst

Paperclip ist kein "einrichten und vergessen"-Tool. Es ist ein mächtiges Werkzeug, das Aufmerksamkeit und klare Anweisungen braucht – genau wie ein echtes Team. Wer die Zeit investiert, wird mit einer Produktivität belohnt, die ein einzelner Agent nicht erreichen kann.