Telegram Bot — Setup & Troubleshooting¶

Letzte Änderung: 10.05.2026\ Status: Aktiv

Schnellstart (nach Container-Neustart)¶

Ab 10.05.2026 ist der Wrapper-Fix vollautomatisch. Nach einem Container-Neustart (HA-Update, Add-on-Update, Reboot) passiert folgendes automatisch:

pip install /data/home/claudefix läuft in run.sh (vor ttyd-Start)
fix-run-sh.sh wird aufgerufen
Wrapper, .tmux.conf und Session-Picker werden gepatcht
Claude startet automatisch mit %%--channels -c%% (letzte Konversation fortsetzen)
Terminal öffnen → Enter drücken → direkt in der laufenden Session ✅

Nichts manuell tun nötig. Falls doch etwas schiefläuft:

bash /config/tools/fix-run-sh.sh

Überblick¶

Das Telegram-Plugin verbindet den Bot @Claude_HA_Home_bot mit dem Claude Code CLI. Nachrichten an den Bot erscheinen direkt als User-Prompt im laufenden Claude-Prozess. Claude antwortet via Reply-Tool.

Funktionsweise¶

Bot pollt Telegram via getUpdates (Long-Polling)
Eingehende Nachrichten → MCP-Notification notifications/claude/channel
Claude Code empfängt Notification → erscheint als `` Tag
Claude antwortet via reply-Tool (sendMessage API)

Auto-Fix & Auto-Resume Mechanismus (seit 10.05.2026)¶

Problem (gelöst): Nach jedem Container-Neustart ist /usr/local/bin/claude wieder ein Symlink zur Binary. Claude startet ohne Wrapper nicht → SessionStart-Hook läuft nie → Henne-Ei-Problem.

Lösung — 3 Stufen:

Was fix-run-sh.sh patcht: - /usr/local/bin/claude → Wrapper (%%--channels%% + IS_SANDBOX=1 + %%--bypass-permissions%%) - /data/home/.tmux.conf → set-environment -g IS_SANDBOX 1 + PATH mit /data/home/bin/ vorne - /usr/local/bin/claude-session-picker → ruft fix-run-sh.sh beim Start auf - /data/home/bin/claude → persistenter PATH-Fallback-Wrapper (überlebt Neustarts) - tmux-Session claude → startet automatisch mit %%--channels -c%% (Auto-Resume, vor ttyd)

Auto-Resume — wie es funktioniert:

fix-run-sh.sh Step 4 startet Claude VOR ttyd in einer Hintergrund-tmux-Session:

tmux new-session -d -s claude -x 220 -y 50 \
    "export IS_SANDBOX=1; exec /usr/local/bin/claude --channels -c"

-c = continue most recent conversation. Wenn der User das Terminal öffnet, sieht der Session-Picker die laufende Session und bietet "Reconnect" als Default an — einfach Enter drücken.

Persistente Dateien (überleben Container-Neustarts): - /data/persistent-packages.json → registriert pip-Package - /data/home/claudefix/setup.py → ruft Fix auf - /data/home/bin/claude → Fallback-Wrapper - /config/tools/fix-run-sh.sh → eigentliches Fix-Script - /config/tools/claude-telegram-wrapper → Wrapper-Quelle

Konfigurationsdateien¶

Schnelldiagnose¶

Schritt 1 — Wrapper prüfen (IMMER ZUERST):

ls -la /usr/local/bin/claude
# -rwxr-xr-x (Script, ~1171 bytes) → OK ✅
# lrwxrwxrwx (Symlink)             → Auto-Fix hat nicht geklappt
#   → bash /config/tools/fix-run-sh.sh

Schritt 1b — Auto-Resume Session prüfen:

tmux list-sessions 2>/dev/null
# claude: 1 windows (created ...) → Session läuft ✅
# (leer / Fehler)                 → Session nicht gestartet → fix-run-sh.sh ausführen

Schritt 2 — Session-Typ (--channels aktiv?):

cat /data/home/.claude/sessions/$(pgrep claude).json | python3 -c "import json,sys; print(json.load(sys.stdin).get('entrypoint','?'))"
# "channels" → OK ✅
# "cli"      → --channels fehlt → Wrapper installieren + Neustart

Schritt 3 — Plugin-Version:

cat /data/home/.claude/plugins/installed_plugins.json
# "version": "0.0.6" → OK ✅

Schritt 4 — bun-Pfad in .mcp.json:

grep command /data/home/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/telegram/.mcp.json
# "/data/home/.bun/bin/bun" → OK ✅
# "bun" (ohne Pfad)         → Fehler! .mcp.json manuell auf absoluten Pfad setzen

Schritt 5 — Bot pollt?

curl "https://api.telegram.org/bot8685305507:AAHghbigovBX621pquSJt_WuoWC1RWm_FuY/getUpdates?timeout=1"
# 409 Conflict → Bot pollt aktiv → OK ✅
# 200 OK + result:[] → kein Poller → Zombie oder bun-Prozess tot

Schritt 6 — bun-Prozess läuft?

ps aux | grep bun
# Prozess sichtbar → OK ✅
# Leer            → Bot-Subprocess tot → Add-on neu starten

Schritt 7 — 👀-Reaktion auf Testnachricht? 1. Ja → Grammy empfängt, weiter mit Schritt 8 1. Nein → Grammar empfängt nicht → bun-Pfad prüfen (Schritt 4), Plugin updaten

Schritt 8 — CC-Version aktuell?

claude --version
npm show @anthropic-ai/claude-code version
# bei Update-Rückstand: npm install -g @anthropic-ai/claude-code@latest + Neustart

Bekannte Probleme & Lösungen¶

Wrapper fehlt / --bypass-permissions nicht aktiv¶

Symptom: Bestätigungs-Prompts bei Tool-Aufrufen, oder Claude empfängt keine Telegram-Nachrichten.

Fix: bash /config/tools/fix-run-sh.sh → Add-on neu starten

Hinweis: IS_SANDBOX=1 ist Pflicht — HAOS läuft als root (uid=0), und --bypass-permissions erfordert diese Env-Variable.

Claude startet nicht — "dangerously-skip-permissions" Fehler¶

Seit einer neueren CC-Version heißt das Flag --bypass-permissions (früher --dangerously-skip-permissions).

Fix 1 — Wrapper prüfen:

grep "bypass\|dangerously" /config/tools/claude-telegram-wrapper
# Muss "bypass-permissions" zeigen

Fix 2 — Feature-Flag in .claude.json:

sed -i 's/"tengu_disable_bypass_permissions_mode": false/"tengu_disable_bypass_permissions_mode": true/' /data/home/.claude.json

Dieser Wert kann nach einem Fehlstart wieder auf false zurückspringen → dann Fix 2 wiederholen.

Auto-Fix funktioniert nicht (pip läuft nicht)¶

Prüfen ob /data/persistent-packages.json korrekt ist:

cat /data/persistent-packages.json
# Soll: {"apk_packages": [], "pip_packages": ["/data/home/claudefix"]}
cat /data/home/claudefix/setup.py | head -5
# Soll: import subprocess, os (erste Zeilen)

Manuell testen:

pip3 install --break-system-packages --no-cache-dir /data/home/claudefix
ls -la /usr/local/bin/claude   # danach kein Symlink mehr?

Auto-Resume startet nicht (tmux-Session fehlt nach Neustart)¶

Symptom: Terminal öffnen → Session-Picker zeigt kein "Reconnect" an.\ Ursache: fix-run-sh.sh Step 4 ist nicht gelaufen (pip hat nicht gefeuert, oder tmux nicht verfügbar).

Fix:

bash /config/tools/fix-run-sh.sh
tmux list-sessions   # "claude" soll erscheinen

Zombie-Bot (outbound OK, inbound tot)¶

Symptom: Claude antwortet auf Telegram-Nachrichten, empfängt aber keine neuen.\ Diagnose: getUpdates → 200 OK + result:[] (statt 409 = aktiver Poller)

Fix: Bot-PID killen + Add-on neu starten:

kill $(cat /data/home/.claude/channels/telegram/bot.pid 2>/dev/null)
# danach: HA → Add-ons → Claude Code Terminal → RESTART

bun nicht im PATH — MCP-Server startet nicht¶

Symptom: Telegram-Tools nicht in deferred tool list, kein bun-Prozess.\ Fix: .mcp.json auf absoluten Pfad setzen:

# Datei: /data/home/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/telegram/.mcp.json
# "command": "bun"  →  "/data/home/.bun/bin/bun"

⚠️ Bei Plugin-Update wird .mcp.json überschrieben → danach erneut prüfen!

Bot komplett tot (kein Prozess)¶

Symptom: Weder ein- noch ausgehende Nachrichten, kein bun-Prozess.\ Ursache: Harter Shutdown (Stromausfall, SIGKILL).\ Fix: Claude Code Add-on in HA neu starten → letzte Nachricht nochmal senden.

Versionshistorie der Fixes¶

| Version | Datum | Inhalt | | v10.1 | 2026-05-10 | Auto-Resume: fix-run-sh.sh Step 4 startet tmux-Session "claude" mit --channels -c VOR ttyd; Session-Picker attached automatisch; Bot-Token erneuert | | v10.0 | 2026-05-10 | Auto-Fix: pip-Package /data/home/claudefix via /data/persistent-packages.json löst Henne-Ei-Problem; .tmux.conf + session-picker werden automatisch gepatcht | | v9.0 | 2026-05-01 | %%--bypass-permissions%% ersetzt %%--dangerously-skip-permissions%%; IS_SANDBOX=1 bleibt Pflicht; tengu_disable_bypass_permissions_mode: true in .claude.json | | v8.0 | 2026-04-25 | Wrapper-Ansatz: /usr/local/bin/claude wird durch Script ersetzt statt /run.sh zu patchen | | v7.0 | 2026-04-24 | SessionStart-Hook patcht /run.sh automatisch + HA Push-Notification | | v6.0 | 2026-04-24 | --channels erneut verloren nach Add-on Update; /run.sh muss beide claude-Vorkommen haben | | v5.0 | 2026-04-24 | --channels geht bei Add-on UPDATE (nicht nur Restart) verloren → /run.sh aus Container-Image | | v4.0 | 2026-04-24 | bun nicht im PATH → .mcp.json auf /data/home/.bun/bin/bun + SessionStart-Symlink | | v3.0 | 2026-04-24 | Plugin 0.0.6: Polling-Retry bei ALLEN Fehlern (nicht nur 409) | | v2.0 | 2026-04-24 | --channels Flag erklärt: ohne es läuft Plugin als MCP-Server, aber kein Inbound | | v1.0 | 2026-04-23 | Zombie-Bug: 409-Retry 8→120, Non-409 retry statt abort; IS_SANDBOX Patch |

Referenzen¶

Wrapper (Quelle): /config/tools/claude-telegram-wrapper
Wrapper (aktiv): /usr/local/bin/claude (Script, kein Symlink!)
Fix-Script: /config/tools/fix-run-sh.sh
pip-Package: /data/home/claudefix/setup.py
pip-Registrierung: /data/persistent-packages.json
Plugin: /data/home/.claude/plugins/cache/claude-plugins-official/telegram/0.0.6/server.ts
Plugin .mcp.json: /data/home/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/telegram/.mcp.json
Config: /data/home/.claude/channels/telegram/
Einstellungen: /data/home/.claude/settings.json

← Zurück zur Projekte-Übersicht | ← Server-Übersicht