> ## 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 marcada, sem ninguém na frente do computador. Serve para limpeza noturna, geração de relatório, ou chamada periódica de um…

**Caminho no painel:** menu da esquerda > Configuração > cartão **Configurações de
Recursos** > **Tarefas Agendadas**

> [!NOTE]
>
> **Esta tela não é item de menu na área do administrador**
>
> Ela fica dentro da **Configuração**, no cartão Configurações de Recursos, e é o
> único link daquele cartão que abre uma tela própria: os outros são seções da
> própria Configuração. O botão **Voltar a visão geral** desta tela leva de volta
> para lá.

## A tela de lista

É por onde tudo começa. Ela mostra as tarefas que já existem, **de todas as
contas**.

![Lista de tarefas agendadas na área do administrador, com a coluna Proprietário](https://mintcdn.com/san-internet/uqy6kUqe17ldMjVV/keyhelp-admin/imagens/tarefas-lista-admin.png?fit=max\&auto=format\&n=uqy6kUqe17ldMjVV\&q=85\&s=5a52cc42eabaa1fbe2c59e3fa9c72f01)

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 alterar |
| **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 escrita por quem a criou |
| **Está ativado** | se ela vai rodar no horário marcado ou não |
| **Agendar** | quando ela roda, em texto |
| **Proprietário** | em nome de quem ela roda. **É um link: clicar nele entra na conta daquele cliente** |
| **Notificação** | se sai 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,
> e é por isso que a coluna Proprietário não aparece num servidor recém-instalado.

## 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](https://mintcdn.com/san-internet/uqy6kUqe17ldMjVV/keyhelp-admin/imagens/tarefas-form-topo-admin.png?fit=max\&auto=format\&n=uqy6kUqe17ldMjVV\&q=85\&s=30a64ceff12d6326a4ce9fd0b8b67610)

| Campo | O que faz |
| - | - |
| **Está ativado** | marcado, a tarefa roda no horário. Desmarcado, ela fica guardada e não roda. **Dá para criar desativada e ligar depois** |
| **Descrição** | um lembrete em texto livre. 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 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: *"Ao acessar
arquivos, use sempre caminhos absolutos."*

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/uqy6kUqe17ldMjVV/keyhelp-admin/imagens/tarefas-form-base.png?fit=max\&auto=format\&n=uqy6kUqe17ldMjVV\&q=85\&s=96ef141836594fc22b50ddc29ca1b7e8)

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 |

> [!WARNING]
>
> **O horário é o do servidor**
>
> 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.
>
> **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 às **21:00 do dia
> anterior** no relógio de quem está no Brasil.
>
> **Trocar o fuso do servidor já vale para as tarefas.** Medido em 2026-09-15: com o
> fuso trocado de UTC para `America/Sao_Paulo` e o serviço de agendamento rodando
> desde antes da troca, uma tarefa marcada para 11:40 rodou às 11:40 de Brasília.

### 3. Em nome de quem a tarefa roda

**Este campo só existe na área do administrador.** Ele fica entre o horário e a
notificação.

![Campo Proprietário com Sistema (root) escolhido e o aviso sobre o crontab](https://mintcdn.com/san-internet/uqy6kUqe17ldMjVV/keyhelp-admin/imagens/tarefas-proprietario.png?fit=max\&auto=format\&n=uqy6kUqe17ldMjVV\&q=85\&s=bc1587f75aa2b77b53d2bc948fb6e188)

Em **Proprietário** você escolhe entre o **Sistema (root)** e cada conta de usuário
do servidor. A escolha decide **com quais permissões o comando é executado**.

> [!WARNING]
>
> **Tarefas de root mantidas à mão pelo crontab se perdem**
>
> O painel avisa na própria tela: se as tarefas do usuário Sistema já eram mantidas
> pelo comando `crontab`, no console, **é preciso transferir todas para o painel
> antes de salvar este formulário**. O que não estiver aqui é apagado ao salvar.

### 4. 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. Na área do
administrador ele **já vem preenchido** com o e-mail da conta. **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 ninguém 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/uqy6kUqe17ldMjVV/keyhelp-admin/imagens/tarefas-relatorio.png?fit=max\&auto=format\&n=uqy6kUqe17ldMjVV\&q=85\&s=24d10b188d8d8420866394b1aacdde9e)

| 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 no STDOUT. **É aqui que se 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**, mesmo depois de a tarefa ser excluída: medido, o relatório de
uma tarefa excluída semanas antes continuava 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.

Medido com uma tarefa do **Sistema (root)**: o relatório do administrador é igual
ao da área do cliente, com as mesmas linhas.

> [!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 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/nome-da-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 a 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, incluindo o
**Proprietário**:

![Tela de excluir tarefa com a linha Proprietário, a caixa Confirmação e os botões Voltar a visão geral e Excluir](https://mintcdn.com/san-internet/uqy6kUqe17ldMjVV/keyhelp-admin/imagens/tarefas-excluir-admin.png?fit=max\&auto=format\&n=uqy6kUqe17ldMjVV\&q=85\&s=9d7d4cdecdd5d7000bee5e11a9421132)

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 |
| - | - | - |
| **Não acho Tarefas Agendadas no menu** | na área do administrador ela não é item de menu | Configuração > cartão Configurações de Recursos > Tarefas Agendadas |
| 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 devia | o comando falhou e ninguém 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 marcado** | o horário é o do servidor, e ele está num fuso diferente do de quem marcou, 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. Ela fica em *Pendente* até alguém recarregar |
| **O relatório sumiu** | ele foi fechado no **X** | executar de novo para ver um relatório novo |
| **Tarefas de root que existiam no crontab sumiram** | salvar o formulário com o proprietário Sistema reescreve o crontab do root | é o aviso da própria tela. Transferir tudo para o painel **antes** de salvar |
| 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** |
| A tabela não aparece | não há nenhuma tarefa cadastrada no servidor | a tabela nasce com a primeira |

## Ver também

* [Tarefas agendadas (área do cliente)](/keyhelp/tarefas-agendadas), a mesma tela do lado de quem tem conta de usuário
* [Senha e acesso ao painel](/keyhelp-admin/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.