Teile dieser Seite sind noch auf Englisch: Das englische Original wurde nach der Übersetzung geändert.
Referenz / Archiv & Integrationen
Telegram · Befehlszeile
Suchen, Kontext lesen, Aktivitäten zählen und gespeicherte Nachrichten aus Skripten und Agenten exportieren – mit --json-Ausgabe, stabilen Exit-Codes und bereichsgebundenen, schreibgeschützten Tokens.
Schreibgeschütztes MCP · Volltextsuche · Wiki
Preview. tgwitness search, context, messages, stats and export read
saved observations for scripts and AI agents. They cannot send anything to
Telegram, change settings or modify the signed journal. tgwitness index and
tgwitness backup (below) work on a local data directory and
need no token.
Dabei --jsongibt stdout genau ein JSON-Dokument aus (export schreibt JSON-Zeilen).
Fortschrittsmeldungen, Hinweise und Fehler werden an stderr ausgegeben. Die Exit-Codes sind stabil:
| Code | Bedeutung |
|---|---|
0 |
Erfolg, einschließlich eines leeren Ergebnisses |
1 |
Fehler: nicht erreichbares Panel, unlesbare Daten, unterbrochener Export |
2 |
Anwendungsfehler oder ungültige Anfrage: falsches Datum, unbekannte Option, Suchindex deaktiviert |
3 |
Derzeit nicht verfügbar: Der Arbeitsbereich ist in einem aktiven Panel geöffnet, oder das Panel fordert dazu auf, es später erneut zu versuchen (Ratenbegrenzung, Zeitüberschreitung). |
4 |
Zugriff verweigert: fehlendes, abgelaufenes oder widerrufenes Token, ein Chat außerhalb des Gültigkeitsbereichs, ein Tool, das dies nicht zulässt |
Zwei Lesemöglichkeiten#
Über das Bedienfeld (--url). Der Befehl verwendet dieselbe bereichsbezogene Archiv-API wie
MCP. Erstellen Sie eine Verbindung unter Weitere Tools → Integrationen → MCP: Wählen Sie Arbeitsbereiche und Chats,
Tools und eine Gültigkeitsdauer aus und kopieren Sie das Token einmal. Die Verbindung ist schreibgeschützt, beschränkt
auf diese Chats, auf 60 Anfragen pro Minute begrenzt und kann jederzeit widerrufen oder
erneuert werden. Panel-Anmeldetoken und Telegram-Anmeldedaten funktionieren hier nicht.
export TGWITNESS_URL=https://panel.example.org # default http://127.0.0.1:8787
export TGWITNESS_MCP_TOKEN=tgw_mcp_... # or --token-file path
tgwitness search 'перевод карта' --json
Ein Remote-Panel benötigt HTTPS; einfaches HTTP wird nur für 127.0.0.1,
localhost und ::1. Proxy-Umgebungsvariablen werden ignoriert und Weiterleitungen
abgelehnt, sodass das Token ausschließlich die von Ihnen angegebene Adresse erreicht.
Direkt aus einem angehaltenen Arbeitsbereich (--data-dir). Liest das Datenverzeichnis mit
vollständigem lokalem Zugriff, ohne Token. Verwenden Sie es auf einer Kopie eines Datenverzeichnisses oder während
die Erfassung angehalten ist. Signierte Datensätze werden niemals verändert; wie beim Panel kann das Öffnen eines
Arbeitsbereichs dazu führen, dass die daraus abgeleiteten Indizes auf den aktuellen Stand gebracht werden. Wenn das Panel den Arbeitsbereich geöffnet hat, beendet sich der Befehl mit dem
Code 3; lesen Sie stattdessen über das Panel. Ohne --data-dir, TGWITNESS_DATA,
./data/live oder das Datenverzeichnis der Installation, auf der der Befehl ausgeführt wird, wird verwendet.
--workspace ID wählt einen Arbeitsbereich aus (Standard default). tgwitness messages
--workspaces listet diejenigen auf, die Sie lesen dürfen.
Befehle#
| Befehl | Ergebnis |
|---|---|
tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N] |
Die besten Treffer zuerst, mit Wortformen, exakten Phrasen in Anführungszeichen, Domains und @username (Syntax) |
tgwitness search QUERY --exact [--before SEQ] |
Genauer Wortlaut, neueste Einträge zuerst, ohne Index |
tgwitness context CHAT_ID MESSAGE_ID [--limit N] [--before SEQ] |
Gespeicherte Nachrichten innerhalb von zehn Nachrichten-IDs auf beiden Seiten |
tgwitness messages [--limit N] [--offset N] |
Chats, die Sie lesen können |
tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--before SEQ] |
Gespeicherte Nachrichten des Chats, die neuesten zuerst |
tgwitness messages CHAT_ID --message ID |
Jede gespeicherte Version und jeder Löschdatensatz einer Nachricht |
tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N] |
Aktivitätsstatistiken, siehe unten |
tgwitness export [--chat ID] [--since] [--until] [--output FILE] |
Gespeicherte Beobachtungen als JSON-Zeilen in der Reihenfolge des Protokolls |
Datumsangaben erfolgen 2026-10-01 (UTC-Mitternacht) oder ISO-Zeiten mit Zeitzone
2026-10-01T09:00+03:00. Für search, messages und export wählen sie
den Beobachtungszeitpunkt. Seiten fassen bis zu 50 Datensätze: Befolgen Sie next_offset (--offset) für die
rangierte Suche und next_before (--before) an anderer Stelle.
Ranked search stops at 1,000 results. The final page may be shorter than --limit. When more observations match, the last page says so (truncated: true with --json); narrow the query, chat or period.
Jedes Nachrichtenergebnis enthält untrusted_content: true
, die Arbeitsbereichs-, Chat- und
Nachrichten-IDs, die Journalsequenz, den Hash des gespeicherten Datensatzes und einen Panel-Link. Bearbeitungen,
Löschhinweise und missing_on_recheck
sind separate Datensätze. Die Abdeckung in stats
zeigt die Zeiträume an, auf die sich ein Suchergebnis bezieht.
Aktivitätsstatistiken#
stats Zählt die gespeicherten Beobachtungen für einen Chat, einen Absender oder alle Chats im Erfassungsbereich:
- Nachrichten nach UTC-Stunde und nach Wochentag (Montag an erster Stelle), verkehrsreichste Stunden und Tage;
- bearbeitet, gelöscht und
missing_on_recheckFreigaben; - Absender mit Nachrichtenanzahl sowie Zeitangaben für die erste und letzte Nachricht;
- die häufigsten Domains und
@handles, einmal pro Nachricht über alle gespeicherten Versionen hinweg gezählt; - Erfassungsbereich:
coverage.gapAufzeichnungen sowie – für den Zugriff auf den gesamten Arbeitsbereich – Zeiträume ohne Heartbeat eines verbundenen Collectors (collector_liveness).
Der Zeitraum umfasst die von Telegram gemeldete Zeit der Nachricht. Die Anzahl der Stunden und Wochentage
hilft bei der Schätzung der Zeitzone eines Absenders. Die Zahlen werden auf
Anfrage aus dem Journal berechnet und nicht gespeichert. Jedes Ergebnis nennt den Journal-Anfang, den es
abdeckt, wenn Ihr Zugriff den gesamten Arbeitsbereich umfasst. Das Einlesen wird nach fünf Sekunden über
das Panel oder nach --timeout-Sekunden lokal (Standard 30) beendet; dann ist complete falsch und
partial bezeichnet den ersten Datensatz, der nicht gelesen wurde. In diesem Fall werden nur die neuesten Datensätze
gezählt.
Exportieren#
export Schreibt pro gespeicherter Beobachtung (neue Nachrichten, Snapshots,
Bearbeitungen, wiederhergestellte Nachrichten, Löschbenachrichtigungen, missing_on_recheck und gespeicherte Mediendateien
) in der Reihenfolge des Protokolls. Jede Zeile enthält dieselben Felder wie die anderen Einträge, einschließlich
des vollständigen Textes. Bei --outputwird die Datei unter einem .partial Namen abgelegt und
erst nach dem Abschlussprotokoll des Panels umbenannt; ein unterbrochener Export hinterlässt keine
Datei und beendet den Vorgang mit dem Code 1. --output überschreibt niemals eine vorhandene Datei. Mit
--output und --jsonwird über stdout eine Zusammenfassung ausgegeben: Datensatzanzahl, letzte Journal-
Sequenz und, bei Zugriff auf den gesamten Arbeitsbereich, der Journal-Anfang.
Ein Export über das Panel erfordert eine Verbindung, die Export-Nachrichten
zulässt
(nur über die Befehlszeile)
; diese Option ist standardmäßig nicht ausgewählt. Diese Datei ist eine Arbeitskopie; für eine überprüfbare
Übergabe verwenden Sie den signierten Export unter Exports
, der mit python -m tgwitness.verify
überprüft wird.
Das Panel überprüft den Zugriff vor der Ausgabe jedes Datensatzes erneut, einschließlich des Abschlussdatensatzes. Ein widerrufener oder abgelaufener Zugriff führt zu einem unvollständigen Export. Lazy-Page-Lesevorgänge teilen sich das Limit der Archiv-Worker mit anderen Abfragen und unterliegen einer begrenzten Wartezeit.
Index and backup#
These two commands read the data directory directly and take no token or --url.
| Befehl | Ergebnis |
|---|---|
tgwitness index status [--workspace ID] [--data-dir DIR] [--json] |
Search index state of one workspace or, by default, every workspace: mode, ready, building or not built, indexed and journal head sequence. Works while the panel runs |
tgwitness index rebuild [--workspace ID] [--data-dir DIR] [--json] |
Rebuilds the index from the first journal record. Rewrites only the derived index, never the signed journal. Exits with code 3 while the panel has the workspace open. Nothing is built when the workspace keeps its index in memory or has search off |
tgwitness backup FOLDER [--data-dir DIR] [--json] |
Copies the whole data directory into a new or empty folder outside it while the panel keeps running, and writes backup-manifest.json with every file's SHA-256 and the journal heads |
index accepts --workspace default or a workspace ID; the default is all. The
backup skips temporary exports, SQLite sidecar files and lock files. The folder
holds the Telegram session and signing keys, so keep it as private as the data
directory. Backup, restore, and capacity
describes restoring and what the next start records.
Agent-Fähigkeit#
.agents/skills/tgwitness-cli/SKILL.md
erklärt einem Agenten, wie diese Befehle zu verwenden sind, wie Datensätze zu zitieren sind und wie mit
erfasstem Text umzugehen ist. Agenten, die .agents/skills laden diese aus einem Repository-Checkout
. Für Claude Code kopieren Sie den tgwitness-cli Ordner in .claude/skills/ in
Ihr Projekt oder ~/.claude/skills/.
MCP und die Befehlszeile#
Beide nutzen dieselben Verbindungen, Gültigkeitsprüfungen und Beschränkungen. MCP-Ergebnisse sind auf
eine 64-KiB-Seite begrenzt, daher bietet MCP keinen Massenexport an; die Befehlszeile gibt die Daten per Stream aus.
get_activity_stats ist für beide verfügbar.