TgWitness / Documentazione

Cosa è stato testato →

Alcune parti di questa pagina sono ancora in inglese: il testo originale in inglese è stato modificato dopo la traduzione.

Riferimento / Archivio e integrazioni

Telegram · Riga di comando

Effettuare ricerche, leggere il contesto, contare le attività ed esportare i messaggi salvati da script e agenti, con output in formato --json, codici di uscita stabili e token di sola lettura con ambito limitato.

TgWitness / Documentazione

Integrazioni con gli archivi

MCP in sola lettura · Ricerca full-text · 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.

Con --json, stdout trasmette esattamente un documento JSON (export scrive righe JSON). Lo stato di avanzamento, i suggerimenti e gli errori vengono inviati a stderr. I codici di uscita sono stabili:

Codice Significato
0 Esito positivo, compreso un risultato vuoto
1 Errore: pannello non raggiungibile, dati illeggibili, esportazione interrotta
2 Errore di utilizzo o richiesta non valida: data errata, opzione sconosciuta, indice di ricerca disattivato
3 Al momento non disponibile: l'area di lavoro è aperta in un pannello attivo, oppure il pannello richiede di riprovare più tardi (limite di frequenza, timeout)
4 Accesso negato: token mancante, scaduto o revocato, una chat al di fuori del suo ambito di applicazione, uno strumento non consentito

Due modi di leggere#

Tramite il pannello (--url). Il comando utilizza la stessa API di archiviazione con ambito di MCP. Crea una connessione in Altri strumenti → Integrazioni → MCP: scegli spazi di lavoro e chat, strumenti e una scadenza, quindi copia il token una volta. La connessione è di sola lettura, limitata a quelle chat, con un limite di 60 richieste al minuto e può essere revocata o rotata in qualsiasi momento. I token di accesso al pannello e le credenziali di Telegram non funzionano qui.

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

Un pannello remoto richiede HTTPS; l'HTTP semplice è accettato solo per 127.0.0.1, localhost e ::1. Le variabili d’ambiente del proxy vengono ignorate e i reindirizzamenti sono rifiutati, in modo che il token raggiunga esclusivamente l’indirizzo specificato.

Direttamente da uno spazio di lavoro arrestato (--data-dir). Legge la directory dei dati con pieno accesso locale, senza token. Utilizzarlo su una copia della directory dei dati o mentre la raccolta è arrestata. I record firmati non vengono mai modificati; come nel pannello, l’apertura di uno spazio di lavoro può aggiornare gli indici derivati. Quando il pannello ha lo spazio di lavoro aperto, il comando termina con codice 3; leggere invece tramite il pannello. In assenza di --data-dir, TGWITNESS_DATA, ./data/live , viene utilizzata la directory dei dati dell’installazione in cui viene eseguito il comando.

--workspace ID seleziona un'area di lavoro (per impostazione predefinita default). tgwitness messages --workspaces elenca quelli che è possibile leggere.

Comandi#

Comando Risultato
tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N] I risultati più pertinenti per primi, con forme delle parole, frasi esatte tra virgolette, domini e @username (sintassi)
tgwitness search QUERY --exact [--before SEQ] Testo esatto, dal più recente al più vecchio, senza l'indice
tgwitness context CHAT_ID MESSAGE_ID [--limit N] [--before SEQ] Messaggi salvati entro dieci ID di messaggio in entrambe le direzioni
tgwitness messages [--limit N] [--offset N] Chat che puoi leggere
tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--before SEQ] Messaggi salvati della chat, dal più recente al più vecchio
tgwitness messages CHAT_ID --message ID Ogni versione salvata e ogni registrazione di cancellazione di un messaggio
tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N] Statistiche sulle attività, di seguito
tgwitness export [--chat ID] [--since] [--until] [--output FILE] Osservazioni salvate come righe JSON nell’ordine in cui compaiono nel registro

Le date sono 2026-10-01 (mezzanotte UTC) oppure in formato ISO con indicazione del fuso orario, 2026-10-01T09:00+03:00. Per quanto riguarda search, messages e export si seleziona l’ora dell’osservazione. Le pagine contengono fino a 50 record: seguire next_offset (--offset) per la ricerca per ordine di priorità e next_before (--before) altrove.

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.

Ogni risultato di messaggio riporta untrusted_content: true , l’ID dell’area di lavoro, della chat e del messaggio, la sequenza del registro, l’hash del record salvato e un link al pannello. Le modifiche, gli avvisi di cancellazione e missing_on_recheck sono record separati. La copertura in stats mostra i periodi a cui si riferisce un risultato di ricerca.

Statistiche sulle attività#

stats Conta le osservazioni salvate relative a una chat, a un mittente o a tutte le chat incluse nell'ambito di analisi:

  • messaggi per ora UTC e per giorno della settimana (a partire dal lunedì), ore e giorni di maggiore traffico;
  • modificati, eliminati e missing_on_recheck condivisioni;
  • mittenti con il numero di messaggi e le date e gli orari del primo e dell’ultimo messaggio;
  • i domini più frequenti e @handles, conteggiati una volta per messaggio in tutte le sue versioni salvate;
  • copertura: coverage.gap registrazioni e, per l’accesso all’intero spazio di lavoro, periodi in cui non è presente un segnale di attività del collettore connesso (collector_liveness).

Il periodo seleziona l’ora del messaggio riportata da Telegram. Il conteggio delle ore e dei giorni della settimana aiuta a stimare il fuso orario del mittente. I dati vengono calcolati su richiesta dal registro e non vengono memorizzati. Ogni risultato indica l’intestazione del registro che copre quando l’accesso si estende all’area di lavoro. La lettura si interrompe dopo cinque secondi tramite il pannello, oppure dopo --timeout secondi localmente (30 per impostazione predefinita); a quel punto complete è falso e partial indica il primo record che non è stato letto. In tal caso vengono contati solo i record più recenti.

Esporta#

export scrive un oggetto JSON per ogni osservazione salvata (nuovi messaggi, istantanee, modifiche, messaggi recuperati, avvisi di cancellazione, missing_on_recheck e registrazioni multimediali salvate) nell’ordine del registro. Ogni riga presenta gli stessi campi degli altri risultati, con il testo completo. Con --output, il file viene salvato con un .partial nome e viene rinominato solo dopo il completamento della registrazione del pannello; un’esportazione interrotta non lascia alcun file e termina con il codice 1. --output non sovrascrive mai un file esistente. Con --output e --json, stdout riporta un riepilogo: numero di record, ultima sequenza del journal e, per l’accesso all’intero spazio di lavoro, l’intestazione del journal.

Un’esportazione tramite il pannello richiede una connessione che consenta l’esportazione dei messaggi (solo da riga di comando) ; non è selezionata per impostazione predefinita. Questo file è una copia di lavoro; per un trasferimento verificabile utilizzare l’esportazione firmata in Esportazioni , che viene verificata da python -m tgwitness.verify .

Il pannello ricontrolla l’accesso prima di emettere ogni record, compreso il record di completamento. Un accesso revocato o scaduto comporta un’esportazione incompleta. Le letture differite delle pagine condividono il limite dei worker dell’archivio con altre query e hanno un tempo di attesa limitato.

Index and backup#

These two commands read the data directory directly and take no token or --url.

Comando Risultato
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.

Competenze dell’agente#

.agents/skills/tgwitness-cli/SKILL.md spiega a un agente come utilizzare questi comandi, come citare i record e come trattare il testo acquisito. Gli agenti che leggono .agents/skills lo caricano da un repository checkout. Per Claude Code, copiare la tgwitness-cli cartella nel .claude/skills/ nel tuo progetto oppure ~/.claude/skills/.

MCP e la riga di comando#

Entrambi utilizzano le stesse connessioni, gli stessi controlli di ambito e gli stessi limiti. I risultati di MCP sono limitati a una pagina da 64 KiB, pertanto MCP non offre l’esportazione in blocco; la riga di comando ne esegue lo streaming. get_activity_stats è disponibile per entrambi.