Telegram Status Bot - Betriebsdoku

Zweck

Telegram-Bot fuer Statusabfragen und Codex-Auftraege (Text + Voice/STT).

Laufzeitmodell (wichtig)

• Produktivbetrieb erfolgt ueber systemd, nicht per nohup.
• Service-Name: telegram-codex-bot.service
• Unit-Datei: /etc/systemd/system/telegram-codex-bot.service
• EnvironmentFile: /root/codex/telegram-status-bot/.env.host

Service-Commands

• Status: systemctl status telegram-codex-bot.service
• Neustart: systemctl restart telegram-codex-bot.service
• Stoppen: systemctl stop telegram-codex-bot.service
• Starten: systemctl start telegram-codex-bot.service
• Logs live: journalctl -u telegram-codex-bot.service -f
• Letzte Logs: journalctl -u telegram-codex-bot.service -n 200 --no-pager

Konfiguration

Primar relevant in .env.host:

• TELEGRAM_BOT_TOKEN
• TELEGRAM_ALLOWED_CHAT_ID (Owner-ID)
• TELEGRAM_ALLOWED_GROUP_IDS (kommagetrennte Gruppenliste)
• STATE_DIR (hier: /root/codex/telegram-status-bot/data-host)
• OPENAI_API_KEY
• OPENAI_TRANSCRIBE_MODEL

Hinweis:

• .env ist lokal fuer manuelle Runs nutzbar.
• Service liest per Unit explizit .env.host.

Zugriff / Sicherheit

• Private Chats: nur TELEGRAM_ALLOWED_CHAT_ID.
• Gruppen: nur erlaubte Gruppen (TELEGRAM_ALLOWED_GROUP_IDS), nur vom Owner (from.id == TELEGRAM_ALLOWED_CHAT_ID), und nur bei Mention bzw. /codex.
• Bot sendet eine persistente Telegram-Tastatur mit /new.

Session- und Update-State

• Codex-Session: codex_session_id.txt in STATE_DIR.
• Neue Session-Mappings: codex_session_message_map.jsonl in STATE_DIR mit session_id + eingehender Nachricht.
• Telegram-Offset: telegram_update_offset.txt in STATE_DIR.
• Damit werden nach Neustarts alte Updates nicht erneut abgearbeitet.

Voice-Verarbeitung

• Voice wird von Telegram geladen, temporaer gespeichert, transkribiert (OpenAI STT), und temp-Datei danach geloescht.
• Es wird kein Audio dauerhaft archiviert.

Bekannte Stolperfallen

• Wenn Bot “nicht reagiert”: zuerst pruefen, ob Service aktiv ist.
• Nicht parallel als nohup und systemd laufen lassen (Doppelverarbeitung/Verwirrung).
• Bei Gruppen-Nachrichten ohne Mention ist deny no_mention erwartetes Verhalten.