# Cron job no cPanel: 3 decisões para o script rodar sozinho

O cron job do cPanel resolvido como três decisões, com o menu Common Settings no lugar da sintaxe de asteriscos e um arquivo de log como prova de execução no primeiro dia.

> em três decisões. No cPanel, abra Avançado > Cron Jobs, escolha o intervalo pelo menu Common Settings (comece com 1 hora), escreva o comando com o caminho absoluto do arquivo em vez da URL, e acrescente >> log 2>&1 para ter prova de que rodou.

João Rizzon · 2026-10-29 · Painéis

---

Você tem um script que precisa rodar todo dia: limpar uma tabela, enviar um relatório por e-mail, gerar um backup de arquivos, importar um XML de fornecedor. Hoje você abre o navegador e chama o arquivo na mão. O cron job do cPanel faz isso sozinho, no horário que você mandar, sem navegador aberto.

Criar a primeira tarefa agendada não é aprender sintaxe de cron. São três decisões, nesta ordem: **de quanto em quanto tempo**, **qual o caminho completo do arquivo** e **como provar que rodou**. Se você acertar as três, o resto do painel é preenchimento de campo.

## O que o cron job do cPanel executa e o que ele não resolve

Na documentação oficial do cPanel, a interface **Cron Jobs** permite automatizar comandos ou scripts para serem executados em um horário ou intervalo definido ([docs.cpanel.net, Cron Jobs](https://docs.cpanel.net/cpanel/advanced/cron-jobs/)).

Três consequências práticas disso:

- O cron executa **um comando no servidor**, como se você estivesse num terminal. Ele não abre uma página, não tem sessão de navegador, não tem cookie, não tem usuário logado no WordPress.
- Quem roda o comando é **o seu usuário do cPanel**, com as permissões dele. Nada de permissão de root.
- Se o comando imprimir alguma coisa na tela (um `echo`, um aviso do PHP, um erro), o cPanel manda essa saída por e-mail, para o endereço configurado na própria tela de Cron Jobs. Esse comportamento está documentado e é a origem de quase toda caixa de entrada lotada de mensagem de cron.

O que ele não faz: não corrige um script quebrado, não instala dependência que falta e não garante que o ambiente de linha de comando seja igual ao ambiente do navegador. Esses três pontos vêm depois, quando a tarefa já estiver rodando.

## Escolher o intervalo pelo Common Settings em vez de digitar asterisco

A tela de Cron Jobs tem cinco campos de tempo (minuto, hora, dia, mês, dia da semana) e, acima deles, um menu chamado **Common Settings**. A documentação do cPanel descreve esse menu como uma lista de configurações comuns que preenche os campos automaticamente quando você escolhe uma opção.

Use o Common Settings. Sério. No primeiro cron, escolher "Once Per Hour" no menu é mais seguro do que digitar cinco campos de cabeça e descobrir no dia seguinte que o script rodou 1.440 vezes em vez de uma.

### Por que o primeiro agendamento deve ser de 1 hora, não de 5 minutos

A tentação é agendar "a cada 5 minutos" para ver funcionar logo. Dois motivos para não fazer isso no primeiro dia:

- Se o script demora mais do que o intervalo, uma execução começa antes de a anterior terminar. Com 5 minutos isso acontece rápido, e você acaba com várias cópias do mesmo processo disputando o banco de dados.
- Erro de caminho ou de permissão vira dezenas de mensagens de erro em uma hora. Com intervalo de uma hora, você lê uma mensagem, corrige, espera a próxima.

Depois que duas ou três execuções seguidas saírem limpas, aí sim você edita a tarefa e desce o intervalo. Trocar o intervalo é um clique em **Edit** na lista de tarefas existentes.

### O que cada um dos cinco campos de tempo significa

| Você quer | Minuto | Hora | Dia | Mês | Dia da semana |
|---|---|---|---|---|---||
| Uma vez por hora, no minuto 0 | 0 | * | * | * | * |
| Todo dia às 3h da manhã | 0 | 3 | * | * | * |
| A cada 5 minutos | */5 | * | * | * | * |
| Toda segunda-feira às 2h | 0 | 2 | * | * | 1 |

O asterisco significa "qualquer valor". Cinco asteriscos seguidos significam "todo minuto de toda hora de todo dia", que é quase nunca o que você quer.

## Por que o comando aponta para o caminho no disco, não para a URL

Este é o erro número um de quem vem do navegador. No navegador você chama `https://seudominio.com.br/relatorio.php`. No cron, o comando certo aponta para o arquivo no disco.

Um exemplo fictício, com o usuário chamado `exemplo`:

```
/usr/local/bin/php /home/exemplo/public_html/relatorio.php
```

Lendo da esquerda para a direita:

- `/usr/local/bin/php` é o interpretador, o programa que lê e executa o arquivo PHP. Em servidores cPanel esse costuma ser o caminho do PHP de linha de comando, mas confirme o seu: abra o **Terminal** do cPanel (quando disponível) e rode `which php`. A resposta é o caminho que você deve usar.
- `/home/exemplo/public_html/relatorio.php` é o caminho absoluto do script. Troque `exemplo` pelo seu nome de usuário do cPanel, que aparece no canto da tela do painel, e ajuste a pasta se o arquivo não estiver na raiz do site.

Para descobrir o caminho sem adivinhar: abra o **Gerenciador de Arquivos**, navegue até o arquivo, clique com o botão direito e escolha a opção que mostra o caminho (ou olhe a barra de endereço da pasta no topo do gerenciador). Copie e cole. Digitar de cabeça é como se perde uma tarde.

Se o seu script é um shell script `.sh`, o comando é `/bin/bash /home/exemplo/caminho/script.sh`. Se é Python, é o caminho do Python seguido do arquivo. A lógica é sempre a mesma: **interpretador, espaço, caminho absoluto**.

## Como provar que a tarefa rodou gravando um log em arquivo

Sem log, você fica olhando para o painel tentando adivinhar se rodou. Com log, você abre um arquivo e vê a data da última execução.

No primeiro dia, escreva o comando assim (exemplo fictício, mesmo usuário `exemplo`):

```
/usr/local/bin/php /home/exemplo/public_html/relatorio.php >> /home/exemplo/cron-relatorio.log 2>&1
```

A parte nova:

- `>>` manda tudo que o script imprimiria na tela para o arquivo, **acrescentando** ao final. Com um `>` só, cada execução apagaria o conteúdo anterior.
- `/home/exemplo/cron-relatorio.log` é o arquivo de log. Deixe fora de `public_html` para que ninguém leia pela web.
- `2>&1` manda também as mensagens de erro para o mesmo arquivo. Sem isso, o erro continua indo por e-mail e o log fica com metade da história.

Depois da hora marcada, abra o Gerenciador de Arquivos, entre na pasta `/home/exemplo`, clique no `.log` e use **View** ou **Edit**. Se o arquivo existe, o cron executou o comando. Se o arquivo existe mas está vazio, o comando rodou e não imprimiu nada, o que em geral é bom sinal. Se o arquivo não existe, o cron não rodou ou o caminho de destino está errado.

Para marcar a hora de cada execução, faça o próprio script imprimir uma linha com a data no início. Em PHP, `echo date('Y-m-d H:i:s') . " ok\n";` resolve e aparece no log.

### Quando manter e quando parar o e-mail de notificação do cron

Na parte de cima da tela de Cron Jobs há um campo de e-mail. A documentação do cPanel indica que é para lá que vai a saída dos cron jobs. Duas escolhas razoáveis:

- Nos primeiros dias, deixe um e-mail que você lê. É o aviso mais rápido de que algo quebrou.
- Depois que o log estiver funcionando e a tarefa estável, você pode parar de receber mensagem de uma tarefa específica redirecionando a saída, como no exemplo acima, já que com `>> arquivo 2>&1` não sobra nada para enviar.

## Criando a tarefa, clique a clique

### Gere um backup antes da primeira execução automática

Cron não edita arquivo sozinho, mas o seu script talvez edite. Se ele apaga registros, move arquivos ou altera banco, gere um backup antes da primeira execução automática: no cPanel, **Backup** ou **Assistente de Backup**, e baixe pelo menos o banco de dados. Para voltar atrás, restaure esse backup e apague a tarefa pelo botão **Delete**, na lista **Current Cron Jobs**. Se quiser só pausar sem perder o comando, clique em **Edit** e troque o intervalo para algo distante (por exemplo, uma vez por mês), ou coloque um `#` no começo do campo Command para o servidor ignorar a linha.

### Onde fica o Cron Jobs dentro do cPanel

No cPanel, seção **Avançado**, ícone **Cron Jobs**. Se não achar, use a busca no topo do painel e digite cron.

### Selecione Once Per Hour e confira os campos preenchidos

No menu **Common Settings**, selecione "Once Per Hour". Os cinco campos abaixo são preenchidos sozinhos. Confira se fazem sentido antes de seguir.

### Cole o comando completo no campo Command

No campo **Command**, cole a linha completa, com interpretador, caminho absoluto e redirecionamento para o log. Releia o nome de usuário e o nome do arquivo caractere por caractere.

### Adicione a tarefa e encontre ela em Current Cron Jobs

A tarefa aparece na lista **Current Cron Jobs**, no fim da página, com botões de **Edit** e **Delete**. É essa lista que você vai usar para ajustar o intervalo depois.

### Confira o log depois do horário do primeiro disparo

Não fique recarregando o painel. Espere passar o horário do próximo disparo, abra o Gerenciador de Arquivos e leia o `.log`.

## Log vazio ou inexistente: como achar a causa

Tabela de triagem para o primeiro dia:

| Sintoma | Causa provável | O que fazer |
|---|---|---||
| O arquivo de log não foi criado | Caminho do script ou do log errado, ou intervalo ainda não disparou | Confira o caminho no Gerenciador de Arquivos e o horário do servidor |
| Log com "No such file or directory" | Caminho absoluto com erro de digitação ou pasta trocada | Copie o caminho direto do Gerenciador de Arquivos |
| Log com "Permission denied" | Arquivo sem permissão de execução ou pasta inacessível | Ajuste as permissões do arquivo pelo Gerenciador de Arquivos |
| Log com erro do PHP que não aparece no navegador | Ambiente de linha de comando diferente do ambiente web | Rode o mesmo comando no Terminal e compare a saída |
| Script funciona no navegador e falha no cron | Dependência de sessão, de variável de servidor ou de caminho relativo | Troque caminhos relativos por absolutos dentro do script |

As duas últimas linhas são o assunto dos artigos seguintes deste bloco: script que roda no navegador e quebra no cron, escolha do binário certo e dependências que somem na linha de comando. Resolva primeiro o básico: tarefa criada, caminho correto, log sendo escrito.

## Checklist antes de descer o intervalo

Antes de trocar "Once Per Hour" por algo mais agressivo, confirme:

- O log registrou pelo menos duas execuções seguidas sem erro.
- Você sabe quanto tempo o script leva. Se não sabe, imprima a data no começo e no fim e compare.
- O intervalo novo é maior que a duração do script, com folga.
- O log não vai crescer sem controle. Um script que imprime muita coisa a cada 5 minutos gera arquivo grande. Trunque o log de vez em quando ou imprima menos.
- Você sabe desligar a tarefa: lista **Current Cron Jobs**, botão **Delete**.

Feito isso, a decisão de intervalo vira o que ela deveria ser desde o começo: uma escolha de negócio, não uma aposta.

