ClawdDotNet/docs/InstanceSetupGuide.md

ClawdDotNet – Instanz-Setup-Guide

Anleitung für die vollständige Planung, Erstellung und Konfiguration einer neuen ClawdDotNet-Instanz. Richtet sich an menschliche Nutzer und AI-Agenten gleichermaßen.

---

1. Planung: Was soll die Instanz leisten?

Bevor eine Instanz erstellt wird, muss klar definiert werden:

Frage	Beispiel
Welche Aufgabe(n) soll die Instanz als Ganzes erledigen?	"Social-Media-Monitoring mit automatischer Zusammenfassung"
Wie viele Agenten werden benötigt?	So viele, wie es Zuständigkeiten gibt — die Kosten stecken in den Verbindungen, nicht in der Zahl
Welche externen Systeme sind beteiligt?	Telegram, E-Mail, Datenbank, APIs
Wie hoch ist das Token-Budget pro Tag?	z.B. $1/Tag, $10/Tag
Soll die Instanz autonom arbeiten oder manuell getriggert werden?	Cron-Jobs vs. manueller Start

Agentenanzahl richtig wählen

Geändert am 2026-09-21. Hier stand: „Mehr als 5 Agenten — kritisch hinterfragen, Koordinationsoverhead steigt quadratisch." Die Beobachtung stimmt, die Folgerung war falsch. Quadratisch steigen die Verbindungen, nicht die Agenten. Eine Instanz, die einen Onlinehandel betreibt, braucht Einkauf, Buchhaltung, Marketing und Logistik mit je mehreren Agenten — fünf reichen dafür nicht annähernd. Das Ziel von ClawdDotNet sind 50 bis 100 Agenten, die geordnet zusammenarbeiten. Die Begründung und was dafür fehlt: Organisation-Konzept.

Szenario	Empfehlung
Eine klar abgegrenzte Aufgabe	1 Agent
Aufgabe mit getrennten Zuständigkeiten (z.B. Recherche + Bericht)	2–3 Agenten
Ein Fachgebiet mit mehreren Teilaufgaben	So viele Agenten wie Teilaufgaben, plus eine Leitung
Mehrere Fachgebiete	Je Gebiet eine Einheit mit eigener Leitung; die Leitungen reden miteinander, die Mitglieder nicht

Die Faustregel gilt weiter, aber sie zielt auf etwas anderes: Jede Nachricht zwischen zwei Agenten kostet auf beiden Seiten einen Lauf. Zwei Agenten, die drei Nachrichten tauschen, sind sechs Läufe. Teuer wird also nicht der elfte Agent, sondern der elfte Agent, der jeden anderen ansprechen darf.

Deshalb ist die eigentliche Entwurfsfrage nicht „wie viele Agenten?", sondern „wer muss mit wem reden?" Ein Agent, der drei Nachbarn und eine Leitung kennt, kostet gleich viel, ob die Instanz zehn oder hundert Agenten hat. Ein Agent, der eine Liste aller hundert bekommt, kostet bei jedem Blick in diese Liste.

Bis die Strukturen aus dem Organisation-Konzept gebaut sind, ist das Adressbuch flach: list_agents zeigt jedem Agenten alle anderen. Bei mehr als etwa zehn Agenten heißt das, AgentComm nur den Agenten zu geben, die es wirklich brauchen — und den übrigen die Zusammenarbeit über das Taskboard zu geben, das keine Gegenseite wachhält.

---

2. Verzeichnisstruktur einer Instanz

Eine Instanz hat folgende Struktur. CreateInstance() und CreateAgent() im InstanceDirectoryManager erzeugen diese automatisch.

Instance-{Name}/
├── InstanceSettings.json          ← Instanz-Konfiguration + API-Key
├── TokenUsage.json                ← Verbrauchsprotokoll (leer bei Start)
├── state.db                       ← SQLite StateStore (wird zur Laufzeit erzeugt)
└── Agents/
    ├── AgentList.json             ← Agenten-Register (Name, Beschreibung, Ordner)
    ├── SharedWorkspace/           ← Geteilter Arbeitsbereich
    │   └── coordination/          ← Status-Dateien für Inter-Agenten-Kommunikation
    └── Agent-{Name}/
        ├── AgentSettings.json     ← Agent-Konfiguration (Modell, Tools, Scheduler)
        ├── Identity.md            ← WER ist der Agent (Rolle, Expertise)
        ├── Soul.md                ← WIE arbeitet der Agent (Persönlichkeit, Methodik)
        ├── ChatContext.json       ← Aktueller Konversationskontext
        ├── ChatHistory.json       ← Vollständiger Chatverlauf
        ├── Logs/                  ← Agent-spezifische Logs
        └── Workspace/             ← Persönlicher Arbeitsbereich

---

3. Schritt-für-Schritt: Instanz erstellen

3.1 Instanz anlegen

Über die UI: Instanz-Manager → Neue Instanz erstellen

Oder manuell die Ordnerstruktur erzeugen. Die InstanceSettings.json hat dieses Format:

{
  "instanceId": "<8-Zeichen-GUID>",
  "instanceName": "MeinProjekt",
  "openRouterApiKey": "",
  "workingDirectory": "",
  "logDirectory": "",
  "backupDirectory": "",
  "autoBackupEnabled": false,
  "autoBackupTime": "03:00",
  "backupKeepCount": 14,
  "webServerPort": 7001,
  "agents": [],
  "services": []
}

Wichtig: Der openRouterApiKey muss gesetzt werden, bevor Agenten funktionieren.

Protokoll und Sicherungen gehören der Instanz

logDirectory und backupDirectory leer zu lassen ist der Normalfall und nicht die Ausnahme: Leer heißt <Instanzverzeichnis>/Logs beziehungsweise <Instanzverzeichnis>/Backups.

Beides stand bis #528 (Stufe 1) in den anwendungsweiten Einstellungen und galt damit für jede Instanz — in Startup.log standen abwechselnd Zeilen zweier Instanzen, ohne Kennzeichnung, welche gerade spricht.

Ein eingetragener Wert geht vor und zählt, wenn er relativ ist, gegen das Instanzverzeichnis — nicht gegen das Arbeitsverzeichnis des Prozesses. Ein systemd-Dienst ohne WorkingDirectory= startet in /, und "./Logs" zeigte dort auf /Logs.

Zwei Instanzen sollten sich kein Sicherungsverzeichnis teilen. Die Aufbewahrung (backupKeepCount) räumt dort nach dem Präfix backup_<Instanzname>_ auf, und ein Präfix ist keine Grenze: Das Archiv der Instanz Test_2 fängt mit backup_Test_ an und wird von Test mitgezählt.

Wer die fünf Schlüssel noch in seiner alten Settings.json stehen hat, findet beim nächsten Start eine Warnung im Protokoll; übernommen werden sie nicht — ein Pfad für alle Instanzen wäre genau der Zustand, den die Trennung beseitigt.

3.2 Agenten anlegen

Pro Agent wird ein Ordner Agent-{Name} unter Agents/ erstellt.

AgentList.json — Register aller Agenten:

{
  "agents": [
    {
      "name": "Analyst",
      "description": "Recherchiert und analysiert Daten aus externen Quellen",
      "folderName": "Agent-Analyst"
    },
    {
      "name": "Reporter",
      "description": "Erstellt Berichte und versendet sie per E-Mail",
      "folderName": "Agent-Reporter"
    }
  ]
}

3.3 AgentSettings.json

Jeder Agent bekommt eine AgentSettings.json:

{
  "agentId": "analyst",
  "displayName": "Analyst",
  "model": "google/gemini-2.5-flash",
  "systemPrompt": "",
  "tools": {
    "WebFetch": {
      "allowedDomains": ["example.com", "api.example.com"]
    },
    "FileRW": {
      "sharedAccessLevel": "ReadWrite",
      "personalAllowedExtensions": [".txt", ".json", ".md", ".csv"],
      "sharedAllowedExtensions": [".txt", ".json", ".md"]
    }
  },
  "scheduler": {
    "cron": "0 8 * * 1-5",
    "runOnStart": false,
    "taskMessage": "Recherchiere die neuesten Daten und speichere sie im SharedWorkspace."
  },
  "toolJobs": [],
  "loopGuard": {
    "maxSteps": 15,
    "maxTokens": 50000,
    "timeoutSeconds": 300,
    "maxContextTokens": 100000,
    "compactionThreshold": 0.8
  }
}

3.4 Identity.md schreiben

Definiert WER der Agent ist. Kurz, prägnant, rollenspezifisch.

# Analyst

Du bist ein Datenanalyst im ClawdDotNet-Team "MeinProjekt".

## Rolle
- Recherche und Aufbereitung externer Daten
- Ergebnisse im SharedWorkspace als JSON ablegen

## Expertise
- Web-Recherche, Datenextraktion, strukturierte Zusammenfassungen

## Kontext
- Deine Ergebnisse werden vom Reporter-Agenten weiterverarbeitet
- Lege Dateien im SharedWorkspace unter coordination/ ab

3.5 Soul.md schreiben

Definiert WIE der Agent arbeitet.

# Arbeitsweise

## Persönlichkeit
- Gründlich und faktenbasiert
- Komprimiert Informationen auf das Wesentliche

## Methodik
1. Quellen prüfen und Daten abrufen
2. Relevante Informationen extrahieren
3. Strukturiertes JSON erstellen
4. Im SharedWorkspace ablegen

## Ausgabeformat
- Ergebnisse immer als JSON mit Timestamp
- Keine Prosa, nur strukturierte Daten

---

4. Modellwahl: Kosten vs. Leistung

Die Modellwahl hat den größten Einfluss auf die laufenden Kosten. Nicht jeder Agent braucht das teuerste Modell.

Modell-Empfehlungen nach Aufgabentyp

Aufgabentyp	Empfohlenes Modell	Kosten (ca.)	Begründung
Einfache Routineaufgaben (Dateien verschieben, Status prüfen, weiterleiten)	google/gemini-2.5-flash	~$0.15/M input	Schnell, günstig, zuverlässiger Tool-Use
Textverarbeitung (Zusammenfassungen, Berichte, E-Mails)	google/gemini-2.5-flash oder anthropic/claude-haiku-4-5	$0.15–0.80/M input	Gutes Preis/Leistungs-Verhältnis
Analyse & Reasoning (Datenanalyse, Entscheidungen, komplexe Logik)	anthropic/claude-sonnet-4-5	~$3/M input	Starkes Reasoning bei akzeptablen Kosten
Koordinator-Agent (orchestriert andere, trifft Entscheidungen)	anthropic/claude-sonnet-4-5	~$3/M input	Braucht gutes Verständnis der Gesamtsituation
Maximale Qualität (kritische Entscheidungen, kreative Aufgaben)	anthropic/claude-opus-4	~$15/M input	Nur wenn Qualität wichtiger als Kosten
Budget-Minimum	google/gemini-2.5-flash-lite	~$0.02/M input	Für einfachste Aufgaben, schlechterer Tool-Use

Kostenberechnung

Kosten pro Run ≈ (Input-Tokens × Inputpreis) + (Output-Tokens × Outputpreis)

Beispiel: Gemini 2.5 Flash, typischer Run (5000 in, 1000 out):
  = 5000 × $0.00000015 + 1000 × $0.0000006
  = $0.00075 + $0.0006
  = $0.00135 pro Run

Beispiel: Claude Sonnet, typischer Run (5000 in, 1000 out):
  = 5000 × $0.000003 + 1000 × $0.000015
  = $0.015 + $0.015
  = $0.03 pro Run

Cron alle 5 Minuten mit Gemini Flash: 288 Runs/Tag × $0.00135 = **$0.39/Tag** Cron alle 5 Minuten mit Claude Sonnet: 288 Runs/Tag × $0.03 = **$8.64/Tag**

LoopGuard für Kostenkontrolle anpassen

Szenario	maxSteps	maxTokens	timeoutSeconds
Einfache Routine	5–10	20.000	120
Standard-Aufgabe	10–20	50.000	300
Komplexe Analyse	20–30	80.000	600
Budget-kritisch	3–5	10.000	60

---

5. Tool-Zuweisung

Verfügbare Tools

Tool	Zweck	Benötigte Config	Background Jobs
FileRW	Dateien lesen/schreiben im Workspace	(optional) sharedAccessLevel, allowedExtensions	Nein
Database	SQL/NoSQL-Zugriff	type, connectionString	Nein
Mail	E-Mails senden/empfangen	smtpHost, imapHost, username, password	Ja: mail_check_unread
Telegram	Telegram-Nachrichten	botToken	Ja: telegram_poll
WebFetch	Webseiten/RSS abrufen	allowedDomains	Nein
WebMonitor	Webseiten auf Änderungen prüfen	monitors (mit url, parser, idPattern)	Nein
FTP	Datei-Upload/Download	host	Nein
DirectAPI	Finanzdaten (Aktien, Crypto, Forex)	providers (mit apiKey pro Provider)	Nein
SocialMediaManager	X, Reddit, YouTube-Transkripte	(je nach Aktion) xApiKey, openRouterApiKey	Ja: sm_yt_monitor, sm_transcript_notifier
AgentComm	Nachrichten an andere Agenten senden	(keine)	Nein
AgentSpawn	Andere Agenten starten und beauftragen	(keine)	Nein

Zuweisungsregeln

1. Minimalprinzip: Nur Tools zuweisen, die der Agent tatsächlich braucht
2. Tool = Berechtigung: Ein Tool in tools aufzunehmen gewährt sofort Zugriff (PermissionGate prüft nur Existenz im Dictionary)
3. Config = Sicherheitsgrenze: allowedDomains, allowedTables, allowedRecipients etc. sind die echten Einschränkungen
4. AgentComm/AgentSpawn: Nur dem Koordinator-Agenten zuweisen, nicht jedem
5. Tool Jobs prüfen: Ein ToolJob funktioniert nur wenn der Agent das Tool auch zugewiesen hat — die Laufzeitprüfung deaktiviert den Job sonst automatisch

Typische Tool-Kombinationen

Agenten-Rolle	Tools
Koordinator	FileRW, AgentComm, AgentSpawn
Recherche-Agent	FileRW, WebFetch, WebMonitor
Kommunikations-Agent	FileRW, Mail, Telegram
Datenbank-Agent	FileRW, Database
Social-Media-Agent	FileRW, SocialMediaManager, WebFetch
Finanz-Agent	FileRW, DirectAPI, Database

---

6. Kritische Analyse: Ist die Idee umsetzbar?

Vor dem Aufbau einer Instanz systematisch prüfen:

Checkliste: Machbarkeit

Prüfpunkt	Frage	Risiko wenn nein
Tool-Abdeckung	Gibt es für jeden externen Zugang ein passendes Tool?	Hoch — ohne Tool kein Zugriff
API-Verfügbarkeit	Haben alle externen APIs die nötigen Endpunkte?	Hoch — Tool ist nutzlos ohne funktionierende API
Datenformat	Kann das Tool die Daten in einem Format liefern, das das LLM verarbeiten kann?	Mittel — große/binäre Daten überfordern den Context
Autonomie-Level	Kann die Aufgabe ohne menschliche Zwischenschritte laufen?	Mittel — wenn nicht, braucht es manuelle Trigger statt Cron
Budget	Reicht das Token-Budget für die geplante Frequenz?	Hoch — unterschätzter Verbrauch ist der häufigste Fehler
Koordination	Brauchen Agenten wirklich Echtzeit-Kommunikation oder reicht SharedWorkspace?	Mittel — AgentComm kostet Token auf beiden Seiten

Häufige Fallstricke und Lösungen

Fallstrick 1: Token-Explosion durch Polling

Problem: Agent wird per Cron alle 2 Minuten geweckt → 720 LLM-Runs/Tag, auch wenn nichts passiert ist.

Lösung: Tool Jobs (IToolJobProvider) statt Agent-Wakeup verwenden. Das Tool prüft selbst (kein LLM) und weckt den Agenten nur bei Bedarf. Kostet ~0 Token pro Leer-Check.

"scheduler": null,
"toolJobs": [
  {
    "toolName": "Telegram",
    "jobTypeId": "telegram_poll",
    "cron": "*/1 * * * *",
    "enabled": true
  }
]

Fallstrick 2: Context-Overflow bei großen Daten

Problem: WebFetch liefert 50 KB HTML, Database-Query liefert 200 Zeilen → Context voll, Compaction verliert wichtige Infos.

Lösung:

• maxResponseKb in WebFetch begrenzen (Standard: 512 KB — oft zu viel)
• Database-Queries mit LIMIT versehen (in SystemPrompt anweisen)
• LoopGuard maxContextTokens angemessen setzen
• Agent in der Identity anweisen, Ergebnisse sofort zu verarbeiten und zusammenzufassen

Fallstrick 3: Agenten reden aneinander vorbei

Problem: AgentComm-Nachrichten ohne klare Struktur → Missverständnisse, Endlosschleifen.

Lösung:

• In Soul.md ein festes Nachrichtenformat definieren (JSON mit type, content, expectedAction)
• SharedWorkspace für asynchronen Datenaustausch bevorzugen (Dateien statt Nachrichten)
• Koordinator-Agent als einzigen mit AgentSpawn/AgentComm ausstatten

Fallstrick 4: Scheduler ohne sichtbares Ergebnis

Problem: Agent wird per Cron geweckt, arbeitet im Hintergrund, aber niemand sieht ob es funktioniert.

Lösung:

• Agent soll Ergebnisse in den SharedWorkspace schreiben (prüfbar per FileRW)
• Wichtige Ergebnisse per Mail oder Telegram melden lassen
• TokenUsage.json regelmäßig prüfen (Kosten vs. erwarteter Output)

Fallstrick 5: Tool-Config Fehler erst zur Laufzeit sichtbar

Problem: Falscher botToken, fehlender connectionString → Agent startet, Tool schlägt beim ersten Aufruf fehl.

Lösung:

• Vor dem Scheduler-Start einen manuellen Test-Run durchführen
• Agent manuell starten mit einer Test-Aufgabe: "Sende eine Test-Nachricht über Telegram"
• Logs unter Agent-{Name}/Logs/ prüfen

Fallstrick 6: Kosten unterschätzt bei Multi-Agent-Setup

Problem: 3 Agenten × Cron alle 10 Min × Claude Sonnet = ~$130/Tag.

Lösung:

• Billige Modelle für Routinearbeit (Gemini Flash, Haiku)
• Teure Modelle nur für Koordinator oder komplexe Analyse
• LoopGuard maxTokens aggressiv begrenzen für Routine-Agenten
• Tool Jobs statt Agent-Wakeup wo möglich

Fallstrick 7: YouTube-Transkription braucht externes Tool

Problem: SocialMediaManager mit sm_yt_monitor Job braucht yt-dlp als externes CLI-Tool auf dem System installiert.

Lösung:

• Vor Instanz-Setup prüfen ob yt-dlp installiert und im PATH ist
• Ohne yt-dlp funktionieren x_search und reddit_search trotzdem

---

7. Beispiel-Instanz: "TelegramBot"

Einfache Instanz mit einem Agenten, der über Telegram kommuniziert.

Planung

• Aufgabe: Auf Telegram-Nachrichten antworten, einfache Fragen beantworten, Dateien im Workspace verwalten
• Agenten: 1 (kein Koordinationsbedarf)
• Budget: ~$0.50/Tag
• Modell: google/gemini-2.5-flash (günstig, ausreichend für Chat)

Verzeichnisstruktur

Instance-TelegramBot/
├── InstanceSettings.json
├── TokenUsage.json
└── Agents/
    ├── AgentList.json
    ├── SharedWorkspace/
    └── Agent-Assistent/
        ├── AgentSettings.json
        ├── Identity.md
        ├── Soul.md
        ├── Logs/
        └── Workspace/

AgentList.json

{
  "agents": [
    {
      "name": "Assistent",
      "description": "Beantwortet Telegram-Nachrichten und verwaltet Notizen",
      "folderName": "Agent-Assistent"
    }
  ]
}

AgentSettings.json

{
  "agentId": "assistent",
  "displayName": "Assistent",
  "model": "google/gemini-2.5-flash",
  "systemPrompt": "",
  "tools": {
    "Telegram": {
      "botToken": "123456:ABC-DEF...",
      "defaultChatId": "987654321",
      "allowedChatIds": ["987654321"]
    },
    "FileRW": {
      "sharedAccessLevel": "Denied",
      "personalAllowedExtensions": [".txt", ".json", ".md"]
    }
  },
  "scheduler": null,
  "toolJobs": [
    {
      "jobId": "tgpoll01",
      "toolName": "Telegram",
      "jobTypeId": "telegram_poll",
      "cron": "*/1 * * * *",
      "enabled": true,
      "runOnStart": true
    }
  ],
  "loopGuard": {
    "maxSteps": 10,
    "maxTokens": 30000,
    "timeoutSeconds": 120,
    "maxContextTokens": 100000,
    "compactionThreshold": 0.8
  }
}

Kostenabschätzung

• Telegram-Polling: 1440 Ticks/Tag, ~0 Token (Tool Job, kein LLM)
• Agent-Wakeups: geschätzt 20 Nachrichten/Tag × $0.00135/Run = **$0.03/Tag**
• Deutlich unter dem $0.50 Budget

---

8. Beispiel-Instanz: "Recherche-Team"

Multi-Agent-Setup für automatisierte Web-Recherche mit Berichterstattung.

Planung

• Aufgabe: Täglich Webseiten/RSS-Feeds prüfen, relevante Infos sammeln, Bericht per E-Mail senden
• Agenten: 3 (Recherche, Analyse, Bericht)
• Budget: ~$5/Tag

Agenten-Design

Agent	Modell	Tools	Scheduler	Zweck
Crawler	google/gemini-2.5-flash	FileRW, WebFetch, WebMonitor	Cron 0 7 * * *	Daten sammeln, in SharedWorkspace ablegen
Analyst	anthropic/claude-sonnet-4-5	FileRW	Cron 0 8 * * *	Daten analysieren, Zusammenfassung erstellen
Reporter	google/gemini-2.5-flash	FileRW, Mail	Cron 0 9 * * *	Zusammenfassung als E-Mail versenden

Warum dieses Setup?

• Crawler braucht kein teures Modell — holt nur Daten ab und speichert sie
• Analyst bekommt Sonnet weil Analyse-Qualität hier den Unterschied macht
• Reporter braucht kein teures Modell — formatiert nur und sendet
• Zeitversatz (7:00 → 8:00 → 9:00) statt AgentComm — günstiger und zuverlässiger
• SharedWorkspace statt Echtzeit-Kommunikation — keine doppelten Token-Kosten

Kostenabschätzung

• Crawler: 1 Run/Tag × ~$0.002 = $0.002
• Analyst: 1 Run/Tag × ~$0.03 = $0.03
• Reporter: 1 Run/Tag × ~$0.002 = $0.002
• ~$0.034/Tag — weit unter Budget

---

9. Checkliste: Neue Instanz aufsetzen

• Aufgabe und Agenten-Aufteilung definiert
• Kostenabschätzung durchgeführt (Modell × Frequenz × Agenten)
• Prüfung: Alle nötigen Tools vorhanden?
• Prüfung: Alle externen APIs/Zugangsdaten verfügbar?
• Prüfung: Externe Abhängigkeiten installiert? (z.B. yt-dlp)
• Instanz-Ordner erstellt (manuell oder über UI)
• InstanceSettings.json mit API-Key konfiguriert
• AgentList.json mit allen Agenten erstellt
• Pro Agent: AgentSettings.json mit Modell, Tools, LoopGuard
• Pro Agent: Identity.md (Rolle, Expertise, Kontext)
• Pro Agent: Soul.md (Persönlichkeit, Methodik, Ausgabeformat)
• Pro Agent: Tool-Configs mit echten Zugangsdaten befüllt
• Tool Jobs konfiguriert (statt Agent-Wakeup wo sinnvoll)
• Manueller Test-Run pro Agent durchgeführt
• Logs geprüft — keine Tool-Fehler?
• Scheduler aktiviert
• Nach 24h: TokenUsage.json prüfen, Kosten validieren