Telegram-Bots — Benutzerhandbuch

Arc OS nutzt eine zweistufige Telegram-Bot-Architektur: Ein Master Bot verwaltet alle Projekte, und jedes Projekt bekommt seinen eigenen Child Bot mit AI-Workern.

Architekturüberblick

Das System basiert auf zwei Ebenen:

Master Bot ("Der Meister") — Orchestrator ohne AI. Verwaltet den Lebenszyklus aller Projekte: Erstellung, Löschung, Health-Monitoring, Deploy, Notfall-Stop.
Child Bot — einer pro Projekt. Proxy zwischen Telegram und Claude CLI. Enthält AI-Worker (Consultant, Developer, eigene), verarbeitet Nachrichten und speichert den Dialogkontext.

So funktioniert es

Telegram-Kanal:
  Nutzer → Telegram → Child Bot → Claude CLI → Antwort → Telegram

CRM Dashboard:
  Nutzer → CRM → crm_inbox.jsonl → Child Bot (Polling 500ms) → Claude CLI → Antwort → Telegram + CRM

Der Child Bot pollt die Datei crm_inbox.jsonl alle 500ms, sodass Nachrichten aus dem CRM Dashboard nahezu sofort verarbeitet werden.

Master Bot-Befehle

Befehl	Beschreibung
`/start`	Liste der verfügbaren Befehle anzeigen
`/status`	Status aller Projekte: aktive Threads, Uptime, Ressourcennutzung
`/list`	Liste aller Child Bots mit Health-Indikatoren (🟢/🔴)
`/health`	Health-Matrix: Bot-, Bridge- und tmux-Sitzungsstatus für jedes Projekt
`/deploy <name\|all>`	Git pull + Neustart für ein bestimmtes Projekt oder alle auf einmal
`/new_project <name>`	Onboarding für neues Projekt starten (Child Bot, tmux, Konfiguration erstellen)
`/remove_project <name>`	Projekt mit Bestätigung löschen (Inline-Schaltfläche „Ja, löschen")
`/emergency_stop`	3-stufiger kaskadierender Stop: SIGINT → `/exit` → SIGKILL. Stoppt alles.
`/watchdog`	Child Bot-Monitoring: automatischer Neustart, wenn ein Bot nicht antwortet
`/cancel`	Aktuelle laufende Operation abbrechen (Deploy, Onboarding usw.)

Child Bot-Befehle

Grundlegende Präfixe

Präfix	Worker	Modell	Zugriff
`/c <Nachricht>`	Consultant	Sonnet	Read-only, strategischer Berater
`/d <Nachricht>`	Developer	Opus	Voller Zugriff auf Dateien und Terminal
`/w:<worker_id> <Nachricht>`	Eigener Worker	Abhängig von der Konfiguration	Definiert in `workers_registry.json`
(ohne Präfix)	Aktiver Worker	—	Standardmäßig Consultant

Beispiel:

/c Analysiere die Architektur des Auth-Moduls
/d Behebe den Bug im Login-Formular
/w:sentinel Führe ein Security-Audit der letzten Änderungen durch

Informationsbefehle

Befehl	Beschreibung
`/ping`	Bot-Health + Uptime prüfen
`/thread`	Größe des aktuellen Dialogverlaufs (Anzahl der Nachrichten)
`/quality`	Qualitätsmetriken: Anzahl der Aufrufe, Feedback (👍/👎), durchschnittliche Antwortdauer
`/learnings`	Liste der angesammelten Korrekturregeln (Learnings)
`/specs`	Liste der Spezifikationen mit Status (draft / review / approved)
`/approve <id>`	Spezifikation nach ID genehmigen
`/reject <id> [Grund]`	Spezifikation mit optionalem Grund ablehnen

Inline-Schaltflächen

Unter der Worker-Antwort

Nach jeder Antwort des AI-Workers erscheinen drei Reihen von Schaltflächen:

Reihe 1 — Claude-Prozesssteuerung:

Schaltfläche	Aktion
🛑 STOP	Beendet den Claude-Prozess (SIGKILL). Verwenden, wenn die Antwort in die falsche Richtung geht oder hängt.
⏸️ PAUSE	Pausiert den Claude-Prozess (SIGSTOP). Nützlich, um auf etwas zu warten, bevor es weitergeht.
▶️ RESUME	Setzt den pausierten Prozess fort (SIGCONT).

Reihe 2 — Kontext und Feedback:

Schaltfläche	Aktion
💡 BTW	Modus zum Sammeln von zusätzlichem Kontext. Deine nächsten Nachrichten landen in der Warteschlange und werden in den nächsten GSD-Prompt injiziert.
🛠️ Fix It	Aufgabe mit automatischen Korrekturen auf Basis der vorherigen Antwort neu starten.
👍	Positives Feedback — wird in den Qualitätsmetriken erfasst.
👎	Negatives Feedback — erstellt automatisch eine Learning-Regel, die in jeden zukünftigen Worker-Prompt injiziert wird.

Reihe 3 — Navigation:

Schaltfläche	Aktion
🏷️ Skills	Liste der Skills anzeigen, die für die Antwort verwendet wurden.
📊 View Log	CRM-Log dieser Sitzung öffnen.

Master Bot-Schaltflächen

Auf jeder Projektkarte im Master Bot stehen folgende Schaltflächen zur Verfügung:

Restart — Child Bot neu starten
Delete — Projekt löschen (mit Bestätigung)
Manifest — Projektkonfiguration anzeigen
Skills — Liste der Projekt-Skills
Quality — Qualitätsmetriken
CRM — Link zum CRM Dashboard

Kontext und Gedächtnis

Der Dialogverlauf wird pro Worker gespeichert (maximal 50 Einträge). Jeder Worker hat sein eigenes Gedächtnis.
Reply auf eine bestimmte Nachricht → ihr Text wird als CONTEXT in den Claude-Prompt injiziert.
Context Router wählt automatisch die Top-5-Skills aus, die für deine Nachricht relevant sind.
Learnings aus 👎 → werden automatisch in jeden zukünftigen GSD-Prompt injiziert, damit der Worker keine Fehler wiederholt.

Worker wechseln

Jeder Child Bot unterstützt mehrere Worker. Der aktive Worker wird in der Datei active_role.json gespeichert.

/c — wechselt zum Consultant (Sonnet, read-only-Analyse)
/d — wechselt zum Developer (Opus, voller Zugriff)
/w:<worker_id> — wechselt zu einem eigenen Worker anhand seiner ID

Nachrichten ohne Präfix gehen an den aktuell aktiven Worker. Wenn du /d Behebe den Bug geschickt hast, wird Developer aktiv — nachfolgende Nachrichten ohne Präfix gehen ebenfalls an Developer.

Verbindung zum CRM

Telegram und CRM Dashboard sind zwei Kanäle zum selben Worker:

Das CRM Dashboard schreibt Nachrichten in die Datei crm_inbox.jsonl
Der Child Bot pollt diese Datei alle 500ms und verarbeitet neue Nachrichten
Antworten erscheinen sowohl in Telegram als auch im CRM gleichzeitig
Anhänge (Bilder, PDFs) werden über das CRM Dashboard unterstützt

Das bedeutet: Du kannst einen Dialog in Telegram beginnen, im CRM fortführen und umgekehrt — der Kontext bleibt erhalten.

Troubleshooting

Problem	Lösung
Bot antwortet nicht	Prüfe `/health` im Master Bot. Wenn der Child Bot 🔴 zeigt — klicke auf Restart oder nutze `/deploy <name>`. Überprüfe `/watchdog` für automatisches Monitoring.
Lange Antwortzeiten	Wechsle zum Consultant (`/c`) — er nutzt Sonnet, das schneller als Opus ist. Für einfache Fragen reicht das aus.
Nachricht wird abgeschnitten	Telegram hat ein Limit von 4096 Zeichen pro Nachricht. Der Bot teilt lange Antworten automatisch auf: `[1/3]`, `[2/3]`, `[3/3]`.
Bot antwortet langsam über CRM	Prüfe, ob die tmux-Sitzung des Child Bots aktiv ist: `/health` sollte tmux 🟢 anzeigen.
👎 erstellt kein Learning	Stelle sicher, dass du 👎 direkt unter der Worker-Antwort gedrückt hast, nicht unter einer Systemnachricht.