TgWitness / Documentação

O que foi testado →

Algumas partes desta página ainda estão em inglês: o original em inglês sofreu alterações após ter sido traduzido.

Referência / Arquivo e integrações

Telegram · Linha de comando

Pesquise, leia o contexto, conte atividades e exporte mensagens salvas a partir de scripts e agentes, com saída no formato --json, códigos de saída estáveis e tokens de leitura exclusiva com escopo definido.

TgWitness / Documentação

Integrações com arquivos

MCP somente leitura · Pesquisa de texto completo · 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.

Com --json, a saída padrão (stdout) contém exatamente um documento JSON (export grava linhas JSON). O progresso, as dicas e os erros são direcionados para o stderr. Os códigos de saída são estáveis:

Código Significado
0 Sucesso, incluindo um resultado vazio
1 Falha: painel inacessível, dados ilegíveis, exportação interrompida
2 Erro de uso ou solicitação inválida: data incorreta, opção desconhecida, índice de pesquisa desativado
3 Indisponível no momento: o espaço de trabalho está aberto em um painel em execução, ou o painel solicita que se tente novamente mais tarde (limite de taxa, tempo limite)
4 Acesso negado: token ausente, expirado ou revogado; um chat fora do escopo; uma ferramenta que não permite

Duas maneiras de ler#

Por meio do painel (--url). O comando utiliza a mesma API de arquivo com escopo que MCP. Crie uma conexão em Mais ferramentas → Integrações → MCP: escolha espaços de trabalho e chats, ferramentas e um prazo de validade, depois copie o token uma vez. A conexão é somente para leitura, limitada a esses chats, com restrição de taxa de 60 solicitações por minuto e pode ser revogada ou renovada a qualquer momento. Tokens de login do painel e credenciais do Telegram não funcionam aqui.

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

Um painel remoto requer HTTPS; o HTTP simples é aceito apenas para 127.0.0.1, localhost e ::1. Variáveis de ambiente de proxy são ignoradas e redirecionamentos são recusados, de modo que o token chegue apenas ao endereço que você fornecer.

Diretamente de um espaço de trabalho parado (--data-dir). Lê o diretório de dados com acesso local total, sem um token. Use-o em uma cópia de um diretório de dados ou enquanto a coleta estiver parada. Registros assinados nunca são alterados; assim como no painel, abrir um espaço de trabalho pode atualizar seus índices derivados. Quando o painel tem o espaço de trabalho aberto, o comando sai com código 3; leia pelo painel, em vez disso. Sem --data-dir, TGWITNESS_DATA, ./data/live ou o diretório de dados da instalação que está executando o comando é utilizado.

--workspace ID seleciona um espaço de trabalho (padrão default). tgwitness messages --workspaces lista aqueles que você pode ler.

Comandos#

Comando Resultado
tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N] Melhores correspondências primeiro, incluindo formas de palavras, frases exatas entre aspas, domínios e @username (sintaxe)
tgwitness search QUERY --exact [--before SEQ] Texto exato, do mais recente ao mais antigo, sem o índice
tgwitness context CHAT_ID MESSAGE_ID [--limit N] [--before SEQ] Mensagens salvas dentro de dez IDs de mensagem de cada lado
tgwitness messages [--limit N] [--offset N] Conversas que você pode ler
tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--before SEQ] Mensagens salvas do chat, com as mais recentes em primeiro lugar
tgwitness messages CHAT_ID --message ID Cada versão salva e registro de exclusão de uma mensagem
tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N] Estatísticas de atividade, abaixo
tgwitness export [--chat ID] [--since] [--until] [--output FILE] Observações salvas como linhas JSON na ordem do registro

As datas são 2026-10-01 (meia-noite UTC) ou horários ISO com fuso horário, 2026-10-01T09:00+03:00. Para search, messages e export eles selecionam a hora da observação. As páginas comportam até 50 registros: siga next_offset (--offset) para busca por classificação e next_before (--before) em outros lugares.

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.

Cada resultado de mensagem contém untrusted_content: true , os IDs do espaço de trabalho, do chat e da mensagem, a sequência do diário, o hash do registro salvo e um link para o painel. Edições, avisos de exclusão e missing_on_recheck são registros separados. A cobertura em stats mostra os períodos aos quais um resultado de pesquisa se refere.

Estatísticas de atividade#

stats Conta as observações salvas para um chat, um remetente ou todos os chats no escopo:

  • mensagens por hora UTC e por dia da semana (começando pela segunda-feira), horários e dias de maior movimento;
  • editados, excluídos e missing_on_recheck compartilhamentos;
  • remetentes com contagem de mensagens e horários da primeira e da última mensagem;
  • os domínios mais frequentes e @handles, contados uma vez por mensagem em todas as suas versões salvas;
  • cobertura: coverage.gap registros e, para acesso a todo o espaço de trabalho, períodos sem um sinal de vida do coletor conectado (collector_liveness).

O período seleciona a hora da mensagem informada pelo Telegram. As contagens de horas e dias da semana ajudam a estimar o fuso horário do remetente. Os números são calculados mediante solicitação do diário e não são armazenados. Cada resultado indica o cabeçalho do diário que abrange quando seu acesso abrange o espaço de trabalho. A leitura é interrompida após cinco segundos no painel ou após --timeout segundos localmente (padrão 30); então complete é falso e partial indica o primeiro registro que não foi lido. Nesse caso, apenas os registros mais recentes são contados.

Exportar#

export grava um objeto JSON por observação salva (novas mensagens, capturas de tela, edições, mensagens recuperadas, avisos de exclusão, missing_on_recheck e registros de mídia salvos) na ordem do diário. Cada linha possui os mesmos campos dos demais resultados, com o texto completo. Com --output, o arquivo é gravado com um .partial nome e é renomeado somente após o registro de conclusão do painel; uma exportação interrompida não deixa nenhum arquivo e encerra com o código 1. --output nunca sobrescreve um arquivo existente. Com --output e --json, a saída padrão (stdout) exibe um resumo: contagem de registros, última sequência do diário e, para acesso a toda a área de trabalho, o cabeçalho do diário.

Uma exportação pelo painel requer uma conexão que permita mensagens de exportação (somente linha de comando) ; essa opção não está selecionada por padrão. Este arquivo é uma cópia de trabalho; para uma transferência verificável, use a exportação assinada em Exportações , que é verificada por python -m tgwitness.verify .

O painel verifica novamente o acesso antes de emitir cada registro, incluindo o registro de conclusão. O acesso revogado ou expirado resulta em uma exportação incompleta. As leituras de página diferidas compartilham o limite do processador de arquivos com outras consultas e têm um tempo de espera limitado.

Index and backup#

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

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

Habilidade do agente#

.agents/skills/tgwitness-cli/SKILL.md explica a um agente como usar esses comandos, como citar registros e como tratar o texto capturado. Agentes que leem .agents/skills carregam-no a partir de um checkout do repositório. Para o Claude Code, copie a tgwitness-cli pasta para .claude/skills/ dentro do seu projeto ou ~/.claude/skills/.

MCP e a linha de comando#

Ambos utilizam as mesmas conexões, verificações de escopo e limites. Os resultados do MCP estão limitados a uma página de 64 KiB; portanto, o MCP não oferece exportação em massa; a linha de comando transmite os dados em fluxo contínuo. get_activity_stats está disponível para ambos.