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:

```json
{
  "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:

```json
{
  "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`:

```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.

```markdown
# 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.

```markdown
# 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.

```json
"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

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

### AgentSettings.json

```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