Skip to content

README.de.md

Latest commit

 

History

History
604 lines (483 loc) · 26.2 KB

README.de.md

File metadata and controls

604 lines (483 loc) · 26.2 KB
Coding Agent Telegram

Coding Agent Telegram 🚀

English | Deutsch | Français | 日本語 | 한국어 | Nederlands | ไทย | Tiếng Việt | 简体中文 | 繁體中文（香港） | 繁體中文（台灣）

Leichtgewichtig, Multi-Bot, Multi-Session, Multi-Tasking, 24/7 AI Coding Agent

Steuere deinen lokalen AI Coding Agent von überall über Telegram.

Experimental MIT License Latest Release Python 3.9+

✨ Warum dieses Projekt

  • ✅ Leichtgewichtig: keine schweren Frameworks, volle Transparenz
  • ✅ Multi-Bot: mehrere Chats, mehrere Sessions
  • ✅ Telegram zum Steuern von Codex / Copilot CLI verwenden
  • ✅ Antworten und geänderte Dateien bequem in Code-Blöcken prüfen
  • ✅ Folgefragen während eines laufenden Agentenlaufs in die Queue stellen
  • ✅ Akzeptiert ✏️ Text-, 🌄 Bild- und 🎙️ Sprachnachrichten

🔁 Nahtlos zwischen Geräten und Sessions wechseln

Starte eine Session in Telegram und setze dieselbe Codex/Copilot CLI-Session später ohne Umwege am Computer fort. Mit /switch kannst du auch wieder sauber von Telegram zurück ins Terminal wechseln.

  • Nutze /switch, um eine lokale Session weiterzuführen
  • Historische Sessions werden ebenfalls unterstützt

🛠️ Typischer lokaler Ablauf

coding-agent-telegram # oder ./startup.sh ausführen
In Telegram:
/project my-project
/new
Fix the failing API test in the current project

→ Setup per Einzeiler:

curl -fsSL https://raw.githubusercontent.com/daocha/coding-agent-telegram/main/install.sh | bash

🔐 Sicherheit

  • Whitelist für private Chats mit ALLOWED_CHAT_IDS

  • Pro Projekt nur ein aktiver Agent, um Konflikte beim Schreiben zu reduzieren

  • Diffs sensibler Dateien werden ausgeblendet

  • API-Schlüssel, Tokens, .env-Werte, Zertifikate, SSH-Schlüssel und ähnliche geheime Ausgaben werden vor dem Senden an Telegram maskiert

  • Laufzeitdaten der App bleiben unter ~/.coding-agent-telegram

  • Bestehende Ordner können vor schreibenden Git-Operationen eine Vertrauensbestätigung verlangen

  • Der Server führt keine versteckten externen Aufrufe aus. Alles bleibt unter deiner Kontrolle.

  • Funktioniert gut mit dem Codex Sandbox mode; du musst danger-full-access nicht freigeben

✅ Voraussetzungen

Vor dem Start des Servers brauchst du:

🦞 Warum brauche ich das, wenn ich Openclaw bereits habe?

Openclaw bietet dir sehr umfassende Funktionen und hat mit Pi-Agent bereits eine integrierte Agent-Loop. Es ist vielseitig und für breitere Einsatzfälle gedacht. Ich mag Openclaw ebenfalls und habe selbst damit entwickelt. Für Coding ist es aber nicht immer die beste Wahl, weil der eingebaute große System-Prompt und der zusätzliche Kontext eher ablenken können. Claude Code / Codex / Copilot sind fürs Coding oft effizienter, präziser, weniger abgelenkt und direkter. Dieses Projekt bleibt bewusst einfach und integriert nur Codex / Copilot CLI. Du delegierst also direkt an Codex / Copilot.

🚀 Schnellstart

Variante A: Einzeiliges Bootstrap-Skript

curl -fsSL https://raw.githubusercontent.com/daocha/coding-agent-telegram/main/install.sh | bash

Variante B: Installation über PyPI mit pip

pip install coding-agent-telegram
coding-agent-telegram

Variante C: Aus einem geklonten Repository starten

git clone https://github.com/daocha/coding-agent-telegram
cd coding-agent-telegram
./startup.sh

🌐 Bot-Server starten

Beim ersten Start legt die App die Env-Datei an und sagt dir, welche Felder du ausfüllen musst.
Nach dem Bearbeiten der Env-Datei starte erneut:
# wenn du Variante A oder Variante B verwendest, dann ausführen
coding-agent-telegram

# wenn du Variante C verwendest, dann dies erneut ausführen
./startup.sh

🎙️ [Optional] Sprach-zu-Text-Funktion: lokale OpenAI-Whisper-Voraussetzungen vorbereiten

Damit aktivierst du optional lokale Whisper-basierte Sprach-zu-Text-Unterstützung für Telegram-Sprachnotizen. Audiodateien sind auf maximal 20 MB begrenzt.

# wenn du per pip oder per Einzeiler install.sh installiert hast
coding-agent-telegram-stt-install

# wenn du aus einem geklonten Repository startest
./install-stt.sh

Empfohlene Env-Einstellungen:

ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT=true
OPENAI_WHISPER_MODEL=base
OPENAI_WHISPER_TIMEOUT_SECONDS=120

Hinweise:

  • Whisper lädt das ausgewählte Modell beim ersten Aufruf automatisch nach ~/.cache/whisper herunter.
  • Wenn du OPENAI_WHISPER_MODEL=turbo wählst, ist es wahrscheinlicher, dass die erste Sprachnachricht das Zeitlimit erreicht, während large-v3-turbo.pt noch heruntergeladen wird.
  • Nach der Transkription einer Sprachnachricht sendet der Bot das erkannte Transkript zuerst zurück an Telegram und gibt es danach an den Agenten weiter. So lassen sich Erkennungsfehler leichter prüfen.

🔑 Telegram-Einrichtung

Bot-Token holen

  1. Öffne Telegram und starte einen Chat mit @BotFather.
  2. Sende /newbot.
  3. Folge den Anweisungen für:
    • einen Anzeigenamen
    • einen Bot-Benutzernamen, der auf bot endet
  4. BotFather gibt dir einen HTTP-API-Token zurück.
  5. Trage den Token in TELEGRAM_BOT_TOKENS in ~/.coding-agent-telegram/.env_coding_agent_telegram ein.

Chat-ID holen

Am zuverlässigsten ist die Telegram-getUpdates-API mit deinem eigenen Bot-Token.

  1. Starte einen Chat mit deinem Bot und sende z. B. /start.
  2. Öffne diese URL im Browser und ersetze <BOT_TOKEN>:
https://api.telegram.org/bot<BOT_TOKEN>/getUpdates
  1. Suche im JSON nach dem Objekt chat.
  2. Kopiere das numerische Feld id.
  3. Trage den Wert in ALLOWED_CHAT_IDS in ~/.coding-agent-telegram/.env_coding_agent_telegram ein.

Hinweise:

  • In privaten Chats ist die Chat-ID meist eine positive Ganzzahl.
  • Wenn getUpdates leer zurückkommt, sende dem Bot noch einmal eine Nachricht und versuche es erneut.

📨 Unterstützte Nachrichtentypen

Der Bot akzeptiert derzeit:

  • Textnachrichten
  • Fotos
  • Sprachnachrichten und Audiodateien, wenn ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT=true gesetzt ist und die lokalen Whisper-Voraussetzungen installiert sind
  • Codex und Copilot unterstützen aktuell nur Text und Bilder, kein Video.

🤖 Telegram-Befehle

/provider Provider für neue Sessions wählen. Die Auswahl wird pro Bot und Chat gespeichert, bis du sie änderst.
/project <project_folder> Aktuellen Projektordner setzen. Falls der Ordner nicht existiert, erstellt die App ihn und markiert ihn als vertrauenswürdig. Wenn er bereits existiert und noch nicht vertraut ist, fragt die App nach einer Bestätigung.
/branch <new_branch> Eine branch für das aktuelle Projekt vorbereiten oder wechseln. Wenn die branch bereits existiert, nutzt der Bot sie als Quellkandidaten. Andernfalls verwendet er die Standard-branch des Repositorys als Quellkandidaten.
/branch <origin_branch> <new_branch> Eine branch mit <origin_branch> als Quellkandidaten vorbereiten oder wechseln. Für beide Formen bietet der Bot anschließend nur die Quelloptionen an, die tatsächlich existieren: local/<branch> und origin/<branch>. Wenn nur eine davon existiert, wird nur diese angezeigt. Wenn keine existiert, meldet der Bot, dass die branch-Quelle fehlt.
/current Die aktive Session für den aktuellen Bot und Chat anzeigen.
/new [session_name] Eine neue Session für das aktuelle Projekt erstellen. Wenn du keinen Namen angibst, verwendet der Bot die echte Session-ID. Fehlen Provider, Projekt oder branch, führt dich der Bot durch den fehlenden Schritt.
/switch Die neuesten Sessions anzeigen, zuerst die neuesten. Die Liste enthält sowohl vom Bot verwaltete Sessions als auch lokale Codex/Copilot CLI-Sessions für das aktuelle Projekt.
/switch page <number> Eine andere Seite der gespeicherten Sessions anzeigen.
/switch <session_id> Zu einer bestimmten Session per ID wechseln. Wenn du eine lokale CLI-Session auswählst, importiert der Bot sie und setzt dort fort.
/compact Aus der aktiven Session eine neue kompakte Session erzeugen und dorthin wechseln.
/commit <git commands> Geprüfte git commit-bezogene Befehle im Projekt der aktiven Session ausführen. Nur verfügbar, wenn ENABLE_COMMIT_COMMAND=true. Schreibende Git-Befehle erfordern ein vertrauenswürdiges Projekt.
/diff Geänderte Dateinamen im Projekt der aktiven Session anzeigen, getrennt nach versionierten und nicht versionierten Dateien. Für versionierte Dateien gibt es Inline-Buttons zum Öffnen des jeweiligen Diffs.
/pull Nach Bestätigung origin in den Branch der aktiven Session pullen. Wenn zutreffend, aktualisiert der Bot zusätzlich den Standard-Branch.
/push origin <branch> für die aktuelle aktive Session pushen. Der Bot fragt vor dem Push nach einer Bestätigung.
/abort Den aktuellen Agentenlauf für das aktuelle Projekt abbrechen. Wenn Fragen in der Queue warten, fragt der Bot, ob sie weiter verarbeitet werden sollen.

⚙️ Umgebungsvariablen

Pfad der Haupt-Env-Datei:

CODING_AGENT_TELEGRAM_ENV_FILE Nutze dies, wenn die App eine bestimmte Env-Datei verwenden soll.
~/.coding-agent-telegram/.env_coding_agent_telegram Standardpfad der Env-Datei.
./.env_coding_agent_telegram Wird nur verwendet, wenn diese lokale Datei bereits existiert.

Erforderlich

WORKSPACE_ROOT Übergeordneter Ordner, der deine Projektverzeichnisse enthält.
TELEGRAM_BOT_TOKENS Kommagetrennte Telegram-Bot-Tokens.
ALLOWED_CHAT_IDS Kommagetrennte Telegram-Chat-IDs privater Chats, die den Bot verwenden dürfen.

Häufige Einstellungen

APP_LOCALE UI-Sprache für gemeinsame Bot-Meldungen und Befehlsbeschreibungen. Unterstützte Werte: en, de, fr, ja, ko, nl, th, vi, zh-CN, zh-HK, zh-TW.
CODEX_BIN Befehl zum Starten von Codex CLI. Standard: codex.
COPILOT_BIN Befehl zum Starten von Copilot CLI. Standard: copilot.
CODEX_MODEL Optionale Model-Überschreibung für Codex. Leer lassen, um das Standardmodell von Codex CLI zu verwenden. Beispiel: gpt-5.4 OpenAI Codex/OpenAI modelle
COPILOT_MODEL Optionale Model-Überschreibung für Copilot. Leer lassen, um das Standardmodell von Copilot CLI zu verwenden. Beispiele: gpt-5.4, claude-sonnet-4.6 GitHub Copilot unterstützte modelle
CODEX_APPROVAL_POLICY An Codex übergebener Freigabemodus. Standard: never.
CODEX_SANDBOX_MODE An Codex übergebener Sandbox-Modus. Standard: workspace-write.
CODEX_SKIP_GIT_REPO_CHECK Wenn aktiviert, werden Codex-Prüfungen für vertrauenswürdige Repositories immer übersprungen.
ENABLE_COMMIT_COMMAND Den Telegram-Befehl /commit aktivieren. Standard: false.
AGENT_HARD_TIMEOUT_SECONDS Hartes Zeitlimit für einen einzelnen Agentenlauf. Standard: 0 (deaktiviert).
SNAPSHOT_TEXT_FILE_MAX_BYTES Maximale Dateigröße, die der Bot als Text liest, wenn er Vorher/Nachher-Snapshots für Run-Diffs erstellt. Standard: 200000.
MAX_TELEGRAM_MESSAGE_LENGTH Maximale Nachrichtengröße, bevor die App Antworten aufteilt. Standard: 3000.
ENABLE_SENSITIVE_DIFF_FILTER Diffs für sensible Dateien ausblenden. Standard: true.
ENABLE_SECRET_SCRUB_FILTER Tokens, Schlüssel, .env-Werte, Zertifikate und ähnliche geheime Ausgaben vor dem Senden an Telegram unkenntlich machen. Standard: true (dringend empfohlen).
SNAPSHOT_INCLUDE_PATH_GLOBS Passende Pfade in Diffs immer einschließen. Beispiel: .github/*,.profile.test,.profile.prod
SNAPSHOT_EXCLUDE_PATH_GLOBS Zusätzliche Diff-Ausschlüsse zusätzlich zu den Standardwerten hinzufügen. Beispiel: .*,personal/*,sensitive*.txt Hinweis: .* erfasst versteckte Pfade, auch Dateien in versteckten Verzeichnissen.

Spracherkennung

ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT Standard: false. Wenn true, werden Sprachnachrichten und Audiodateien erkannt. Das System prüft die erforderlichen Binärdateien oder Bibliotheken und fordert zur Installation auf, falls etwas fehlt.
OPENAI_WHISPER_MODEL Modell für Whisper STT. Standard: base
Verfügbare Modelle: tiny ca. 72 MB, base ca. 139 MB, large-v3-turbo ca. 1.5 GB
Modelle werden bei der ersten Sprachnachricht automatisch heruntergeladen. Empfehlung: base für den allgemeinen Gebrauch. Wenn du bessere Genauigkeit und Qualität willst, kannst du turbo ausprobieren.
OPENAI_WHISPER_TIMEOUT_SECONDS Standard: 120. Timeout für den STT-Prozess. Normalerweise ist die Verarbeitung schnell genug. Wenn du jedoch turbo wählst, kann der erste Sprachaufruf während des Modelldownloads je nach Internetgeschwindigkeit das Timeout überschreiten.

Status und Logs

~/.coding-agent-telegram/state.json Hauptdatei für den Session-Status.
~/.coding-agent-telegram/state.json.bak Sicherungsdatei für den Status.
~/.coding-agent-telegram/logs Log-Verzeichnis.

Beispiel:

APP_LOCALE=en
WORKSPACE_ROOT=~/git
TELEGRAM_BOT_TOKENS=bot_token_one
ALLOWED_CHAT_IDS=123456789
DEFAULT_AGENT_PROVIDER=codex
CODEX_BIN=codex
COPILOT_BIN=copilot
CODEX_APPROVAL_POLICY=never
CODEX_SANDBOX_MODE=workspace-write
ENABLE_SENSITIVE_DIFF_FILTER=true
ENABLE_SECRET_SCRUB_FILTER=true

🧠 Session-Verwaltung

Sessions sind gebunden an:

  • Telegram-Bot
  • Telegram-Chat

Dadurch kann dasselbe Telegram-Konto mehrere Bots nutzen, ohne Sessions zu vermischen.

Beispiel:

  • Bot A + dein Chat -> Backend-Arbeit
  • Bot B + dein Chat -> Frontend-Arbeit
  • Bot C + dein Chat -> Infrastruktur-Arbeit

Die aktive Session ist außerdem gebunden an:

  • Projektordner
  • Provider
  • branch-Name, wenn vorhanden
In jeder Session wird gespeichert:
  • Session-Name
  • Projektordner
  • branch-Name
  • Provider
  • Zeitstempel
  • aktive Session-Auswahl für diesen Bot-/Chat-Bereich

🔓 Workspace-Concurrency-Lock

Pro Projektordner kann immer nur ein Agentenlauf aktiv sein, unabhängig davon, welcher Chat oder welcher Telegram-Bot ihn ausgelöst hat.

Das ist etwas anderes als „der Agent verarbeitet noch die aktuelle Frage“:

  • Projekt ist beschäftigt bedeutet, dass im Workspace bereits ein Agentenlauf aktiv ist
  • Agent ist beschäftigt bedeutet, dass dieser eine Lauf noch an der aktuellen Anfrage arbeitet

Der Bot erzwingt absichtlich genau einen aktiven Lauf pro Projekt, damit nicht zwei Agenten gleichzeitig in denselben Workspace schreiben. Das vermeidet widersprüchliche Änderungen und reduziert das Risiko von Datenkorruption.

Wenn eine Nachricht ankommt, während bereits ein Agent auf demselben Projekt läuft, antwortet der Bot sofort:

⏳ Auf dem Projekt läuft bereits ein Agent. Bitte warte, bis er fertig ist.

Der Lock wird nur im Speicher gehalten, nicht auf der Festplatte. Er wird automatisch freigegeben, wenn der Agent fertig ist, fehlschlägt oder der Server neu startet. Es gibt keine veralteten Lock-Dateien nach einem Absturz.

💬 Fragen in der Queue

Wenn im aktuellen Projekt bereits ein Agentenlauf aktiv ist, werden spätere Textnachrichten nicht abgewiesen. Sie landen stattdessen in einer Queue:

  • die neue Frage wird an eine Datei für wartende Fragen auf der Festplatte angehängt
  • der aktuelle Agent arbeitet weiter an der vorherigen Anfrage
  • wenn dieser Lauf normal endet, beginnt der Bot automatisch mit der Verarbeitung der wartenden Fragen

Wird der aktuelle Lauf abgebrochen und es warten noch Fragen, setzt der Bot nicht automatisch fort. Er fragt dann, ob die verbleibenden Fragen weiter verarbeitet werden sollen. Du kannst sie gebündelt oder einzeln verarbeiten.

⚠️ Diff (Dateiänderungen)

Während jedes Agentenlaufs erstellt der Bot außerdem einen leichten Vorher/Nachher-Snapshot des Projekts, damit er geänderte Dateien zusammenfassen und Diffs an Telegram senden kann. Dieser Snapshot wird von der Bot-App selbst erstellt, nicht von Codex oder Copilot.

Hinweise zum Snapshot:

  • die App durchsucht das Projektverzeichnis vor und nach dem Lauf
  • bei normalen Textdateien bevorzugt die App den Snapshot-Diff dieses Laufs statt eines Git-Head-Diffs
  • übliche Abhängigkeits-, Cache- und Laufzeitverzeichnisse werden ebenfalls übersprungen
  • Binärdateien und Dateien größer als SNAPSHOT_TEXT_FILE_MAX_BYTES werden nicht als Text geladen
  • bei sehr großen Projekten kann dieser zusätzliche Scan spürbaren I/O- und Speicher-Overhead erzeugen
  • wenn ein Snapshot eine Datei nicht als Text abbilden kann, greift die App wenn möglich auf git diff zurück
  • bei großen oder nicht-textuellen Dateien kann der Diff trotzdem ausgelassen und durch eine kurze Hinweisnachricht ersetzt werden

Snapshot-Ausschlussregeln liegen in den Paketressourcen:

  • src/coding_agent_telegram/resources/snapshot_excluded_dir_names.txt
  • src/coding_agent_telegram/resources/snapshot_excluded_dir_globs.txt
  • src/coding_agent_telegram/resources/snapshot_excluded_file_globs.txt

Du kannst diese Standardwerte in der Env-Datei überschreiben, ohne das installierte Paket zu ändern:

  • SNAPSHOT_INCLUDE_PATH_GLOBS Passende Pfade in Diffs immer einschließen. Beispiel: .github/*,.profile.test,.profile.prod

  • SNAPSHOT_EXCLUDE_PATH_GLOBS Zusätzliche Diff-Ausschlüsse zusätzlich zu den Paket-Standards hinzufügen. Beispiel: .*,personal/*,sensitive*.txt Hinweis: .* erfasst versteckte Pfade, einschließlich Dateien in versteckten Verzeichnissen.

Wenn Include- und Exclude-Regeln beide passen, gewinnt Include.

🌿 Branch-Verhalten

Der Bot behandelt Projekt und branch als zusammengehörig.

  • die Wahl eines Projekts wählt nicht stillschweigend eine andere branch
  • wenn eine branch-Auswahl nötig ist, fordert dich der Bot dazu auf
  • wenn branch-Informationen in Session-bezogenen Meldungen ausgegeben werden, werden Projekt und branch gemeinsam angezeigt

Wenn du eine branch erstellst oder wechselst, führt dich der Bot explizit durch die Quelle:

  • local/<branch> bedeutet: lokale branch als Quelle verwenden
  • origin/<branch> bedeutet: zuerst von der Remote-branch aktualisieren und dann wechseln

Wenn der Bot feststellt, dass die in der Session gespeicherte branch und die aktuelle Repository-branch nicht übereinstimmen, macht er nicht blind weiter. Er fragt dich, welche branch verwendet werden soll:

  • gespeicherte Session-branch behalten
  • aktuelle Repository-branch behalten

Wenn die bevorzugte Quell-branch fehlt, bietet der Bot stattdessen Fallback-Quellen auf Basis der Standard-branch und der aktuellen branch an, statt dich mit einem rohen Git-Fehler allein zu lassen.

🔐 Git-Vertrauensverhalten

  • Bestehende Ordner folgen CODEX_SKIP_GIT_REPO_CHECK
  • Ordner, die über /project <name> erstellt werden, werden von dieser App als vertrauenswürdig markiert
  • Bereits bestehende Ordner, die über /project <name> ausgewählt werden, bleiben untrusted, bis du das Vertrauen im Telegram-Prompt bestätigst
  • Neu erstellte Projektordner können daher sofort verwendet werden
  • /commit kann mit ENABLE_COMMIT_COMMAND komplett deaktiviert werden
  • Schreibende /commit-Operationen sind nur für vertrauenswürdige Projekte erlaubt

🪵 Protokolle

Logs werden sowohl auf stdout als auch in eine rotierende Log-Datei geschrieben unter:

  • ~/.coding-agent-telegram/logs (Rotation bei 10 MB, 3 Backups)

Hinweis: Weil Nachrichten sowohl auf stdout als auch in die Log-Datei geschrieben werden, erscheinen sie doppelt, wenn du gleichzeitig das Terminal beobachtest und die Log-Datei per tail -f ~/.coding-agent-telegram/logs/coding-agent-telegram.log verfolgst. Das ist erwartetes Verhalten. Beobachte entweder das eine oder das andere.

Typische geloggte Ereignisse
  • Bot-Start und Polling-Start
  • Projektauswahl
  • Session-Erstellung
  • Session-Wechsel
  • Anzeige der aktiven Session
  • normale Laufausführung (einschließlich Audit-Log-Zeile mit gekürztem Prompt)
  • Session-Ersetzung nach fehlgeschlagenem Resume
  • Warnungen und Laufzeitfehler

🗂️ Projektstruktur

  • src/coding_agent_telegram/ Hauptanwendungscode

  • tests/ Test-Suite

  • startup.sh Lokaler Bootstrap- und Startup-Einstiegspunkt

  • src/coding_agent_telegram/resources/.env.example Kanonische Umgebungs-Vorlage, die sowohl vom Repo-Start als auch von Paketinstallationen verwendet wird

  • pyproject.toml Packaging- und Abhängigkeitskonfiguration

📦 Veröffentlichung-Versionierung

Paketversionen werden aus Git-Tags abgeleitet.

  • TestPyPI/Testen: v2026.3.26.dev1
  • PyPI-Prerelease: v2026.3.26rc1
  • PyPI-Stable: v2026.3.26

📌 Hinweise

  • Dieses Projekt ist für Nutzer gedacht, die die Agenten lokal auf ihrem eigenen Rechner ausführen.
  • Der Telegram-Bot ist eine Steueroberfläche, nicht die Ausführungsumgebung selbst.
  • Wenn du mehrere Bots betreibst, können sie alle von einem einzigen Serverprozess verwaltet werden.