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.
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_recheckcondivisioni; - 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.gapregistrazioni 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.