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?	1–5 (mehr = höhere Koordinationskosten)
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

Szenario	Empfehlung
Eine klar abgegrenzte Aufgabe	1 Agent
Aufgabe mit getrennten Zuständigkeiten (z.B. Recherche + Bericht)	2–3 Agenten
Komplexes System mit Koordination	3–5 Agenten, davon 1 Koordinator
Mehr als 5 Agenten	Kritisch hinterfragen — Koordinationsoverhead steigt quadratisch

Faustregel: Jeder Agent, der mit einem anderen kommuniziert, kostet Token auf beiden Seiten. Zwei Agenten, die jeweils 3 Nachrichten austauschen = 6 LLM-Runs.

---

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