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](Organisation-Konzept.md).

| 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](Organisation-Konzept.md) 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
    ├── SharedWorkspaces/          ← Bereiche mit Mitgliederliste (#684), einer je Einheit
    │   └── {bereich}/             ← in FileRW als workspace "unit" oder "{bereich}"
    └── 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 |

---

## 5a. Fremde Laufzeit: ein Agent in Claude Code (#712)

Ein Agent kann statt in unserer Engine in **Claude Code** arbeiten (gedacht für die
Entwicklungsabteilung) oder in einem **Befehl**. Er läuft dann in der Sandbox auf einer
Kopie seines Arbeitsbereichs. Was er ändert, liegt danach als Vorschlag unter
`Agents/Agent-<id>/proposals/<lauf>/` und wird **nicht** übernommen. Taskboard und Kollegen
erreicht er nur über den MCP-Server der Instanz. Hintergrund: Organisation-Konzept,
Abschnitt 7a.

**Voraussetzungen (nur Linux):**

1. `bubblewrap` ist installiert (`apt install bubblewrap`). Die Karte „Laufzeit“ in der
   Agentenansicht meldet „Die Sandbox ist bereit“. Ohne Sandbox laufen fremde Laufzeiten
   gar nicht, sie fallen auch nicht auf die native Engine zurück.
2. Claude Code ist für den Benutzer installiert, unter dem die Instanz läuft. Mit dem
   nativen Installer liegt es unter `~/.local/bin/claude` und wird dort gefunden. Bei einer
   npm-Installation kommen das Programm und Node in `claudeCode.executable` bzw.
   `claudeCode.readOnlyPaths` der `instance.json`.
3. Das Konto (Karte „Laufzeit“ → „Bearbeiten“, gilt für die ganze Instanz):
   - **API-Schlüssel (Voreinstellung):** am besten ein eigener Schlüssel in einem
     Anthropic-Workspace mit Ausgabengrenze. Der Schlüssel ist im Lauf für Claude Code
     lesbar, denn es muss ihn benutzen.
   - **Abo:** ein Token aus `claude setup-token`, erzeugt auf einem Rechner, an dem du
     angemeldet bist. Das Abo teilt sein Kontingent mit deiner eigenen Nutzung, und ob es
     ein Agentensystem betreiben darf, regeln seine Bedingungen.

**Der Agent** (Karte „Laufzeit“ oder `AgentSettings.json`):

```json
"runtime": {
  "kind": "claude-code",
  "allowedTools": ["Read", "Edit", "Write", "Glob", "Grep", "mcp__clawd"],
  "maxTurns": 30,
  "timeoutMinutes": 30,
  "egress": ["pypi.org", "files.pythonhosted.org"]
}
```

- `allowedTools` leer lassen heißt: die obige Voreinstellung. `Bash` erlaubt die Shell
  **in der Sandbox**. WebFetch und WebSearch sind immer verboten.
- `egress` nennt Hosts, die der Lauf zusätzlich zur API erreichen darf. Es gilt nur HTTPS
  und nur an öffentliche Adressen.
- `model` des Agenten wird an Claude Code weitergegeben (`anthropic/claude-sonnet-5` wird
  zu `claude-sonnet-5`). Ein Modell eines anderen Anbieters wird ignoriert; dann gilt die
  Voreinstellung von Claude Code.

Beim Befehl (`"kind": "command"`, dazu `command` und `arguments`) kommt die Nachricht über
stdin, und was der Befehl ausgibt, ist das Ergebnis. Den MCP-Server erreicht er mit
`$CLAWD_HELPER --mcp-bridge --socket $CLAWD_MCP_SOCKET`; das Token liegt in
`$CLAWD_MCP_TOKEN_FILE`.

**Verbrauch:** Jeder Lauf steht in `RunUsage` mit Laufzeit und Token. Auf dem Abo kostet
er 0 $ und ist als Abo-Lauf markiert, verbraucht aber Kontingent.

---

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

---

## 8. Betrieb unter Linux: Dienst und Updates (#795)

Der Instanzmanager läuft als systemd-Benutzerdienst; die Instanzen startet er selbst. Vorlagen
liegen unter `deploy/systemd/`:

| Datei | Wofür |
|---|---|
| `clawddotnet-manager.service` | Der Manager als Dienst (`Restart=on-failure`, `KillMode=process`) |
| `clawddotnet-update.service` | Einmal-Unit für Updates: Manager stoppen → `update-agent` → Manager starten |

```bash
mkdir -p ~/.config/systemd/user
cp deploy/systemd/*.service ~/.config/systemd/user/
# Pfade (%h/clawddotnet) und Kanal (--channel) in beiden Dateien anpassen
install -m 600 /dev/null ~/.config/clawddotnet/update.env
echo 'DC_LICENSE_KEY=<Lizenzschlüssel>' >> ~/.config/clawddotnet/update.env
systemctl --user daemon-reload
systemctl --user enable --now clawddotnet-manager.service
loginctl enable-linger "$USER"
```

**Update aus der Weboberfläche** (Einstellungen → Instanzmanager → Update): Der Manager hält
erst alle Instanzen geordnet an und stößt dann `clawddotnet-update.service` an. Die Unit stoppt
den Dienst, spielt das Update ein und startet ihn wieder — auch wenn das Update scheitert
(`ExecStopPost`). Fehlt die Unit, hält der Manager nichts an und sagt, was fehlt.

Warum nicht der update-agent allein: Aus dem Manager gestartet, würde er den Manager nach dem
Update selbst neu starten — an systemd vorbei, als zweiten Prozess neben dem Dienst
(Deploymentcenter, SETUP_INTEGRATION_GUIDE §4A). Ohne systemd (Windows, von Hand gestartet)
ist genau das der richtige Weg, und den geht der Manager dann auch.