Tarefas agendadas (Cron)

Cron é o agendador integrado do Gateway. Ele persiste tarefas, ativa o agente no momento certo e pode entregar a saída de volta para um canal de chat ou endpoint de webhook.

Início rápido

# Adicione um lembrete de execução única
openclaw cron add \
  --name "Reminder" \
  --at "2026-02-01T16:00:00Z" \
  --session main \
  --system-event "Reminder: check the cron docs draft" \
  --wake now \
  --delete-after-run

# Verifique suas tarefas
openclaw cron list

# Veja o histórico de execuções
openclaw cron runs --id <job-id>

Como o cron funciona

O cron é executado dentro do processo Gateway (não dentro do modelo).
As tarefas persistem em ~/.openclaw/cron/jobs.json, então reinicializações não fazem os agendamentos se perderem.
Todas as execuções do cron criam registros de tarefa em segundo plano.
Tarefas de execução única (--at) são excluídas automaticamente após sucesso por padrão.
Execuções isoladas de cron fazem, em caráter best-effort, o fechamento de abas/processos de navegador rastreados para a sessão cron:<jobId> quando a execução é concluída, para que automações de navegador destacadas não deixem processos órfãos.
Execuções isoladas de cron também se protegem contra respostas de confirmação obsoletas. Se o primeiro resultado for apenas uma atualização de status intermediária (on it, pulling everything together e dicas semelhantes) e nenhuma execução descendente de subagente ainda for responsável pela resposta final, o OpenClaw faz um novo prompt uma vez para obter o resultado real antes da entrega.

A reconciliação de tarefas para o cron pertence ao runtime: uma tarefa ativa de cron permanece ativa enquanto o runtime do cron ainda rastrear essa tarefa como em execução, mesmo que uma linha antiga de sessão filha ainda exista. Assim que o runtime deixar de ser responsável pela tarefa e a janela de tolerância de 5 minutos expirar, a manutenção poderá marcar a tarefa como lost.

Tipos de agendamento

Tipo	Flag da CLI	Descrição
`at`	`--at`	Timestamp de execução única (ISO 8601 ou relativo como `20m`)
`every`	`--every`	Intervalo fixo
`cron`	`--cron`	Expressão cron de 5 campos ou 6 campos com `--tz` opcional

Timestamps sem fuso horário são tratados como UTC. Adicione --tz America/New_York para agendamento por horário local. Expressões recorrentes no início da hora são automaticamente escalonadas em até 5 minutos para reduzir picos de carga. Use --exact para forçar temporização precisa ou --stagger 30s para uma janela explícita.

Dia do mês e dia da semana usam lógica OR

As expressões cron são analisadas pelo croner. Quando os campos de dia do mês e dia da semana não são curingas, o croner faz correspondência quando qualquer um dos campos corresponde — não ambos. Esse é o comportamento padrão do Vixie cron.

# Pretendido: "9h da manhã no dia 15, apenas se for uma segunda-feira"
# Real:      "9h da manhã em todo dia 15, E 9h da manhã em toda segunda-feira"
0 9 15 * 1

Isso dispara ~5–6 vezes por mês em vez de 0–1 vez por mês. O OpenClaw usa aqui o comportamento OR padrão do Croner. Para exigir ambas as condições, use o modificador + de dia da semana do Croner (0 9 15 * +1) ou agende com base em um campo e valide o outro no prompt ou comando da sua tarefa.

Estilos de execução

Estilo	Valor de `--session`	Executa em	Melhor para
Sessão principal	`main`	Próximo turno de heartbeat	Lembretes, eventos do sistema
Isolada	`isolated`	`cron:<jobId>` dedicado	Relatórios, tarefas em segundo plano
Sessão atual	`current`	Vinculada na criação	Trabalho recorrente com contexto
Sessão personalizada	`session:custom-id`	Sessão nomeada persistente	Fluxos que se baseiam no histórico

Tarefas da sessão principal enfileiram um evento do sistema e opcionalmente ativam o heartbeat (--wake now ou --wake next-heartbeat). Tarefas isoladas executam um turno dedicado do agente com uma sessão nova. Sessões personalizadas (session:xxx) persistem contexto entre execuções, permitindo fluxos como reuniões diárias que se baseiam em resumos anteriores. Para tarefas isoladas, o encerramento do runtime agora inclui limpeza best-effort do navegador para essa sessão de cron. Falhas de limpeza são ignoradas para que o resultado real do cron ainda prevaleça. Quando execuções isoladas de cron orquestram subagentes, a entrega também prefere a saída final descendente em vez de texto intermediário obsoleto do pai. Se descendentes ainda estiverem em execução, o OpenClaw suprime essa atualização parcial do pai em vez de anunciá-la.

Opções de payload para tarefas isoladas

--message: texto do prompt (obrigatório para isolada)
--model / --thinking: substituições de modelo e nível de thinking
--light-context: ignora a injeção do arquivo de bootstrap do workspace
--tools exec,read: restringe quais ferramentas a tarefa pode usar

--model usa o modelo permitido selecionado para essa tarefa. Se o modelo solicitado não for permitido, o cron registra um aviso e volta para a seleção de modelo padrão/do agente dessa tarefa. Cadeias de fallback configuradas ainda se aplicam, mas uma substituição simples de modelo sem uma lista explícita de fallback por tarefa não acrescenta mais o primário do agente como um alvo extra oculto de nova tentativa. A precedência de seleção de modelo para tarefas isoladas é:

Substituição de modelo do hook do Gmail (quando a execução veio do Gmail e essa substituição é permitida)
model do payload por tarefa
Substituição de modelo da sessão cron armazenada
Seleção de modelo padrão/do agente

O modo rápido também segue a seleção ativa resolvida. Se a configuração do modelo selecionado tiver params.fastMode, o cron isolado usa isso por padrão. Uma substituição armazenada de fastMode da sessão ainda prevalece sobre a configuração em qualquer direção. Se uma execução isolada atingir uma transferência ativa de troca de modelo, o cron tenta novamente com o provedor/modelo trocado e persiste essa seleção ativa antes da nova tentativa. Quando a troca também traz um novo perfil de autenticação, o cron também persiste essa substituição de perfil de autenticação. As novas tentativas são limitadas: após a tentativa inicial mais 2 novas tentativas de troca, o cron aborta em vez de entrar em loop infinito.

Entrega e saída

Modo	O que acontece
`announce`	Entrega o resumo ao canal de destino (padrão para isolada)
`webhook`	Envia payload do evento concluído por POST para uma URL
`none`	Apenas interno, sem entrega

Use --announce --channel telegram --to "-1001234567890" para entrega em canal. Para tópicos de fórum do Telegram, use -1001234567890:topic:123. Destinos de Slack/Discord/Mattermost devem usar prefixos explícitos (channel:<id>, user:<id>). Para tarefas isoladas sob responsabilidade do cron, o executor é responsável pelo caminho final de entrega. O agente recebe um prompt para retornar um resumo em texto simples, e esse resumo é então enviado por announce, webhook ou mantido internamente para none. --no-deliver não devolve a entrega ao agente; ele mantém a execução interna. Se a tarefa original disser explicitamente para enviar mensagem a algum destinatário externo, o agente deve indicar em sua saída quem/onde essa mensagem deve ir em vez de tentar enviá-la diretamente. As notificações de falha seguem um caminho de destino separado:

cron.failureDestination define um padrão global para notificações de falha.
job.delivery.failureDestination substitui isso por tarefa.
Se nenhum dos dois estiver definido e a tarefa já entregar via announce, as notificações de falha agora usam esse destino principal de anúncio como fallback.
delivery.failureDestination só é compatível com tarefas sessionTarget="isolated" a menos que o modo principal de entrega seja webhook.

Exemplos de CLI

Lembrete de execução única (sessão principal):

openclaw cron add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now

Tarefa isolada recorrente com entrega:

openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize overnight updates." \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

Tarefa isolada com substituição de modelo e thinking:

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 1" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Weekly deep analysis of project progress." \
  --model "opus" \
  --thinking high \
  --announce

Webhooks

O Gateway pode expor endpoints HTTP de webhook para gatilhos externos. Ative na configuração:

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

Autenticação

Toda solicitação deve incluir o token do hook por cabeçalho:

Authorization: Bearer <token> (recomendado)
x-openclaw-token: <token>

Tokens na query string são rejeitados.

POST /hooks/wake

Enfileire um evento do sistema para a sessão principal:

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

text (obrigatório): descrição do evento
mode (opcional): now (padrão) ou next-heartbeat

POST /hooks/agent

Execute um turno isolado do agente:

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4-mini"}'

Campos: message (obrigatório), name, agentId, wakeMode, deliver, channel, to, model, thinking, timeoutSeconds.

Hooks mapeados (POST /hooks/<name>)

Nomes de hook personalizados são resolvidos por hooks.mappings na configuração. Os mapeamentos podem transformar payloads arbitrários em ações wake ou agent com templates ou transformações em código.

Segurança

Mantenha os endpoints de hook atrás de loopback, tailnet ou proxy reverso confiável.
Use um token dedicado para hooks; não reutilize tokens de autenticação do gateway.
Mantenha hooks.path em um subcaminho dedicado; / é rejeitado.
Defina hooks.allowedAgentIds para limitar o roteamento explícito de agentId.
Mantenha hooks.allowRequestSessionKey=false, a menos que você precise de sessões selecionadas pelo chamador.
Se você ativar hooks.allowRequestSessionKey, também defina hooks.allowedSessionKeyPrefixes para restringir os formatos permitidos de chave de sessão.
Payloads de hook são encapsulados com limites de segurança por padrão.

Integração com Gmail PubSub

Conecte gatilhos da caixa de entrada do Gmail ao OpenClaw via Google PubSub. Pré-requisitos: CLI gcloud, gog (gogcli), hooks do OpenClaw ativados, Tailscale para o endpoint HTTPS público.

Configuração pelo assistente (recomendado)

openclaw webhooks gmail setup --account openclaw@gmail.com

Isso grava a configuração hooks.gmail, ativa a predefinição do Gmail e usa Tailscale Funnel para o endpoint de push.

Inicialização automática do Gateway

Quando hooks.enabled=true e hooks.gmail.account está definido, o Gateway inicia gog gmail watch serve na inicialização e renova automaticamente o watch. Defina OPENCLAW_SKIP_GMAIL_WATCHER=1 para desativar isso.

Configuração manual única

Selecione o projeto do GCP que possui o cliente OAuth usado por gog:

gcloud auth login
gcloud config set project <project-id>
gcloud services enable gmail.googleapis.com pubsub.googleapis.com

Crie o tópico e conceda acesso de push do Gmail:

gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
  --role=roles/pubsub.publisher

Inicie o watch:

gog gmail watch start \
  --account openclaw@gmail.com \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

Substituição de modelo do Gmail

{
  hooks: {
    gmail: {
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

Gerenciando tarefas

# Liste todas as tarefas
openclaw cron list

# Edite uma tarefa
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"

# Force a execução de uma tarefa agora
openclaw cron run <jobId>

# Execute apenas se estiver vencida
openclaw cron run <jobId> --due

# Veja o histórico de execuções
openclaw cron runs --id <jobId> --limit 50

# Exclua uma tarefa
openclaw cron remove <jobId>

# Seleção de agente (configurações com múltiplos agentes)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent

Observação sobre substituição de modelo:

openclaw cron add|edit --model ... altera o modelo selecionado da tarefa.
Se o modelo for permitido, exatamente esse provedor/modelo chega à execução do agente isolado.
Se não for permitido, o cron emite um aviso e retorna para a seleção de modelo padrão/do agente da tarefa.
Cadeias de fallback configuradas ainda se aplicam, mas uma substituição simples com --model sem uma lista explícita de fallback por tarefa não recai mais para o modelo primário do agente como um alvo extra silencioso de nova tentativa.

Configuração

{
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1,
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
    },
    webhookToken: "replace-with-dedicated-webhook-token",
    sessionRetention: "24h",
    runLog: { maxBytes: "2mb", keepLines: 2000 },
  },
}

Desative o cron: cron.enabled: false ou OPENCLAW_SKIP_CRON=1. Nova tentativa de execução única: erros transitórios (limite de taxa, sobrecarga, rede, erro de servidor) tentam novamente até 3 vezes com backoff exponencial. Erros permanentes desativam imediatamente. Nova tentativa recorrente: backoff exponencial (30s a 60m) entre novas tentativas. O backoff é redefinido após a próxima execução bem-sucedida. Manutenção: cron.sessionRetention (padrão 24h) remove entradas de sessão de execuções isoladas. cron.runLog.maxBytes / cron.runLog.keepLines fazem poda automática dos arquivos de log de execução.

Solução de problemas

Sequência de comandos

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor

O cron não dispara

Verifique cron.enabled e a variável de ambiente OPENCLAW_SKIP_CRON.
Confirme se o Gateway está em execução contínua.
Para agendamentos cron, verifique o fuso horário (--tz) em relação ao fuso horário do host.
reason: not-due na saída da execução significa que a execução manual foi verificada com openclaw cron run <jobId> --due e a tarefa ainda não estava vencida.

O cron disparou, mas não houve entrega

Modo de entrega none significa que nenhuma mensagem externa é esperada.
Destino de entrega ausente/inválido (channel/to) significa que a saída foi ignorada.
Erros de autenticação do canal (unauthorized, Forbidden) significam que a entrega foi bloqueada pelas credenciais.
Se a execução isolada retornar apenas o token silencioso (NO_REPLY / no_reply), o OpenClaw suprime a entrega direta para saída externa e também suprime o caminho de fallback do resumo enfileirado, então nada é publicado de volta no chat.
Para tarefas isoladas controladas pelo cron, não espere que o agente use a ferramenta de mensagem como fallback. O executor é responsável pela entrega final; --no-deliver a mantém interna em vez de permitir um envio direto.

Cuidados com fuso horário

Cron sem --tz usa o fuso horário do host do gateway.
Agendamentos at sem fuso horário são tratados como UTC.
activeHours do heartbeat usa a resolução de fuso horário configurada.

Relacionado

Automação e tarefas — todos os mecanismos de automação em um só lugar
Tarefas em segundo plano — registro de tarefas para execuções de cron
Heartbeat — turnos periódicos da sessão principal
Fuso horário — configuração de fuso horário

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Tarefas agendadas

Tarefas agendadas (Cron)

Início rápido

Como o cron funciona

Tipos de agendamento

Dia do mês e dia da semana usam lógica OR

Estilos de execução

Opções de payload para tarefas isoladas

Entrega e saída

Exemplos de CLI

Webhooks

Autenticação

POST /hooks/wake

POST /hooks/agent

Hooks mapeados (POST /hooks/<name>)

Segurança

Integração com Gmail PubSub

Configuração pelo assistente (recomendado)

Inicialização automática do Gateway

Configuração manual única

Substituição de modelo do Gmail

Gerenciando tarefas

Configuração

Solução de problemas

Sequência de comandos

O cron não dispara

O cron disparou, mas não houve entrega

Cuidados com fuso horário

Relacionado

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

​Tarefas agendadas (Cron)

​Início rápido

​Como o cron funciona

​Tipos de agendamento

​Dia do mês e dia da semana usam lógica OR

​Estilos de execução

​Opções de payload para tarefas isoladas

​Entrega e saída

​Exemplos de CLI

​Webhooks

​Autenticação

​POST /hooks/wake

​POST /hooks/agent

​Hooks mapeados (POST /hooks/<name>)

​Segurança

​Integração com Gmail PubSub

​Configuração pelo assistente (recomendado)

​Inicialização automática do Gateway

​Configuração manual única

​Substituição de modelo do Gmail

​Gerenciando tarefas

​Configuração

​Solução de problemas

​Sequência de comandos

​O cron não dispara

​O cron disparou, mas não houve entrega

​Cuidados com fuso horário

​Relacionado

Tarefas agendadas (Cron)

Início rápido

Como o cron funciona

Tipos de agendamento

Dia do mês e dia da semana usam lógica OR

Estilos de execução

Opções de payload para tarefas isoladas

Entrega e saída

Exemplos de CLI

Webhooks

Autenticação

POST /hooks/wake

POST /hooks/agent

Hooks mapeados (POST /hooks/<name>)

Segurança

Integração com Gmail PubSub

Configuração pelo assistente (recomendado)

Inicialização automática do Gateway

Configuração manual única

Substituição de modelo do Gmail

Gerenciando tarefas

Configuração

Solução de problemas

Sequência de comandos

O cron não dispara

O cron disparou, mas não houve entrega

Cuidados com fuso horário

Relacionado