Tareas programadas

Cron es el programador integrado del Gateway. Persiste los trabajos, despierta al agente en el momento adecuado y puede entregar la salida de vuelta a un canal de chat o a un endpoint Webhook.

# Inicio rápido

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

openclaw cron list
openclaw cron show <job-id>

openclaw cron runs --id <job-id>

# Cómo funciona cron

• Cron se ejecuta dentro del proceso del Gateway (no dentro del modelo).
• Las definiciones de trabajos persisten en ~/.openclaw/cron/jobs.json, por lo que los reinicios no pierden las programaciones.
• El estado de ejecución en tiempo de ejecución persiste junto a él en ~/.openclaw/cron/jobs-state.json. Si registras las definiciones de cron en git, registra jobs.json y añade jobs-state.json a gitignore.
• Después de la separación, las versiones anteriores de OpenClaw pueden leer jobs.json, pero pueden tratar los trabajos como nuevos porque los campos de tiempo de ejecución ahora viven en jobs-state.json.
• Cuando se edita jobs.json mientras el Gateway está en ejecución o detenido, OpenClaw compara los campos de programación modificados con los metadatos de ranura de tiempo de ejecución pendientes y borra los valores nextRunAtMs obsoletos. Las reescrituras de solo formato o solo orden de claves conservan la ranura pendiente.
• Todas las ejecuciones de cron crean registros de tareas en segundo plano.
• Al iniciar el Gateway, los trabajos de turno de agente aislado vencidos se reprograman fuera de la ventana de conexión de canales en lugar de reproducirse inmediatamente, por lo que el inicio de Discord/Telegram y la configuración de comandos nativos siguen respondiendo después de los reinicios.
• Los trabajos de una sola ejecución (--at) se eliminan automáticamente después del éxito de forma predeterminada.
• Las ejecuciones aisladas de cron cierran con el mejor esfuerzo las pestañas/procesos de navegador rastreados para su sesión cron:<jobId> cuando la ejecución se completa, de modo que la automatización de navegador desacoplada no deje procesos huérfanos.
• Las ejecuciones aisladas de cron que reciben la concesión limitada de autolimpieza de cron aún pueden leer el estado del programador y una lista autofilltrada de su trabajo actual, por lo que las comprobaciones de estado/Heartbeat pueden inspeccionar su propia programación sin obtener acceso más amplio de mutación de cron.
• Las ejecuciones aisladas de cron también protegen contra respuestas de acuse obsoletas. Si el primer resultado es solo una actualización de estado provisional (on it, pulling everything together y pistas similares) y ninguna ejecución de subagente descendiente sigue siendo responsable de la respuesta final, OpenClaw vuelve a solicitar una vez el resultado real antes de la entrega.
• Las ejecuciones aisladas de cron prefieren metadatos estructurados de denegación de ejecución de la ejecución incrustada y luego recurren a marcadores conocidos de resumen/salida final como SYSTEM_RUN_DENIED e INVALID_REQUEST, de modo que un comando bloqueado no se reporte como una ejecución verde.
• Las ejecuciones aisladas de cron también tratan los fallos de agente a nivel de ejecución como errores de trabajo incluso cuando no se produce ninguna carga útil de respuesta, por lo que los fallos de modelo/proveedor incrementan los contadores de errores y activan notificaciones de fallo en lugar de borrar el trabajo como exitoso.
• Cuando un trabajo de turno de agente aislado alcanza timeoutSeconds, cron aborta la ejecución de agente subyacente y le da una breve ventana de limpieza. Si la ejecución no se drena, la limpieza propiedad del Gateway fuerza la eliminación de la propiedad de sesión de esa ejecución antes de que cron registre el tiempo de espera, de modo que el trabajo de chat en cola no quede detrás de una sesión de procesamiento obsoleta.

# Tipos de programación

Las marcas de tiempo sin zona horaria se tratan como UTC. Añade --tz America/New_York para programación según la hora local de pared.

Las expresiones recurrentes de inicio de hora se escalonan automáticamente hasta 5 minutos para reducir picos de carga. Usa --exact para forzar una temporización precisa o --stagger 30s para una ventana explícita.

# El día del mes y el día de la semana usan lógica OR

Las expresiones de cron las analiza croner. Cuando tanto el campo de día del mes como el de día de la semana no son comodines, croner coincide cuando cualquiera de los campos coincide, no ambos. Este es el comportamiento estándar de Vixie cron.

# Intended: "9 AM on the 15th, only if it's a Monday"
# Actual:   "9 AM on every 15th, AND 9 AM on every Monday"
0 9 15 * 1

Esto se dispara aproximadamente 5-6 veces al mes en lugar de 0-1 veces al mes. OpenClaw usa aquí el comportamiento OR predeterminado de Croner. Para exigir ambas condiciones, usa el modificador de día de la semana + de Croner (0 9 15 * +1) o programa en un campo y protege el otro en el prompt o comando de tu trabajo.

# Estilos de ejecución

# Opciones de carga útil para trabajos aislados

--model usa el modelo permitido seleccionado como modelo principal de ese trabajo. No es lo mismo que una anulación /model de sesión de chat: las cadenas de fallback configuradas siguen aplicándose cuando falla el principal del trabajo. Si el modelo solicitado no está permitido o no puede resolverse, cron hace fallar la ejecución con un error explícito de validación en lugar de recurrir silenciosamente a la selección de modelo del agente/predeterminada del trabajo.

Si entradas antiguas o editadas a mano de jobs.json almacenan payload.model como "default", "null", una cadena en blanco o JSON null, ejecuta openclaw doctor --fix. Doctor elimina esos sentinelas de anulación persistidos no válidos; el tiempo de ejecución no los admite como alias de fallback. Omite el campo de modelo para usar la selección normal de modelo de agente/predeterminada.

Los trabajos de Cron también pueden llevar fallbacks a nivel de carga útil. Cuando está presente, esa lista reemplaza la cadena de fallback configurada para el trabajo. Usa fallbacks: [] en la carga útil/API del trabajo cuando quieras una ejecución estricta de cron que pruebe solo el modelo seleccionado. Si un trabajo tiene --model pero no tiene fallbacks de carga útil ni configurados, OpenClaw pasa una anulación explícita de fallback vacía para que el principal del agente no se añada como objetivo de reintento adicional oculto.

La precedencia de selección de modelo para trabajos aislados es:

1. Anulación de modelo del hook de Gmail (cuando la ejecución vino de Gmail y esa anulación está permitida)
2. model de carga útil por trabajo
3. Anulación de modelo de sesión de cron almacenada seleccionada por el usuario
4. Selección de modelo de agente/predeterminada

El modo rápido también sigue la selección en vivo resuelta. Si la configuración del modelo seleccionado tiene params.fastMode, cron aislado lo usa de forma predeterminada. Una anulación fastMode de sesión almacenada sigue teniendo prioridad sobre la configuración en cualquier dirección.

Si una ejecución aislada encuentra una transferencia de cambio de modelo en vivo, cron reintenta con el proveedor/modelo cambiado y persiste esa selección en vivo para la ejecución activa antes de reintentar. Cuando el cambio también trae un nuevo perfil de autenticación, cron persiste también esa anulación de perfil de autenticación para la ejecución activa. Los reintentos están acotados: después del intento inicial más 2 reintentos de cambio, cron aborta en lugar de entrar en un bucle infinito.

Antes de que una ejecución aislada de cron entre en el ejecutor de agente, OpenClaw comprueba los endpoints de proveedores locales alcanzables para proveedores configurados con api: "ollama" y api: "openai-completions" cuyo baseUrl sea loopback, private-network o .local. Si ese endpoint está caído, la ejecución se registra como skipped con un error claro de proveedor/modelo en lugar de iniciar una llamada al modelo. El resultado del endpoint se almacena en caché durante 5 minutos, de modo que muchos trabajos vencidos que usan el mismo servidor local Ollama, vLLM, SGLang o LM Studio caído comparten una pequeña prueba en lugar de crear una tormenta de solicitudes. Las ejecuciones omitidas por preflight de proveedor no incrementan el backoff de errores de ejecución; habilita failureAlert.includeSkipped cuando quieras notificaciones repetidas de omisión.

# Entrega y salida

Usa --announce --channel telegram --to "-1001234567890" para la entrega a canales. Para temas de foros de Telegram, usa -1001234567890:topic:123; los llamadores directos por RPC/config también pueden pasar delivery.threadId como cadena o número. Los destinos de Slack/Discord/Mattermost deben usar prefijos explícitos (channel:<id>, user:<id>). Los ID de salas de Matrix distinguen mayúsculas y minúsculas; usa el ID de sala exacto o la forma room:!room:server de Matrix.

Cuando la entrega announce usa channel: "last" u omite channel, un destino con prefijo de proveedor como telegram:123 puede seleccionar el canal antes de que cron recurra al historial de sesión o a un único canal configurado. Solo los prefijos anunciados por el Plugin cargado son selectores de proveedor. Si delivery.channel es explícito, el prefijo de destino debe nombrar el mismo proveedor; por ejemplo, channel: "whatsapp" con to: "telegram:123" se rechaza en lugar de permitir que WhatsApp interprete el ID de Telegram como un número de teléfono. Los prefijos de tipo de destino y servicio, como channel:<id>, user:<id>, imessage:<handle> y sms:<number>, siguen siendo sintaxis de destino propiedad del canal, no selectores de proveedor.

Para trabajos aislados, la entrega por chat es compartida. Si hay una ruta de chat disponible, el agente puede usar la herramienta message incluso cuando el trabajo usa --no-deliver. Si el agente envía al destino configurado/actual, OpenClaw omite el announce de reserva. De lo contrario, announce, webhook y none solo controlan lo que el ejecutor hace con la respuesta final después del turno del agente.

Cuando un agente crea un recordatorio aislado desde un chat activo, OpenClaw almacena el destino de entrega en vivo conservado para la ruta de announce de reserva. Las claves internas de sesión pueden estar en minúsculas; los destinos de entrega del proveedor no se reconstruyen a partir de esas claves cuando el contexto de chat actual está disponible.

La entrega announce implícita usa listas de permitidos de canales configuradas para validar y redirigir destinos obsoletos. Las aprobaciones del almacén de emparejamiento de DM no son destinatarios de automatización de reserva; establece delivery.to o configura la entrada allowFrom del canal cuando un trabajo programado deba enviar proactivamente a un DM.

Las notificaciones de fallo siguen una ruta de destino separada:

• cron.failureDestination establece un valor predeterminado global para las notificaciones de fallo.
• job.delivery.failureDestination lo sobrescribe por trabajo.
• Si ninguno está establecido y el trabajo ya entrega mediante announce, las notificaciones de fallo ahora recurren a ese destino announce principal.
• delivery.failureDestination solo se admite en trabajos sessionTarget="isolated" salvo que el modo de entrega principal sea webhook.
• failureAlert.includeSkipped: true hace que un trabajo o una política global de alertas de cron opte por alertas repetidas de ejecuciones omitidas. Las ejecuciones omitidas mantienen un contador independiente de omisiones consecutivas, por lo que no afectan el backoff de errores de ejecución.

# Ejemplos de CLI

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

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"

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

Gateway puede exponer endpoints Webhook HTTP para disparadores externos. Habilítalos en la configuración:

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

# Autenticación

Cada solicitud debe incluir el token de hook mediante un encabezado:

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

Los tokens en la cadena de consulta se rechazan.

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"}'

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"}'

# Integración de Gmail PubSub

Conecta disparadores de la bandeja de entrada de Gmail a OpenClaw mediante Google PubSub.

# Configuración con asistente (recomendado)

openclaw webhooks gmail setup --account [email protected]

Esto escribe la configuración hooks.gmail, habilita el preset de Gmail y usa Tailscale Funnel para el endpoint push.

# Inicio automático de Gateway

Cuando hooks.enabled=true y hooks.gmail.account está establecido, Gateway inicia gog gmail watch serve al arrancar y renueva automáticamente la watch. Establece OPENCLAW_SKIP_GMAIL_WATCHER=1 para excluirte.

# Configuración manual de una sola vez

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

gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:[email protected] \
  --role=roles/pubsub.publisher

gog gmail watch start \
  --account [email protected] \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

# Sobrescritura de modelo de Gmail

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

# Administrar trabajos

# List all jobs
openclaw cron list

# Show one job, including resolved delivery route
openclaw cron show <jobId>

# Edit a job
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"

# Force run a job now
openclaw cron run <jobId>

# Run only if due
openclaw cron run <jobId> --due

# View run history
openclaw cron runs --id <jobId> --limit 50

# Delete a job
openclaw cron remove <jobId>

# Agent selection (multi-agent setups)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent

# Configuración

{
  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 },
  },
}

maxConcurrentRuns limita tanto el despacho programado de cron como la ejecución de turnos de agente aislados. Los turnos de agente de cron aislado usan internamente la vía de ejecución dedicada cron-nested de la cola, por lo que aumentar este valor permite que ejecuciones LLM de cron independientes avancen en paralelo en lugar de iniciar solo sus envoltorios externos de cron. La vía compartida no cron nested no se amplía con esta configuración.

El sidecar de estado en tiempo de ejecución se deriva de cron.store: un almacén .json como ~/clawd/cron/jobs.json usa ~/clawd/cron/jobs-state.json, mientras que una ruta de almacén sin sufijo .json añade -state.json.

Si editas jobs.json a mano, deja jobs-state.json fuera del control de código fuente. OpenClaw usa ese sidecar para espacios pendientes, marcadores activos, metadatos de última ejecución y la identidad de programación que le indica al programador cuándo un trabajo editado externamente necesita un nextRunAtMs nuevo.

Deshabilitar cron: cron.enabled: false u OPENCLAW_SKIP_CRON=1.

# Solución de problemas

# Escalera 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

# Relacionado

• Automatización y tareas — todos los mecanismos de automatización de un vistazo
• Tareas en segundo plano — registro de tareas para ejecuciones de Cron
• Heartbeat — turnos periódicos de la sesión principal
• Zona horaria — configuración de zona horaria