---
title: "Cron OpenClaw Não Executa? 9 Correções"
url: "https://openclaw.ia.br/blog/cron-openclaw-nao-executa-troubleshooting/"
markdown_url: "https://openclaw.ia.br/blog/cron-openclaw-nao-executa-troubleshooting.MD"
description: "Cron do OpenClaw não executa ou roda no horário errado? Diagnostique gateway, fuso, sessão, canal, modelo, permissões, histórico e entrega passo a passo."
date: "2026-08-22"
author: "OpenClaw Brasil"
---

# Cron OpenClaw Não Executa? 9 Correções

Cron do OpenClaw não executa ou roda no horário errado? Diagnostique gateway, fuso, sessão, canal, modelo, permissões, histórico e entrega passo a passo.


**Se o cron do OpenClaw não executa, verifique nesta ordem: gateway ativo, job habilitado, fuso horário, próxima execução, sessão e payload compatíveis, modelo disponível, permissões das ferramentas e destino do canal.** Depois force uma execução manual e consulte o histórico do job. Essa sequência separa rapidamente três falhas que parecem iguais: a tarefa não iniciou, iniciou e falhou, ou terminou mas não entregou a mensagem.

Não apague e recrie todos os jobs de imediato. O agendamento pode estar correto enquanto o gateway está parado, o modelo perdeu autenticação ou o resultado foi enviado para outro chat. Preserve o job, anote seu ID e faça o diagnóstico por camadas. Assim você encontra a causa sem perder expressão cron, prompt, destinatário e histórico.

## Resposta rápida: diagnóstico em 5 minutos

| Verificação | Comando ou ação | O que você quer confirmar |
|---|---|---|
| Gateway | `openclaw gateway status` | Serviço ativo e estável |
| Jobs | `openclaw cron list` | Job existe, está habilitado e tem próxima execução |
| Execução manual | `openclaw cron run <jobId> --force` | A tarefa funciona sem esperar o horário |
| Histórico | `openclaw cron runs --id <jobId> --limit 20` | Início, término e erro da execução |
| Canais | `openclaw channels status` | WhatsApp, Telegram ou Discord conectado |
| Saúde geral | `openclaw doctor` | Configuração, modelo e dependências válidos |
| Fuso | Confira `--tz` | Horário interpretado no fuso esperado |

O teste mais informativo é o manual. Se `openclaw cron run <jobId> --force` falha, o problema está no job, no modelo, nas ferramentas ou no canal — não no relógio. Se o teste manual funciona, concentre-se no fuso, na expressão, no estado habilitado e na disponibilidade do gateway no horário agendado.

> Os nomes de flags podem mudar entre versões. Antes de alterar um job importante, compare os exemplos com `openclaw cron --help`, `openclaw cron add --help` e a versão instalada exibida por `openclaw --version`.

## Primeiro: identifique qual das três falhas aconteceu

A frase “o cron não rodou” pode descrever problemas diferentes.

### 1. O job não iniciou

Não aparece uma nova tentativa no histórico. As causas mais prováveis são gateway parado, job desabilitado, horário futuro inesperado, fuso incorreto ou expressão cron diferente do que você imaginou.

### 2. O job iniciou e falhou

Existe uma execução no histórico, mas ela termina com erro. Procure autenticação do modelo, ferramenta indisponível, arquivo sem permissão, timeout, prompt inválido ou integração desconectada.

### 3. O job terminou, mas a mensagem não chegou

O trabalho pode ter sido concluído internamente sem `--deliver`, enviado para outro destinatário ou bloqueado por um canal offline. Também pode haver uma execução “silenciosa” por desenho: monitoramentos nem sempre devem enviar uma mensagem quando está tudo normal.

Essa classificação evita um erro comum: mexer na expressão cron quando, na verdade, o agente executou e só falhou na entrega.

## 1. Confirme que o gateway estava ativo

O cron depende do ambiente do OpenClaw estar disponível para disparar e executar o trabalho. Um job bem configurado não compensa gateway parado, processo encerrado após logout, container em crash ou servidor suspenso.

Comece com:

```bash
openclaw gateway status
openclaw doctor
openclaw --version
```

Se o gateway não estiver ativo, inicie-o pelo método usado na sua instalação e acompanhe os logs. Em uma máquina pessoal, confirme que ela não entrou em suspensão no horário. Em VPS, VM, LXC ou Docker, verifique reinícios, falta de memória e espaço em disco.

Sinais de que o agendador é inocente:

- vários jobs diferentes deixaram de rodar no mesmo intervalo;
- o WhatsApp e o Telegram também pararam de responder;
- não existe histórico de tentativa no horário;
- o processo volta a funcionar assim que o gateway é reiniciado.

Se o serviço não sobe, use o guia de [gateway do OpenClaw que não inicia](/troubleshooting/gateway-nao-inicia/). Para ambientes permanentes, siga também o [guia de deploy em VPS](/blog/deploy-openclaw-vps-servidor-guia/) e configure inicialização automática, monitoramento e reinício controlado.

## 2. Verifique se o job existe e está habilitado

Liste os jobs antes de recriar qualquer coisa:

```bash
openclaw cron list
```

Localize o job pelo nome e copie o ID. Confira:

- estado habilitado;
- tipo de agenda (`at`, intervalo ou expressão cron);
- próxima execução;
- sessão escolhida;
- fuso, quando exibido;
- canal e destino de entrega;
- se um job único já foi removido após rodar.

Um lembrete criado com `--delete-after-run` deve desaparecer depois da execução bem-sucedida. Isso não significa perda de configuração: era um job descartável. Já um job recorrente que não aparece pode ter sido removido, criado em outra instalação ou restaurado a partir de um backup antigo.

Se estiver desabilitado, reative:

```bash
openclaw cron edit <jobId> --enable
```

Não use nomes vagos como “teste”, “relatório” ou “verificar”. Prefira nomes que indiquem frequência, fonte e destino:

```text
briefing-diario-07h-telegram
monitor-site-30min-alerta-whatsapp
relatorio-vendas-sexta-18h
```

Nomes descritivos diminuem o risco de editar o job errado quando a instalação cresce.

## 3. Corrija fuso horário e expressão cron

O job pode estar executando exatamente como configurado — só que no fuso do servidor. Uma VPS em UTC interpreta `0 7 * * *` de forma diferente de uma pessoa em Brasília quando nenhum timezone foi definido.

Para horários brasileiros, torne o fuso explícito:

```bash
--tz "America/Sao_Paulo"
```

Outros exemplos:

- `America/Manaus` para Amazonas;
- `America/Rio_Branco` para Acre;
- o identificador IANA correspondente à localidade real do operador.

Evite confiar apenas em “UTC-3”. Identificadores de região comunicam melhor a intenção e lidam de forma consistente com regras de horário do sistema.

A expressão cron tradicional tem cinco campos:

```text
minuto hora dia-do-mês mês dia-da-semana
```

Exemplos:

| Expressão | Execução esperada |
|---|---|
| `0 7 * * *` | Todos os dias às 7h |
| `0 9 * * 1-5` | Segunda a sexta às 9h |
| `*/30 * * * *` | A cada 30 minutos |
| `0 8,12,18 * * *` | Todos os dias às 8h, 12h e 18h |
| `0 18 * * 5` | Sexta-feira às 18h |
| `0 0 1 * *` | Primeiro dia de cada mês à meia-noite |

Erros frequentes:

- trocar minuto e hora;
- presumir que o dia da semana começa em 1 sem verificar a convenção;
- usar horário local enquanto o servidor opera em UTC;
- criar uma data ISO sem indicar fuso;
- esperar execução retroativa depois que o gateway ficou desligado;
- testar um job mensal e concluir em cinco minutos que ele não funciona.

Para validar, edite temporariamente uma cópia de teste para os próximos minutos ou force a execução manual. Não transforme um job de produção em `*/1 * * * *` sem limitar custo e entrega: um erro pode gerar mensagens a cada minuto.

O guia de [agendamento de tarefas no OpenClaw](/blog/agendamento-tarefas-openclaw-cron-guia/) explica expressões, sessões e exemplos completos.

## 4. Force uma execução e leia o histórico

Depois de confirmar gateway, job e horário, rode:

```bash
openclaw cron run <jobId> --force
```

Em seguida:

```bash
openclaw cron runs --id <jobId> --limit 20
```

Observe quatro momentos:

1. o job foi aceito para execução;
2. o agente iniciou um turno ou evento;
3. ferramentas e modelo responderam;
4. a entrega ao canal foi concluída.

Anote o erro exato, horário e ID da tentativa. “Não funcionou” é pouco acionável; “o job iniciou às 07:00, o modelo retornou erro de autenticação e nenhuma entrega foi tentada” aponta diretamente para a credencial.

Se o histórico não recebe uma nova tentativa mesmo com `--force`, valide a versão e a sintaxe com `openclaw cron run --help`. Depois execute `openclaw doctor`. Pode haver configuração inválida ou incompatibilidade após uma atualização.

Se a execução manual funciona e a automática não, volte ao relógio: fuso, expressão, estado habilitado e gateway disponível no horário são os principais suspeitos.

## 5. Confira a compatibilidade entre sessão e payload

O cron pode executar na sessão principal ou em uma sessão isolada. Esses modos atendem necessidades diferentes.

### Sessão principal

É apropriada quando a tarefa depende do contexto da conversa principal ou precisa inserir um evento que o agente tratará naquele fluxo. Um lembrete contextual pode usar um evento de sistema e acordar o agente.

### Sessão isolada

É melhor para relatórios, monitoramentos e rotinas independentes. Ela evita poluir o histórico principal, pode usar outro modelo e produz um turno completo com instrução própria.

Um job pode falhar quando mistura parâmetros destinados a modos diferentes. Se você copiou um comando antigo, confira na ajuda da sua versão quais combinações são aceitas para:

- `--session main`;
- `--session isolated`;
- evento de sistema;
- mensagem para turno do agente;
- entrega a canal;
- modelo e nível de raciocínio.

Para diagnosticar, reduza o job a uma instrução mínima:

```text
Responda apenas: CRON_OK, com o horário atual e o nome desta tarefa.
```

Se isso roda, a estrutura do job está saudável. Reintroduza ferramentas, fontes e entrega uma camada por vez. O objetivo é descobrir qual componente adicional causa a falha.

## 6. Teste modelo, API key e limites de custo

O relógio pode disparar corretamente e o agente falhar antes de produzir qualquer resposta. Isso acontece quando:

- a API key expirou, foi revogada ou ficou sem crédito;
- o nome do modelo mudou ou não está disponível na conta;
- o provedor aplica rate limit;
- o contexto ficou grande demais;
- o job usa um modelo diferente do modelo padrão;
- o provedor estava indisponível no horário.

Execute um teste simples no mesmo ambiente e, quando possível, com o mesmo modelo do job. Rode `openclaw doctor` e consulte o histórico para distinguir autenticação, limite e timeout.

Se aparecer erro 429 no Claude, veja [como resolver limite da API do Claude](/troubleshooting/claude-api-erro-429/). Para credenciais, use o guia de [API key inválida](/troubleshooting/api-key-invalida/). Se o custo está subindo por repetição ou prompts grandes, consulte [como reduzir custo de API](/troubleshooting/custo-api-alto/) e [quanto custa usar OpenClaw](/blog/quanto-custa-openclaw-analise-tokens/).

Nunca coloque a chave dentro do texto do job, do prompt ou de um print de suporte. O cron deve referenciar a configuração segura do ambiente.

## 7. Valide ferramentas, arquivos e permissões

Um job manual simples pode funcionar enquanto a rotina real falha ao tentar ler e-mail, calendário, arquivos ou navegador. O histórico costuma revelar a primeira ferramenta que retornou erro.

Faça o teste em degraus:

1. peça uma resposta sem ferramenta;
2. consulte apenas uma fonte;
3. gere o resumo sem entregar;
4. entregue o resultado no canal;
5. só então adicione ações de escrita ou alteração.

Confira se o processo do gateway possui acesso aos arquivos e variáveis necessários. Uma tarefa executada como serviço pode ter ambiente diferente do seu terminal interativo. Caminhos relativos, variáveis carregadas apenas no seu shell e credenciais salvas para outro usuário são causas clássicas.

Também verifique se a fonte está disponível no horário. Uma rotina que lê um volume montado, um banco interno ou um navegador remoto pode falhar enquanto o restante do OpenClaw continua saudável.

Para erros genéricos de acesso, consulte [erro de permissão no OpenClaw](/troubleshooting/erro-permissao/). Para automações com navegador, veja [falha do browser](/troubleshooting/browser-falha/).

## 8. Separe execução de entrega ao canal

Nem todo job envia mensagem automaticamente. Uma rotina isolada pode concluir e registrar o resultado sem `--deliver`. Isso é útil para verificações silenciosas, mas confunde quando você espera receber um WhatsApp.

Confira três elementos:

- entrega ativada;
- canal correto;
- destinatário no formato esperado pela sua versão.

Depois valide os canais:

```bash
openclaw channels status
```

Teste o canal fora do cron. Se uma mensagem manual também não chega, resolva a conexão primeiro. No WhatsApp, sessão desconectada, QR expirado ou número incorreto podem impedir a entrega. No Telegram, token, chat ID e permissão do bot são pontos comuns.

Use os guias de [WhatsApp desconectando](/troubleshooting/whatsapp-desconecta/), [Telegram que não responde](/troubleshooting/telegram-nao-responde/) e [mensagens não enviadas](/troubleshooting/mensagens-nao-enviadas/) conforme o sintoma.

Também confirme se o job foi desenhado para não notificar no caminho feliz. Um monitor de site pode registrar “online” internamente e só enviar alerta quando detecta indisponibilidade. Nesse caso, ausência de mensagem é o comportamento correto.

## 9. Revise atualização, backup e arquivos do cron

Se os jobs pararam logo depois de uma atualização, não edite tudo ao mesmo tempo. Registre:

```bash
openclaw --version
openclaw doctor
openclaw cron list
```

Compare a sintaxe da versão atual com a configuração existente. Faça backup antes de migrar ou reparar. Os arquivos do agendador são estado operacional; não devem ser editados manualmente enquanto o OpenClaw está em uso.

Uma atualização pode afetar:

- nome de flags;
- modelo configurado;
- validação do arquivo de configuração;
- usuário do serviço;
- localização do runtime;
- sessão do canal;
- permissões do diretório de dados.

Se necessário, siga [como atualizar o OpenClaw sem perder configuração](/blog/como-atualizar-openclaw-sem-perder-configuracao/) e o troubleshooting de [falha ao atualizar](/troubleshooting/atualizacao-falhou/). Tenha a versão anterior registrada para rollback e valide um job de teste antes de reabilitar automações sensíveis.

O [guia de backup do OpenClaw](/guias/backup/) deve incluir jobs, configuração, workspace, memória e inventário de integrações. Um backup só é confiável quando a restauração foi testada.

## Árvore de decisão para cron que não funciona

Use este roteiro:

```text
O job aparece em `cron list`?
├─ Não → procure outra instalação/usuário, restaure backup ou recrie conscientemente.
└─ Sim
   ├─ Está habilitado e com próxima execução correta?
   │  ├─ Não → corrija estado, fuso ou expressão.
   │  └─ Sim
   │     ├─ `cron run --force` cria uma tentativa?
   │     │  ├─ Não → verifique versão, gateway, doctor e sintaxe.
   │     │  └─ Sim
   │     │     ├─ A tentativa termina com erro?
   │     │     │  ├─ Sim → leia modelo, ferramenta, permissão ou timeout.
   │     │     │  └─ Não
   │     │     │     ├─ A mensagem chegou?
   │     │     │     │  ├─ Não → confira deliver, canal e destinatário.
   │     │     │     │  └─ Sim → o job funciona; revise apenas o agendamento.
```

Essa árvore reduz o problema a uma camada por vez. Não avance para canal enquanto a execução falha; não investigue modelo se o job nem inicia.

## Job mínimo para testar o agendador

Crie um job descartável com instrução curta e entrega para um canal de teste. Ajuste as flags à ajuda da versão instalada:

```bash
openclaw cron add \
  --name "diagnostico-cron-5min" \
  --at "5m" \
  --session isolated \
  --message "Responda apenas CRON_OK e o horário atual." \
  --deliver \
  --channel telegram \
  --to "SEU_CHAT_ID"
```

Depois:

1. confirme o job em `openclaw cron list`;
2. anote a próxima execução;
3. mantenha o gateway ativo;
4. confira o histórico após o horário;
5. remova o teste quando terminar.

Se o teste passa, copie a configuração do job real por etapas: primeiro agenda, depois modelo, depois uma ferramenta, depois o prompt completo e por fim o destino definitivo.

## Como evitar que o problema volte

### Use um job sentinela

Agende uma rotina pequena que registre saúde uma ou duas vezes ao dia. Ela deve confirmar gateway, modelo e canal sem executar trabalho caro. Se o sentinela falha junto com outras tarefas, a causa é sistêmica.

### Monitore ausência, não só erro

Um relatório que deveria chegar às 7h e não chegou é um incidente mesmo sem mensagem de erro. Defina uma janela: se não houver recibo até 7h15, acione um alerta independente.

### Gere recibos de execução

Para rotinas importantes, inclua:

- nome e ID do job;
- horário previsto e horário real;
- fontes consultadas;
- resultado ou motivo de falha;
- canal de entrega;
- versão da configuração.

### Limite repetição e custo

Não configure retry infinito. Uma API indisponível pode transformar um job barato em centenas de chamadas. Defina teto, espera entre tentativas e condição de escalonamento.

### Mantenha um botão de pausa

Saiba desabilitar um job sem apagar sua definição:

```bash
openclaw cron edit <jobId> --disable
```

Isso é essencial quando uma integração começa a duplicar mensagens ou produzir saídas incorretas.

### Teste depois de mudanças

Rode manualmente um conjunto pequeno após atualizar OpenClaw, trocar modelo, alterar uma skill, restaurar backup ou reconectar canal. O guia de [boas práticas do OpenClaw](/blog/boas-praticas-openclaw-producao/) detalha rollout, observabilidade e rollback.

## Cron, heartbeat ou webhook: você escolheu o gatilho certo?

Às vezes o cron “não funciona bem” porque não é o mecanismo adequado.

| Gatilho | Use quando | Exemplo |
|---|---|---|
| Cron | Existe horário ou frequência previsível | Briefing todos os dias às 7h |
| Heartbeat | Verificações podem ser agrupadas e toleram variação | Checar periodicamente se há algo urgente |
| Webhook | Um sistema externo sabe exatamente quando chamar | Novo pedido aprovado no e-commerce |
| Comando manual | O trabalho ainda está em piloto | Gerar relatório sob demanda |

Não use cron de um em um minuto para simular evento em tempo real se o sistema oferece webhook. Não use heartbeat para entrega que precisa ocorrer exatamente às 9h. O guia de [heartbeat no OpenClaw](/blog/heartbeat-openclaw-agente-proativo-sem-spam/) ajuda a separar os dois mecanismos.

## Checklist final antes de considerar resolvido

- [ ] Gateway permanece ativo durante a janela do job.
- [ ] `openclaw doctor` não mostra erro crítico.
- [ ] Job aparece habilitado em `openclaw cron list`.
- [ ] Próxima execução corresponde ao horário e fuso desejados.
- [ ] Execução forçada termina com sucesso.
- [ ] Histórico registra início, término e resultado.
- [ ] Modelo e API key funcionam no mesmo ambiente.
- [ ] Ferramentas têm acesso às fontes necessárias.
- [ ] Entrega está ativada quando uma mensagem é esperada.
- [ ] Canal e destinatário foram testados separadamente.
- [ ] Job não produz duplicidade nem retry ilimitado.
- [ ] Existe backup e forma de pausar a rotina.

## Perguntas frequentes

### Por que o cron do OpenClaw não executa?

As causas mais comuns são gateway parado, job desabilitado, fuso horário incorreto, expressão cron errada ou incompatibilidade entre sessão e payload. Se existe tentativa no histórico, investigue modelo, API key, ferramenta, permissão e canal. Force uma execução para separar falha de agendamento de falha da tarefa.

### Como testar um cron do OpenClaw sem esperar o horário?

Use `openclaw cron run <jobId> --force` e depois consulte `openclaw cron runs --id <jobId> --limit 20`. Confirme a sintaxe na ajuda da sua versão. O teste manual mostra se o conteúdo e as integrações do job funcionam independentemente do relógio.

### Por que o cron roda no horário errado?

Normalmente o servidor está em UTC ou em outro fuso e o job não definiu `--tz`. Use um identificador como `America/Sao_Paulo`, confira minuto e hora da expressão e valide a próxima execução exibida pela listagem do cron.

### O job executou, mas a mensagem não chegou. O que fazer?

Confira se a entrega foi ativada, se canal e destinatário estão corretos e se `openclaw channels status` mostra conexão saudável. Teste uma mensagem fora do cron. Também verifique se o job foi desenhado para registrar silenciosamente quando não há alerta.

### Cron funciona com o gateway desligado?

Não conte com isso. O ambiente responsável pelo agendamento e pela execução precisa estar disponível no horário. Em computador pessoal, suspensão também interrompe a operação. Para tarefas 24 horas, use um host permanente com serviço automático, monitoramento e backup.

### Devo usar sessão main ou isolated?

Use main quando a rotina depende do contexto da conversa principal ou injeta um evento naquele fluxo. Use isolated para tarefas independentes, relatórios e monitoramentos que precisam de instrução e histórico próprios. Confira quais payloads sua versão aceita em cada modo.

### Atualizar o OpenClaw pode quebrar jobs existentes?

Pode haver mudança de configuração, flags, modelo ou ambiente do serviço. Antes de atualizar, registre versão, faça backup e teste um job não crítico. Depois execute `openclaw doctor`, confira a lista e rode manualmente as automações essenciais.

### Como impedir cron duplicado?

Use nomes únicos, confira `openclaw cron list` antes de adicionar outro job e mantenha recibos com ID. Se há mensagens duplicadas, desabilite os candidatos um por vez e consulte o histórico. Não apague todos: preserve evidência para localizar a origem.

## Próximo passo

Escolha um job que falhou e execute agora o diagnóstico mínimo:

1. confirme o gateway;
2. copie o ID em `openclaw cron list`;
3. verifique fuso e próxima execução;
4. force uma tentativa;
5. leia o histórico;
6. teste modelo, ferramenta e canal separadamente;
7. corrija somente a camada que falhou;
8. rode novamente e registre um recibo de sucesso.

Depois que o job estiver estável, volte ao [guia completo de cron no OpenClaw](/blog/agendamento-tarefas-openclaw-cron-guia/) para organizar sessões e expressões, e use o [checklist de produção](/blog/checklist-producao-openclaw-whatsapp-telegram/) antes de depender da rotina em atendimento, vendas ou operação. Cron confiável não é apenas “rodar no horário”: é iniciar, concluir, entregar, deixar evidência e falhar de forma compreensível quando uma dependência sai do ar.