> ## Documentation Index
> Fetch the complete documentation index at: https://docs.saninternet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tarefas agendadas

> Manda o servidor executar alguma coisa sozinho, na hora que você marcar, sem você estar na frente do computador. Serve para limpar arquivos velhos toda noite, gerar um relatório…

**Caminho no painel:** menu da esquerda > Recursos > Tarefas Agendadas

## A tela de lista

É por onde tudo começa. Ela mostra as tarefas que já existem.

![Lista de tarefas agendadas do cliente, com o uso 1 / Ilimitado e uma tarefa desativada](https://mintcdn.com/san-internet/ROiLhCzBw6wgVslN/keyhelp/imagens/tarefas-lista-cliente.png?fit=max\&auto=format\&n=ROiLhCzBw6wgVslN\&q=85\&s=061f53cef30c3a098d16319b2067552e)

Acima da tabela, à esquerda, o painel mostra **quantas tarefas você já usou do seu
limite**, no formato `1 / Ilimitado`.

A caixa marcada são as **três ações de cada linha**, e é fácil passar por elas sem
ver, porque são três ícones pequenos:

| Ícone | O que faz |
| - | - |
| **lápis** | abre a tarefa para você mudar alguma coisa |
| **triângulo** | **executa a tarefa agora**, uma vez, fora do horário dela |
| **lixeira** | abre a tela de excluir |

As colunas dizem:

| Coluna | O que mostra |
| - | - |
| **S** | se a tarefa já foi aplicada no servidor: uma chave inglesa logo depois de salvar, e um quadrado verde, *"Tudo certo"*, quando ela já foi aplicada. **Não mostra o resultado de execução nenhuma**: uma tarefa que nunca rodou também fica com o quadrado verde |
| **Comando** | o que a tarefa executa, e embaixo a descrição que você escreveu |
| **Está ativado** | se ela vai rodar no horário marcado ou não |
| **Agendar** | quando ela roda, em texto |
| **Notificação** | se você recebe e-mail do resultado |
| **Ações** | os três ícones acima |

> [!NOTE]
>
> **Sem nenhuma tarefa, a tabela inteira desaparece**
>
> Não é erro. Enquanto não existir nenhuma tarefa, a tela mostra só o texto de
> apresentação e o botão **Adicionar tarefa**. A tabela nasce junto com a primeira.

## 1. Criar uma tarefa

1. Na tela de lista, clique em **Adicionar tarefa**.

O formulário aparece com a primeira metade assim:

![Começo do formulário de tarefa: Está ativado, Descrição, Tipo de tarefa e Comando, com o caminho da pasta do cliente](https://mintcdn.com/san-internet/ROiLhCzBw6wgVslN/keyhelp/imagens/tarefas-form-topo-cliente.png?fit=max\&auto=format\&n=ROiLhCzBw6wgVslN\&q=85\&s=593a52c2afd30870fa1196f20066e533)

| Campo | O que faz |
| - | - |
| **Está ativado** | marcado, a tarefa roda no horário. Desmarcado, ela fica guardada e não roda. **Você pode criar desativada e ligar depois** |
| **Descrição** | um lembrete para você, escrito com as suas palavras. Aparece embaixo do comando na lista |
| **Tipo de tarefa** | escolhe **o que** vai ser executado, entre três coisas diferentes |

### Os três tipos, e o que cada um pede

**A tela se monta conforme a sua escolha:** ao marcar um tipo, os campos dele
aparecem e os dos outros somem.

| Se você escolher | Aparece |
| - | - |
| **Executar comando** | um campo **Comando**, para uma linha de comando do servidor |
| **Executar script PHP** | uma lista **Intérprete PHP** e um campo **Caminho do script PHP** |
| **Chamar URL** | um campo **URL**, e o painel considera sucesso quando a resposta vier com código 2XX |

**O campo de comando pede caminho completo.** O painel avisa na tela que é preciso
usar caminhos absolutos, e **mostra o começo do caminho da sua pasta** logo abaixo,
para você copiar.

Na lista de intérpretes, o painel marca as versões antigas com a palavra
**Desatualizado** ao lado do número.

### 2. Quando a tarefa roda

![Fim do formulário de tarefa: Agendar, com o fuso do servidor, e as opções de Notificação](https://mintcdn.com/san-internet/ROiLhCzBw6wgVslN/keyhelp/imagens/tarefas-form-base.png?fit=max\&auto=format\&n=ROiLhCzBw6wgVslN\&q=85\&s=bbeebe27f01a89bae47a2f1c71162471)

Escolha em **Selecionar intervalo**. Igual ao tipo, **os campos de horário mudam
conforme a escolha**:

| Intervalo | O que ele pergunta |
| - | - |
| De hora em hora | o minuto |
| **Diário** | a hora, no formato hh:mm |
| Semanal | o dia da semana e a hora |
| Mensal | o dia do mês e a hora |
| Anual | o mês, o dia e a hora |
| Intervalo de minuto | de quantos em quantos minutos |
| Intervalo de hora | de quantas em quantas horas |
| Após a reinicialização do servidor | **nada**, porque não tem horário |
| Sintaxe do cron | uma linha no formato do cron, para quem já conhece |

> [!WARNING]
>
> **O horário é o do servidor, e ele pode não ser o seu**
>
> Logo abaixo de **Agendar**, o painel diz com qual fuso horário o servidor está
> funcionando. Nesta instalação ele diz **America/Sao\_Paulo**, que é o horário de
> Brasília, e a tarefa roda na hora marcada.
>
> **Num servidor em outro fuso, a conta muda.** Com **Etc/UTC**, que está três horas
> à frente de Brasília, uma tarefa marcada para `00:00` roda, no seu relógio, às
> **21:00 do dia anterior**. Se a hora importa, confira o fuso antes de salvar.

### 3. Quem recebe o aviso do resultado

| Escolha | Quando chega e-mail |
| - | - |
| **Sempre** | toda vez que o comando escrever alguma coisa, de texto ou de erro. Sem saída, não chega nada |
| **Sobre erros (STDERR)** | só quando o comando escrever mensagem de erro |
| **Nunca** | nunca |

**Com Sempre ou Sobre erros, aparece o campo Enviar notificação para**, que é
obrigatório e aceita vários endereços separados por vírgula. **Com Nunca, esse
campo some da tela.**

Para terminar, clique em **Salvar**.

## 2. Mudar uma tarefa que já existe

1. Na tela de lista, na linha da tarefa, clique no ícone de **lápis**.
2. Mude o que precisar e clique em **Salvar**.

**A tela é a mesma de criar**, com os campos já preenchidos. O título muda para
**Editar tarefa**.

## 3. Executar agora, e ver o que aconteceu

Serve para testar sem esperar o horário, ou para rodar uma vez fora da hora
marcada.

1. Na tela de lista, na linha da tarefa, clique no ícone de **triângulo**.

**A execução não é imediata.** O painel responde que o comando *"será iniciado em
breve"* e coloca a tarefa numa fila. O resultado passa por três situações:
**Pendente**, depois **Processando**, depois **Concluído**.

> [!NOTE]
>
> **A página não se atualiza sozinha**
>
> Enquanto você não recarregar, ela continua mostrando **Pendente**, mesmo que a
> tarefa já tenha terminado. O próprio painel pede: *"Atualize esta página para
> receber abaixo os relatórios de status atualizados."*

Recarregando, aparece o relatório:

![Relatório de execução: comando, status Concluído, tempo, código de retorno 0 e a saída](https://mintcdn.com/san-internet/ROiLhCzBw6wgVslN/keyhelp/imagens/tarefas-relatorio.png?fit=max\&auto=format\&n=ROiLhCzBw6wgVslN\&q=85\&s=b8f54f8cc78a6ffee7360d2a6bfac24c)

| Linha | O que ela responde |
| - | - |
| **Status** | se terminou |
| **Tempo de execução** | quanto demorou |
| **Código do status de retorno** | `0 (Sucesso)` quer dizer que terminou sem erro. Qualquer outro número é falha |
| **Saída** | o que o comando escreveu. **É aqui que você descobre por que a tarefa não fez o que devia** |
| **Saída de erro (STDERR)** | as mensagens de erro, separadas do resto |

O relatório tem um **X no canto** para fechar. Fechando, ele sai da tela. **Sem
fechar, ele fica**: medido, dois relatórios de um mês antes continuavam no alto
da lista. O link *"Clique aqui para remover todas as tarefas pendentes e
concluídas de uma só vez."*, acima dos relatórios, fecha todos juntos, e some
quando não sobra nenhum.

> [!TIP]
>
> **Tarefa desativada também roda quando você manda rodar**
>
> O **Executar agora** funciona mesmo com **Está ativado** desmarcado. É o que
> permite criar a tarefa desligada, testar à vontade pelo relatório, e só ligar
> quando o resultado estiver certo.

> [!WARNING]
>
> **Comando com `%` passa no teste e falha no horário**
>
> O painel grava o comando do jeito que foi digitado, e o agendador do servidor
> trata o `%` como fim de linha. Um comando como `date "+%F %T"` responde
> *Concluído* no **Executar agora** e **não roda no horário marcado**, sem aviso
> nenhum na tela.
>
> Trocar por `\%` conserta o horário e estraga o **Executar agora**, que passa a
> gravar a barra junto: `\2026-09-15`. O que funcionou nos dois caminhos foi **pôr o
> comando num script** com permissão de execução, e deixar no campo **Comando** só
> o caminho completo dele, como `/home/users/sua-conta/files/tarefa.sh`.

## 4. Ligar e desligar sem abrir a tarefa

Dá para mudar a situação de várias tarefas de uma vez:

1. Na tela de lista, marque a caixa de seleção das tarefas que você quer mudar.
2. Em **Ações em massa**, escolha *"Definir status para Ativado"* ou *"Definir
   status para Desativado"*.
3. Clique em **Aplicar**.

O painel responde *"Os itens selecionados foram atualizados"*, **sem pedir
confirmação**. Mudar status é reversível, e o painel trata assim.

**Excluir em massa é a exceção.** Escolhendo *Excluir seleção*, o painel **não
apaga na hora**: ele leva para a **mesma tela de confirmação da exclusão pela
linha**, com a lista do que vai sumir e a mesma caixa **Confirmação**. Só depois
disso ele responde *"Os itens selecionados foram excluídos"*.

## 5. Excluir uma tarefa

1. Na tela de lista, na linha da tarefa, clique no ícone de **lixeira**.

Abre uma tela que mostra a tarefa inteira antes de apagar, para você conferir:

![Tela de excluir tarefa, com os dados da tarefa, a caixa Confirmação e os botões Voltar a visão geral e Excluir](https://mintcdn.com/san-internet/ROiLhCzBw6wgVslN/keyhelp/imagens/tarefas-excluir-cliente.png?fit=max\&auto=format\&n=ROiLhCzBw6wgVslN\&q=85\&s=6d801426c26ea8b6e9d46031679732cf)

2. Marque a caixa **Confirmação**. Sem ela, a exclusão não acontece.
3. Clique em **Excluir**.

| Botão | O que faz |
| - | - |
| **Voltar a visão geral** | desiste e volta para a lista |
| **Excluir** | apaga a tarefa |

Note também que o título desta tela diz **Deletar tarefa** e o botão diz
**Excluir**, duas palavras para a mesma coisa.

## O que pode dar errado

| Sintoma | Causa | O que fazer |
| - | - | - |
| Criei a tarefa e ela nunca roda | a coluna **Está ativado** mostra *Desativado* | abrir a tarefa e marcar **Está ativado**, ou usar a ação em massa |
| A tarefa roda mas não faz o que eu queria | o comando falhou e você não viu | clicar no **triângulo**, recarregar a página e ler a **Saída** e a **Saída de erro** no relatório |
| **Ela roda três horas antes do que eu marquei** | o horário é o do servidor, e ele está num fuso diferente do seu, como **UTC** | conferir o fuso escrito abaixo de **Agendar** e refazer a conta |
| **Pelo triângulo funciona, e no horário a tarefa não faz nada** | o comando tem `%`, que o agendador corta | pôr o comando num script e chamar o script pelo caminho completo |
| Cliquei em executar e não acontece nada | a página não se atualiza sozinha | recarregar a página. Ela fica em *Pendente* até você recarregar |
| **O relatório sumiu** | ele foi fechado no **X** | executar de novo para ver um relatório novo |
| Não acho o campo do e-mail de notificação | a notificação está em **Nunca**, e aí o campo some | escolher **Sempre** ou **Sobre erros** |
| O comando não acha o meu arquivo | caminho relativo não funciona aqui | usar o caminho completo. O painel mostra o caminho da sua pasta na ajuda do campo |
| Cheguei no meu limite de tarefas | o número acima da tabela mostra quantas você usou | pedir mais a quem administra o servidor |
| Apaguei sem querer | a exclusão não tem desfazer | criar de novo. Antes de excluir, a tela mostra a tarefa inteira: é o momento de conferir |

## Ver também

* [Senha e acesso ao painel](/keyhelp/senha-e-acesso-ao-painel), para trocar a senha e o e-mail que recebe
  estes avisos


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.