TgWitness / Dokumentation

Was wurde getestet? →

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.

TgWitness / Dokumentation

Archiv-Integrationen

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_recheck Freigaben;
  • 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.gap Aufzeichnungen 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.