Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw cron
Gerencie tarefas cron para o agendador do Gateway.
Sessões
--session aceita main, isolated, current ou session:<id>.
Session keys
Session keys
mainvincula à sessão principal do agente.isolatedcria uma transcrição nova e um ID de sessão para cada execução.currentvincula à sessão ativa no momento da criação.session:<id>fixa uma chave de sessão persistente explícita.
Isolated session semantics
Isolated session semantics
Execuções isoladas redefinem o contexto de conversa ambiente. O roteamento de canal e grupo, a política de envio/fila, a elevação, a origem e a vinculação de runtime ACP são redefinidos para a nova execução. Preferências seguras e substituições explícitas de modelo ou autenticação selecionadas pelo usuário podem ser mantidas entre execuções.
Entrega
openclaw cron list e openclaw cron show <job-id> pré-visualizam a rota de entrega resolvida. Para channel: "last", a prévia mostra se a rota foi resolvida a partir da sessão principal ou atual, ou se falhará fechada.
Destinos com prefixo de provedor podem desambiguar canais de anúncio não resolvidos. Por exemplo, to: "telegram:123" seleciona Telegram quando delivery.channel é omitido ou é last. Apenas prefixos anunciados pelo plugin carregado são seletores de provedor. Se delivery.channel for explícito, o prefixo deve corresponder a esse canal; channel: "whatsapp" com to: "telegram:123" é rejeitado. Prefixos de serviço como imessage: e sms: permanecem sintaxe de destino de propriedade do canal.
Tarefas
cron add isoladas usam entrega --announce por padrão. Use --no-deliver para manter a saída interna. --deliver permanece como um alias obsoleto para --announce.Propriedade da entrega
A entrega de chat de cron isolado é compartilhada entre o agente e o executor:- O agente pode enviar diretamente usando a ferramenta
messagequando uma rota de chat está disponível. announceentrega a resposta final por fallback apenas quando o agente não enviou diretamente para o destino resolvido.webhookpublica o payload concluído em uma URL.nonedesativa a entrega de fallback do executor.
--announce é a entrega de fallback do executor para a resposta final. --no-deliver desativa esse fallback, mas não remove a ferramenta message do agente quando uma rota de chat está disponível.
Lembretes criados a partir de um chat ativo preservam o destino de entrega do chat ao vivo para entrega de anúncio por fallback. Chaves de sessão internas podem estar em minúsculas; não as use como fonte da verdade para IDs de provedor sensíveis a maiúsculas e minúsculas, como IDs de sala do Matrix.
Entrega de falhas
Notificações de falha são resolvidas nesta ordem:delivery.failureDestinationna tarefa.cron.failureDestinationglobal.- O destino principal de anúncio da tarefa (quando nenhum destino de falha explícito está definido).
Tarefas de sessão principal só podem usar
delivery.failureDestination quando o modo de entrega principal é webhook. Tarefas isoladas o aceitam em todos os modos.openclaw cron show
e openclaw cron runs incluem um erro específico da fase, como
setup timed out before runner start ou
stalled before first model call (last phase: context-engine).
Para provedores baseados em CLI, o watchdog pré-modelo permanece ativo até o turno da CLI externa começar,
portanto travamentos de busca de sessão, hook, autenticação, prompt e configuração da CLI
são relatados como falhas cron pré-modelo.
Agendamento
Tarefas de execução única
--at <datetime> agenda uma execução única. Datas e horas sem offset são tratadas como UTC, a menos que você também passe --tz <iana>, que interpreta o horário de relógio na timezone informada.
Tarefas de execução única são excluídas após sucesso por padrão. Use
--keep-after-run para preservá-las.Tarefas recorrentes
Tarefas recorrentes usam backoff exponencial de repetição após erros consecutivos: 30s, 1m, 5m, 15m, 60m. O agendamento volta ao normal após a próxima execução bem-sucedida. Execuções ignoradas são rastreadas separadamente de erros de execução. Elas não afetam o backoff de repetição, masopenclaw cron edit <job-id> --failure-alert-include-skipped pode incluir alertas de falha em notificações repetidas de execuções ignoradas.
Para tarefas isoladas que têm como destino um provedor de modelo local configurado, o cron executa um preflight leve do provedor antes de iniciar o turno do agente. Provedores api: "ollama" de loopback, rede privada e .local são sondados em /api/tags; provedores locais compatíveis com OpenAI, como vLLM, SGLang e LM Studio, são sondados em /models. Se o endpoint estiver inacessível, a execução é registrada como skipped e repetida em um agendamento posterior; endpoints inativos correspondentes são armazenados em cache por 5 minutos para evitar que muitas tarefas sobrecarreguem o mesmo servidor local.
Observação: definições de tarefas cron ficam em jobs.json, enquanto o estado pendente de runtime fica em jobs-state.json. Se jobs.json for editado externamente, o Gateway recarrega agendamentos alterados e limpa slots pendentes obsoletos; reescritas apenas de formatação não limpam o slot pendente.
Execuções manuais
openclaw cron run retorna assim que a execução manual é enfileirada. Respostas bem-sucedidas incluem { ok: true, enqueued: true, runId }. Use openclaw cron runs --id <job-id> para acompanhar o resultado eventual.
openclaw cron run <job-id> força a execução por padrão. Use --due para manter o comportamento antigo de “executar somente se estiver no prazo”.Modelos
cron add|edit --model <ref> seleciona um modelo permitido para a tarefa.
Cron --model é um primário da tarefa, não uma substituição /model de sessão de chat. Isso significa:
- Fallbacks de modelo configurados ainda se aplicam quando o modelo selecionado da tarefa falha.
fallbackspor payload de tarefa substitui a lista de fallbacks configurada quando presente.- Uma lista vazia de fallback por tarefa (
fallbacks: []no payload/API da tarefa) torna a execução cron estrita. - Quando uma tarefa tem
--model, mas nenhuma lista de fallback está configurada, o OpenClaw passa uma substituição explícita de fallback vazia para que o primário do agente não seja anexado como um destino oculto de repetição.
Precedência de modelo em cron isolado
Cron isolado resolve o modelo ativo nesta ordem:- Substituição de hook do Gmail.
--modelpor tarefa.- Substituição de modelo da sessão cron armazenada (quando o usuário selecionou uma).
- Seleção de modelo do agente ou padrão.
Modo rápido
O modo rápido do cron isolado segue a seleção de modelo ao vivo resolvida. A configuração de modeloparams.fastMode se aplica por padrão, mas uma substituição fastMode da sessão armazenada ainda prevalece sobre a configuração.
Repetições de troca de modelo ao vivo
Se uma execução isolada lançarLiveSessionModelSwitchError, o cron persiste o provedor e o modelo trocados (e a substituição de perfil de autenticação trocada quando presente) para a execução ativa antes de repetir. O loop externo de repetição é limitado a duas repetições de troca após a tentativa inicial e então aborta em vez de ficar em loop para sempre.
Saída de execução e recusas
Supressão de confirmação obsoleta
Turnos cron isolados suprimem respostas obsoletas apenas de confirmação. Se o primeiro resultado for apenas uma atualização de status intermediária e nenhuma execução de subagente descendente for responsável pela resposta eventual, o cron solicita novamente uma vez pelo resultado real antes da entrega.Supressão de token silencioso
Se uma execução cron isolada retornar apenas o token silencioso (NO_REPLY ou no_reply), o cron suprime tanto a entrega direta de saída quanto o caminho de resumo enfileirado por fallback, então nada é publicado de volta ao chat.
Recusas estruturadas
Execuções cron isoladas preferem metadados estruturados de recusa de execução da execução incorporada e depois recorrem a marcadores de recusa conhecidos na saída final, comoSYSTEM_RUN_DENIED, INVALID_REQUEST e frases de recusa de vinculação de aprovação.
cron list e o histórico de execuções exibem o motivo da recusa em vez de relatar um comando bloqueado como ok.
Retenção
Retenção e poda são controladas na configuração:cron.sessionRetention(padrão24h) poda sessões concluídas de execuções isoladas.cron.runLog.maxBytesecron.runLog.keepLinespodam~/.openclaw/cron/runs/<jobId>.jsonl.
Migração de tarefas antigas
Se você tiver tarefas cron de antes do formato atual de entrega e armazenamento, execute
openclaw doctor --fix. Doctor normaliza campos cron legados (jobId, schedule.cron, campos de entrega de nível superior incluindo threadId legado, aliases de entrega provider de payload) e migra tarefas simples de fallback de webhook notify: true para entrega webhook explícita quando cron.webhook está configurado.Edições comuns
Atualize configurações de entrega sem alterar a mensagem:--light-context aplica-se apenas a tarefas de turno de agente isoladas. Para execuções cron, o modo leve mantém o contexto de bootstrap vazio em vez de injetar o conjunto completo de bootstrap do workspace.
Comandos comuns de administração
Execução manual e inspeção:openclaw cron list mostra todas as tarefas correspondentes por padrão. Passe --agent <id> para mostrar apenas tarefas cujo ID de agente normalizado efetivo corresponde; tarefas sem um ID de agente armazenado contam como o agente padrão configurado.
openclaw cron get <job-id> retorna diretamente o JSON armazenado da tarefa. Use cron show <job-id> quando quiser a visualização legível por humanos com prévia da rota de entrega.
cron list --json e cron show <job-id> --json incluem um campo status de nível superior em cada tarefa, calculado a partir de enabled, state.runningAtMs e state.lastRunStatus. Valores: disabled, running, ok, error, skipped ou idle. Isso espelha a coluna de status legível por humanos para que ferramentas externas possam ler o estado da tarefa sem recalculá-lo.
Entradas de cron runs incluem diagnósticos de entrega com o destino cron pretendido, o destino resolvido, envios da ferramenta de mensagem, uso de fallback e estado de entrega.
Redirecionamento de agente e sessão:
openclaw cron add avisa quando --agent é omitido em tarefas de turno de agente e recorre ao agente padrão (main). Passe --agent <id> no momento da criação para fixar um agente específico.
Ajustes de entrega: