# AI Crawler Manager: documentação
> Apresentação O AI Crawler Manager (slug técnico: dfaicrawlermanager) dá à sua loja PrestaShop 8 ou 9 o controlo fino do tráfego gerado pelos bots de IA: GPTBot da OpenAI, ClaudeBot…
- Página:
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/ai-crawler-manager/index.md), [en](https://www.datafirefly.com/en/documentation/ai-crawler-manager/index.md), [es](https://www.datafirefly.com/es/documentation/ai-crawler-manager/index.md), [de](https://www.datafirefly.com/de/documentation/ai-crawler-manager/index.md), [it](https://www.datafirefly.com/it/documentation/ai-crawler-manager/index.md), [pl](https://www.datafirefly.com/pl/documentation/ai-crawler-manager/index.md), [nl](https://www.datafirefly.com/nl/documentation/ai-crawler-manager/index.md)
- Índice:
## Apresentação
O **AI Crawler Manager** (slug técnico: `dfaicrawlermanager`) dá à sua loja PrestaShop 8 ou 9 o controlo fino do tráfego gerado pelos bots de IA: GPTBot da OpenAI, ClaudeBot da Anthropic, Google-Extended, Applebot-Extended, PerplexityBot, Bytespider da ByteDance e mais de 25 outros crawlers, atualizados a maio de 2026.
Três mecanismos de proteção complementares:
- **Construtor visual do robots.txt** — autoriza/bloqueia cada bot através de um interruptor, aplica uma predefinição num clique e escreve o ficheiro sem estragar as suas diretivas manuais.
- **Bloqueio HTTP 403** — para os bots que ignoram o robots.txt (Bytespider, anthropic-ai legacy), devolve um código 403 logo no primeiro pedido, antes de qualquer processamento do PrestaShop.
- **Estatísticas de rastreio** — acompanhamento em tempo real através de hook + importação dos registos Apache/Nginx para medir retroativamente o tráfego de IA.
**Nota** — O módulo nunca toca no seu robots.txt fora da sua própria secção, delimitada pelos marcadores sentinela `# BEGIN DataFirefly AI Crawler Manager` e `# END DataFirefly AI Crawler Manager`. Todo o resto do ficheiro é preservado tal como está e é criado um ficheiro `.bak` em cada escrita.
## Pré-requisitos
- PrestaShop 8.0 → 9.x
- PHP 7.4 no mínimo (PHP 8.0 a 8.3 recomendado)
- MySQL 5.7 / MariaDB 10.3 ou superior
- Permissões de escrita em `/robots.txt` (raiz da loja)
- Para a importação dos registos: acesso de leitura ao registo de acessos do Apache/Nginx (geralmente `/var/log/apache2/access.log`, ou `~/logs/` e `~/access-logs/` em alojamento partilhado com cPanel)
## Instalação
1. Descarregue o ZIP `dfaicrawlermanager-v1.0.0.zip` a partir da sua conta DataFirefly.
2. No back-office do PrestaShop, vá a **Módulos › Gestor de módulos › Carregar um módulo**.
3. Arraste e largue o ZIP, aguarde a confirmação e clique em **Instalar**.
4. Depois de instalado, aparece um novo separador **AI Crawler Manager** no menu da esquerda (em _Configurar_).
A instalação cria 5 tabelas (prefixo `ps_dfaicm_`), preenche automaticamente a lista dos mais de 30 bots de IA e insere 6 separadores de administração.
**Dica** — Não é necessário qualquer `composer install`. O autoloader PSR-4 está incorporado no módulo, no namespace `DataFireflyAiCrawlerManager`.
## Primeira utilização: o painel
O separador **AI Crawler Manager** abre o painel. Numa instalação nova, verá:
- **Bots de IA monitorizados**: mais de 30 (contagem dos bots ativos na base de dados)
- **Bots bloqueados**: 0 (por predefinição, todos os bots estão autorizados)
- **Visitas (30 dias)**: 0 (o acompanhamento em tempo real só arranca depois de ativado)
- **Regras por caminho**: 0
Três ações recomendadas nesta fase:
1. Abrir o **construtor visual do robots.txt** e aplicar uma predefinição (ver secção dedicada).
2. Ativar o **acompanhamento em tempo real** nas Definições para começar a recolher estatísticas.
3. Opcional: importar os seus registos de acesso antigos para ver o rastreio de IA das semanas anteriores.
## Separador Bots de IA
A lista completa dos mais de 30 bots monitorizados, com:
- **Nome de apresentação**: nome comercial (por exemplo, «ClaudeBot»)
- **User-agent**: cadeia exata procurada no cabeçalho HTTP
- **Editora**: empresa (OpenAI, Anthropic, Google, ByteDance, Meta...)
- **Utilização**: _training_ (treino de LLM), _assistant_ (respostas em tempo real), _search_ (motor de pesquisa de IA), _crawl_ (genérico)
- **Respeita o robots.txt**: sim / não (indica se o robots.txt é suficiente)
- **Estado**: autorizado / bloqueado
Ações disponíveis:
- **Editar** um bot para ajustar o seu estado ou acrescentar notas internas.
- **Bloquear / desbloquear em massa** através das ações agrupadas no fundo da lista.
- Qualquer alteração despoleta uma regeneração automática do robots.txt se a opção correspondente estiver ativada nas Definições.
## Construtor visual do robots.txt
O separador mais utilizado: editor visual do ficheiro robots.txt.
### Predefinições num clique
Cinco estratégias prontas a usar:
- **Bloquear apenas o treino** — trava os bots _training_ (GPTBot, ClaudeBot, anthropic-ai, CCBot, Bytespider...) e mantém autorizados os bots _assistant_ e _search_ (ChatGPT-User, Claude-User, OAI-SearchBot...). Recomendado para a maioria das lojas.
- **Estrito** — bloqueia _training_ + _crawl_ genérico e autoriza _assistant_ + _search_.
- **Bloquear tudo** — disallow em todos os mais de 30 bots de IA.
- **Autorizar tudo** — repõe todos os bots como autorizados.
- **Bloquear apenas o Bytespider** — útil se quiser apenas visar o crawler mais agressivo sem mexer no resto.
**Importante** — Uma predefinição sobrepõe-se ao estado de todos os bots abrangidos. É pedida uma confirmação antes de aplicar. Pode depois afinar bot a bot.
### Interruptor por bot
Cada bot tem um interruptor:
- **Verde** = autorizado (nenhuma diretiva `Disallow` no robots.txt)
- **Vermelho** = bloqueado (diretiva `User-agent: X / Disallow: /` escrita na secção gerida)
Uma etiqueta amarela _«ignora o robots.txt»_ assinala os bots para os quais o robots.txt, por si só, é insuficiente. Para esses, ative também o **bloqueio HTTP 403** nas Definições (ver secção dedicada).
### Pré-visualização em direto
O painel da direita apresenta em tempo real o conteúdo que será escrito no robots.txt. Aspeto típico:
```
# BEGIN DataFirefly AI Crawler Manager
# Generated 2026-05-26 14:32 — do not edit manually
User-agent: GPTBot
Disallow: /
User-agent: ClaudeBot
Allow: /
User-agent: Bytespider
Disallow: /
# … outros bots …
Sitemap: https://example.com/sitemap.xml
# END DataFirefly AI Crawler Manager
```
Clique em **Gravar no robots.txt** para escrever o ficheiro. É criado um ficheiro `robots.txt.bak` ao lado em cada gravação.
## Regras por caminho
Para um bloqueio de granularidade fina: autorizar um bot numa parte do site e bloqueá-lo noutra.
Exemplo típico: autorizar o ClaudeBot nas fichas de produto (para que o Claude as recomende) mas bloqueá-lo no blogue (para não ceder o seu conteúdo editorial).
Uma regra é composta por:
- **Bot** — bot visado (ou «todos os bots» através de wildcard)
- **Ação** — `allow` ou `disallow`
- **Caminho** — padrão de URL com wildcard `*` e fim de cadeia `$`
- **Posição** — ordem de avaliação (as regras mais específicas primeiro)
Exemplos de padrões:
- `/blog/*` — qualquer URL que comece por `/blog/`
- `/*.pdf$` — todos os ficheiros PDF
- `/order*` — URL de encomenda
- `/module/dfsavecart/*` — um módulo específico
**Nota** — As regras por caminho são acrescentadas ao robots.txt sob a forma de diretivas `Allow:` / `Disallow:` clássicas, mas servem também para o bloqueio HTTP 403 se o ativar.
## Bloqueio HTTP 403
Alguns bots ignoram deliberadamente o robots.txt. O mais conhecido é o **Bytespider** (ByteDance), mas também algumas versões antigas do _anthropic-ai_. Para estes bots, o robots.txt não chega.
Ative a opção **«Ativar o bloqueio HTTP 403 para os bots bloqueados»** nas Definições. O módulo instala então um hook `actionDispatcherBefore` que:
1. Deteta o user-agent em cada pedido recebido (comparação de cadeias em memória, cerca de 0,1 ms).
2. Se o bot estiver na lista dos bloqueados e o pedido corresponder a uma regra de bloqueio, devolve imediatamente um HTTP 403 antes de qualquer inicialização do PrestaShop.
3. Regista a tentativa na tabela `ps_dfaicm_visit` com a flag `blocked = 1`.
**Dica** — O bloqueio HTTP poupa CPU e base de dados nos bots de maior volume. O Bytespider pode representar vários milhares de acessos por dia numa loja de dimensão média.
## Estatísticas e importação dos registos
O separador **Estatísticas** oferece uma vista a 7, 30 ou 90 dias, com:
- Indicadores globais (visitas totais, bots distintos, acessos bloqueados)
- Gráfico de tráfego diário
- Principais bots por volume
- URL mais visitados
- Registo das 50 visitas mais recentes (data, bot, URL, IP, estado)
### Acompanhamento em tempo real
Se estiver ativado nas Definições, cada pedido é inspecionado e os acessos de bots de IA identificados são registados. O custo adicional é insignificante: menos de 1 % do tráfego chega à fase de escrita.
### Importação dos registos Apache/Nginx
Permite contabilizar retroativamente as visitas de IA, incluindo as anteriores à instalação do módulo.
1. Nas **Definições**, indique o caminho do ficheiro de registo. O módulo propõe uma deteção automática (caminhos comuns do Apache, do Nginx e do cPanel).
2. Escolha o formato (_combined_ por predefinição, ou _common_).
3. No separador **Estatísticas**, clique em **Analisar o registo agora**.
A análise é **incremental**: um deslocamento em bytes é guardado na base de dados. Repetir a operação não cria duplicados. O módulo limita cada execução a 8 MB para evitar tempos limite; em ficheiros muito grandes, bastam várias passagens sucessivas.
Para recomeçar do zero (por exemplo, depois de uma rotação de registos), marque **Repor o deslocamento** nas Definições e volte a lançar a análise.
## Definições
Resumo das opções disponíveis:
### robots.txt
- **Regeneração automática**: regenera o robots.txt automaticamente quando um bot ou uma regra muda
- **Crawl-delay**: intervalo recomendado entre pedidos (0 = desativado, 1-120 segundos)
- **URL do sitemap**: acrescentado no fim da secção gerida
- **Secção global Disallow**: acrescenta também uma secção `User-agent: *` que bloqueia as zonas sensíveis (administração, carrinho, início de sessão)
### Bloqueio HTTP
- **Ativar o bloqueio HTTP 403**: devolve imediatamente um 403 aos bots bloqueados (ver secção dedicada)
### Acompanhamento em tempo real
- **Ativar o acompanhamento**: regista cada visita de IA detetada
- **Retenção**: número de dias de conservação das visitas individuais (7 a 730, predefinição 90). Os agregados diários são conservados por mais tempo.
### Importação dos registos
- **Ativar a análise dos registos**: ativa o botão de importação no separador Estatísticas
- **Caminho do ficheiro**: caminho absoluto, com deteção automática proposta
- **Formato**: combined (Apache/Nginx por predefinição) ou common
- **Repor o deslocamento**: a marcar para reler o ficheiro completo
## Estratégias de bloqueio recomendadas
A escolha depende do seu posicionamento editorial e comercial. Três perfis típicos:
### Loja online clássica (recomendação predefinida)
Aplicar a predefinição **«Bloquear apenas o treino»**. Os bots de treino (GPTBot, ClaudeBot, anthropic-ai, CCBot, Bytespider) ficam bloqueados. Os bots de assistência em tempo real (ChatGPT-User, Claude-User) e de pesquisa por IA (OAI-SearchBot, PerplexityBot, Google-Extended) continuam autorizados: os seus produtos podem continuar a ser recomendados no ChatGPT, no Claude, no Perplexity e nas AI Overviews da Google.
### Marca premium / conteúdo editorial forte
Predefinição **«Estrito»** + regras por caminho para autorizar certas zonas. Exemplo: bloquear todos os bots de IA em todo o lado, exceto `/produto/*` autorizado para o ChatGPT-User e o Claude-User. As suas descrições de produto continuam referenciadas nos assistentes e o seu blogue e os seus guias ficam protegidos.
### Loja em fase de lançamento / pouco conteúdo editorial
Predefinição **«Autorizar tudo»**. A visibilidade nos motores de resposta por IA ultrapassa largamente o risco de cedência de conteúdo. Passará a um bloqueio mais estrito quando o seu catálogo e o seu blogue ganharem valor.
## Manutenção
### Limpeza automática
As visitas individuais mais antigas do que a retenção configurada são eliminadas automaticamente em cada análise de registos. Também pode despoletar uma limpeza manual a partir do separador Estatísticas (botão **«Limpar as visitas antigas»**).
### Cópia de segurança do robots.txt
Cada escrita cria um `robots.txt.bak` ao lado do ficheiro original. Em caso de erro, pode restaurá-lo manualmente por FTP ou através do seu cPanel.
### Atualização da lista de bots
Os novos bots de IA são acrescentados através das atualizações do módulo. A tabela `ps_dfaicm_bot` é atualizada em modo «merge»: um bot que tenha personalizado manualmente nunca é sobreposto.
## Resolução de problemas
### O robots.txt não é gravável
O painel apresenta uma etiqueta vermelha «Not writable». Verifique:
- Permissões do ficheiro `/robots.txt`: devem ser 644 no mínimo e o proprietário deve ser o utilizador PHP/Apache
- Se o ficheiro não existir, verifique as permissões da pasta raiz (755 + proprietário correto)
- Em alguns alojamentos partilhados, o robots.txt é gerado dinamicamente pelo PrestaShop: desative a opção correspondente em Preferências › Tráfego › SEO e URL
### A deteção automática do registo de acessos não encontra nada
O módulo procura os seguintes caminhos: `/var/log/apache2/access.log`, `/var/log/nginx/access.log`, `~/logs/` e `~/access-logs/`. Noutros alojamentos, indique o caminho manualmente. Se não o souber, contacte o apoio do seu alojamento ou consulte a documentação do seu painel de controlo.
### A análise dos registos demora demasiado
O módulo limita cada execução a 8 MB para evitar tempos limite do PHP. Para um ficheiro de 500 MB, conte com 60 a 70 passagens. Cada clique em **«Analisar o registo agora»** recomeça onde a anterior parou, graças ao deslocamento guardado.
### Um bot bloqueado continua a aparecer nas estatísticas
É normal: o acompanhamento em tempo real regista TODAS as visitas de IA detetadas, incluindo as bloqueadas (com a flag `was_blocked = 1`). Isso permite-lhe medir quantas tentativas são efetivamente bloqueadas pela sua configuração.
### Um bot ignora o robots.txt apesar da minha regra
Confirme com uma importação de registos: se continuar a ver acessos com estado 200, o bot ignora efetivamente o robots.txt. Ative o bloqueio HTTP 403 nas Definições. A partir desse momento, os acessos do bot passarão a aparecer com estado 403 e a flag `was_blocked = 1`.
## Desinstalação
Em **Módulos › Gestor de módulos**, clique em **Desinstalar** na ficha do módulo. A operação:
- Elimina as 5 tabelas `ps_dfaicm_*`
- Elimina os 6 separadores de administração
- Retira a secção gerida do robots.txt (os marcadores sentinela e tudo o que delimitam)
- Preserva o resto do robots.txt e o ficheiro `robots.txt.bak`
## Referência técnica
- **Slug técnico**: `dfaicrawlermanager`
- **Namespace**: `DataFireflyAiCrawlerManager`
- **Tabelas criadas**: `ps_dfaicm_bot`, `ps_dfaicm_rule`, `ps_dfaicm_category_rule`, `ps_dfaicm_visit`, `ps_dfaicm_visit_daily`
- **Hooks utilizados**: `actionDispatcherBefore`, `actionAdminControllerSetMedia`, `displayBackOfficeHeader`
- **Separadores do back-office**: Dashboard, Bots, Path rules, Builder, Statistics, Settings (em AdminParentConfigure)
- **Chaves de configuração**: `DFAICM_AUTO_REGEN`, `DFAICM_VISIT_LOG`, `DFAICM_HTTP_BLOCK`, `DFAICM_LOG_PARSING`, `DFAICM_LOG_PATH`, `DFAICM_LOG_FORMAT`, `DFAICM_LAST_PARSE`, `DFAICM_LAST_OFFSET`, `DFAICM_RETENTION`, `DFAICM_CRAWL_DELAY`, `DFAICM_SITEMAP_URL`, `DFAICM_GLOBAL_DISALLOW`, `DFAICM_INSTALLED_AT`
## Apoio ao cliente
Para qualquer questão técnica, contacte a equipa DataFirefly através de **contact@datafirefly.com** ou consulte a sua área de cliente em [datafirefly.com](https://www.datafirefly.com/pt/).