Configura Cron Jobs en OpenClaw: Automatiza tus tareas

Inicio rápido

Cron es el programador integrado en el Gateway. Este se encarga de persistir las tareas, activar el agente en el momento adecuado y puede enviar el resultado de vuelta a un canal de chat o a un endpoint de webhook.

# Add a one-shot reminder
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

# Check your jobs
openclaw cron list

# See run history
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 las tareas se guardan en ~/.openclaw/cron/jobs.json para que los reinicios no provoquen la pérdida de los programas establecidos.

• El estado de ejecución en tiempo real se guarda junto al archivo anterior en ~/.openclaw/cron/jobs-state.json. Si realizas un seguimiento de las definiciones de cron en GitHub, asegúrate de incluir jobs.json y añadir jobs-state.json al gitignore.
• Tras la separación, las versiones antiguas de OpenClaw pueden leer jobs.json, pero podrían tratar las tareas como nuevas, ya que los campos de tiempo de ejecución ahora residen en jobs-state.json.
• Todas las ejecuciones de cron crean registros de tareas en segundo plano.
• Las tareas de una sola ejecución (--at) se eliminan automáticamente después de completarse con éxito de forma predeterminada.
• Las ejecuciones aisladas de cron intentan cerrar las pestañas o procesos del navegador rastreados para su sesión cron:<jobId> cuando la tarea finaliza, evitando así procesos huérfanos tras la automatización del navegador.
• Las ejecuciones aisladas de cron también protegen contra respuestas de confirmación obsoletas. Si el primer resultado es solo una actualización de estado provisional (como “en ello”, “recopilando información” y pistas similares) y no hay ninguna ejecución de subagente descendiente responsable de la respuesta final, OpenClaw vuelve a solicitar el resultado real una vez antes de la entrega.

La conciliación de tareas para cron es propiedad del tiempo de ejecución: una tarea de cron activa permanece viva mientras el tiempo de ejecución de cron siga rastreando ese trabajo como en curso, incluso si todavía existe una fila de sesión secundaria antigua. Una vez que el tiempo de ejecución deja de ser propietario de la tarea y expira la ventana de gracia de 5 minutos, el mantenimiento puede marcar la tarea como lost.

Tipos de programación

Tipo	CLI flag	Descripción
at	--at	Marca de tiempo única (ISO 8601 o relativa como 20m)
every	--every	Intervalo fijo
cron	--cron	Expresión cron de 5 o 6 campos con --tz opcional

Las marcas de tiempo sin zona horaria se tratan como UTC. Añade --tz America/New_York para una programación basada en el horario local.

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

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

Las expresiones cron son analizadas por 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 dos 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 ejecuta aproximadamente 5-6 veces al mes en lugar de 0-1 veces al mes. OpenClaw utiliza el comportamiento OR predeterminado de croner aquí. Para requerir ambas condiciones, usa el modificador de día de la semana + de croner (0 9 15 * +1) o programa en un campo y filtra el otro en el prompt o comando de tu tarea.

Estilos de ejecución

Estilo	Valor de --session	Se ejecuta en	Ideal para
Sesión principal	main	Siguiente turno de heartbeat	Recordatorios, eventos del sistema
Aislado	isolated	cron:<jobId> dedicado	Informes, tareas de fondo
Sesión actual	current	Vinculado al momento de creación	Trabajo recurrente con contexto
Sesión personalizada	session:custom-id	Sesión persistente con nombre	Flujos de trabajo basados en historial

Las tareas de la sesión principal encolan un evento del sistema y, opcionalmente, activan el heartbeat (--wake now o --wake next-heartbeat). Las tareas aisladas ejecutan un turno de agente dedicado con una sesión nueva. Las sesiones personalizadas (session:xxx) mantienen el contexto entre ejecuciones, permitiendo flujos de trabajo como reuniones diarias que se basan en resúmenes previos.

Para tareas aisladas, la limpieza del tiempo de ejecución ahora incluye una limpieza del navegador para esa sesión de cron. Los fallos en la limpieza se ignoran para que el resultado real de cron prevalezca.

Cuando las ejecuciones aisladas de cron orquestan subagentes, la entrega prefiere la salida final del descendiente sobre el texto provisional obsoleto del padre. Si los descendientes siguen ejecutándose, OpenClaw suprime esa actualización parcial del padre en lugar de anunciarla.

Opciones de carga útil para tareas aisladas

• --message: texto del prompt (obligatorio para aislado)
• --model / --thinking: anulaciones de modelo y nivel de razonamiento
• --light-context: omite la inyección del archivo de arranque del espacio de trabajo
• --tools exec,read: restringe las herramientas que la tarea puede usar

--model utiliza el modelo permitido seleccionado para esa tarea. Si el modelo solicitado no está permitido, cron registra una advertencia y recurre a la selección de modelo predeterminada del agente. Las cadenas de respaldo configuradas siguen aplicándose, pero una anulación de modelo simple sin una lista de respaldo explícita por tarea ya no añade el agente principal como un objetivo de reintento adicional oculto.

La precedencia en la selección de modelo para tareas aisladas es:

1. Anulación de modelo del webhook de Gmail (cuando la ejecución proviene de Gmail y esa anulación está permitida)
2. model de la carga útil por tarea
3. Anulación de modelo de la sesión cron almacenada
4. Selección de modelo predeterminada del agente

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

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

Entrega y salida

Modo	Qué sucede
announce	Envía un resumen al canal de destino (predeterminado para isolated)
webhook	Realiza un POST del payload del evento finalizado a una URL
none	Solo interno, sin entrega

Usa --announce --channel telegram --to "-1001234567890" para la entrega en canales. Para temas de foros en Telegram, usa -1001234567890:topic:123. Los destinos de Slack/Discord/Mattermost deben usar prefijos explícitos (channel:<id>, user:<id>).

Para trabajos aislados gestionados por cron, el runner controla la ruta de entrega final. Se le solicita al agente que devuelva un resumen en texto plano, y ese resumen se envía a través de announce, webhook o se mantiene interno con none. El comando --no-deliver no devuelve la entrega al agente; mantiene la ejecución de forma interna.

Si la tarea original indica explícitamente enviar un mensaje a un destinatario externo, el agente debe anotar a quién o a dónde debe ir ese mensaje en su salida en lugar de intentar enviarlo directamente.

Las notificaciones de fallo siguen una ruta de destino separada:

1. cron.failureDestination establece un valor predeterminado global para las notificaciones de fallo.
2. job.delivery.failureDestination sobrescribe ese valor por cada trabajo.
3. Si no se establece ninguno y el trabajo ya se entrega mediante announce, las notificaciones de fallo ahora recurren a ese objetivo de anuncio principal.
4. delivery.failureDestination solo es compatible con trabajos de sessionTarget="isolated" a menos que el modo de entrega principal sea webhook.

Ejemplos de CLI

Aquí tienes algunos ejemplos prácticos para configurar tus tareas con OpenClaw y gestionar la entrega de resultados mediante la CLI.

Recordatorio de una sola ejecución (sesión principal):

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

Trabajo aislado recurrente con 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"

Trabajo aislado con anulación de modelo y razonamiento:

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

AI Setup Assistant

Webhooks

El Gateway puede exponer endpoints de webhook HTTP para activar eventos externos. Debes habilitarlos en tu configuración de la siguiente manera:

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

Autenticación

Cada solicitud debe incluir el token del webhook a través de una cabecera:

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

Los tokens enviados mediante query-string serán rechazados.

POST /hooks/wake

Encola un evento del sistema para la sesión 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"}'

1. text (obligatorio): descripción del evento.
2. mode (opcional): now (predeterminado) o next-heartbeat.

POST /hooks/agent

Ejecuta un turno de agente de forma aislada:

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 (obligatorio), name, agentId, wakeMode, deliver, channel, to, model, thinking, timeoutSeconds.

Webhooks mapeados (POST /hooks/<name>)

Los nombres personalizados de los webhook se resuelven mediante hooks.mappings en la configuración. Estos mapeos pueden transformar payloads arbitrarios en acciones de tipo wake o agent utilizando plantillas o transformaciones de código.

Seguridad

1. Mantén los endpoints de webhook detrás de un loopback, una red tailnet o un proxy inverso de confianza.
2. Usa un token de webhook dedicado; no reutilices los tokens de autenticación del Gateway.
3. Mantén hooks.path en una subruta dedicada; la ruta / será rechazada.
4. Configura hooks.allowedAgentIds para limitar el enrutamiento explícito de agentId.
5. Mantén hooks.allowRequestSessionKey=false a menos que necesites que el emisor seleccione las sesiones.
6. Si habilitas hooks.allowRequestSessionKey, configura también hooks.allowedSessionKeyPrefixes para restringir las formas permitidas de las claves de sesión.
7. Los payloads de los webhook están protegidos por límites de seguridad de forma predeterminada.

Integración con Gmail PubSub

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

Requisitos previos: CLI gcloud, gog (gogcli), webhook de OpenClaw habilitados y Tailscale para el endpoint HTTPS público.

Configuración mediante asistente (recomendado)

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

Este comando escribe la configuración hooks.gmail, habilita el ajuste preestablecido de Gmail y utiliza Tailscale Funnel para el endpoint de push.

Inicio automático del Gateway

Cuando hooks.enabled=true y hooks.gmail.account están configurados, el Gateway inicia gog gmail watch serve al arrancar y renueva automáticamente la vigilancia. Configura OPENCLAW_SKIP_GMAIL_WATCHER=1 si prefieres omitir este paso.

Configuración manual única

1. Selecciona el proyecto de GCP que posee el cliente OAuth utilizado por gog:

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

2. Crea el tema y otorga acceso de push a 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

3. Inicia la vigilancia:

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

Sustitución del modelo de Gmail

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

Gestión de tareas

Para mantener tus procesos automatizados bajo control, OpenClaw te permite gestionar tus tareas programadas de forma sencilla mediante la CLI. Aquí tienes los comandos esenciales para listar, modificar o ejecutar tus tareas cuando lo necesites.

# List all jobs
openclaw cron list

# 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

Ten en cuenta cómo funciona la sustitución de modelos:

1. El comando openclaw cron add|edit --model ... modifica el modelo seleccionado para esa tarea específica.
2. Si el modelo está permitido, ese proveedor y modelo exactos se utilizarán durante la ejecución del agente aislado.
3. Si no está permitido, la CLI te enviará una advertencia y volverá a la selección de modelo predeterminada del agente o de la tarea.
4. Las cadenas de respaldo configuradas siguen siendo válidas, pero una sustitución simple con --model sin una lista de respaldo explícita por tarea ya no intentará usar el modelo principal del agente como un reintento silencioso adicional.

Configuración de cron

Puedes ajustar el comportamiento de tus tareas automatizadas editando el archivo de configuración en formato JSON. Asegúrate de definir correctamente las rutas de almacenamiento y los parámetros de reintento para que tu OpenClaw cron funcione de manera óptima.

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

El archivo de estado en tiempo de ejecución se deriva de cron.store: un almacén .json como ~/clawd/cron/jobs.json utilizará ~/clawd/cron/jobs-state.json, mientras que si la ruta no tiene el sufijo .json, se añadirá -state.json automáticamente.

Para desactivar el cron, usa cron.enabled: false o la variable de entorno OPENCLAW_SKIP_CRON=1.

Reintento único: los errores transitorios (límite de tasa, sobrecarga, red, error del servidor) se reintentan hasta 3 veces con un retroceso exponencial. Los errores permanentes desactivan la tarea de inmediato.

Reintento recurrente: utiliza un retroceso exponencial (de 30s a 60m) entre reintentos. El retroceso se reinicia después de la siguiente ejecución exitosa.

Mantenimiento: cron.sessionRetention (por defecto 24h) elimina las entradas de sesiones de ejecución aisladas. Los parámetros cron.runLog.maxBytes y cron.runLog.keepLines realizan la limpieza automática de los archivos de registro de ejecución.

Solución de problemas

A veces las cosas no salen como esperas cuando trabajas con sistemas distribuidos. Aquí tienes una serie de comandos y comprobaciones para diagnosticar qué ocurre con tu OpenClaw y sus procesos.

Comandos de diagnóstico

Puedes usar estos comandos en tu CLI para verificar el estado de los servicios y obtener información detallada sobre la ejecución de tus tareas.

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

Problemas con la ejecución de cron

Si notas que tus tareas programadas no se disparan, revisa estos puntos clave para asegurar que el motor de cron esté configurado correctamente.

1. Verifica las variables de entorno cron.enabled y OPENCLAW_SKIP_CRON.
2. Confirma que el Gateway se esté ejecutando de forma continua.
3. Para los horarios de cron, verifica la diferencia entre la zona horaria configurada (--tz) y la zona horaria del host.
4. Si en la salida de la ejecución aparece reason: not-due, significa que se realizó una comprobación manual con openclaw cron run <jobId> --due y la tarea aún no debía ejecutarse.

Tarea ejecutada pero sin entrega

Cuando una tarea se ejecuta pero no recibes el resultado, el problema suele estar relacionado con la configuración de entrega o los permisos del webhook.

1. Si el modo de entrega es none, significa que no se espera ningún mensaje externo.
2. Si el destino de entrega (channel/to) falta o es inválido, la salida fue omitida.
3. Los errores de autenticación del canal (unauthorized, Forbidden) indican que la entrega fue bloqueada por credenciales incorrectas.
4. Si la ejecución aislada devuelve solo el token silencioso (NO_REPLY / no_reply), OpenClaw suprime la entrega directa y también la ruta de resumen en cola, por lo que no se envía nada al chat.
5. Para tareas aisladas propiedad de cron, no esperes que el agente utilice la herramienta de mensajes como alternativa. El ejecutor controla la entrega final; --no-deliver mantiene el resultado interno en lugar de permitir un envío directo.

Detalles sobre zonas horarias

El manejo del tiempo es crítico para la sincronización de tus procesos en Node.js.

1. El cron sin --tz utiliza la zona horaria del host del Gateway.
2. Los horarios at sin zona horaria se tratan como UTC.
3. El activeHours del heartbeat utiliza la resolución de zona horaria configurada.

Documentación relacionada

• Automation & Tasks — todos los mecanismos de automatización de un vistazo
• Background Tasks — registro de tareas para ejecuciones de cron
• Heartbeat — turnos periódicos de la sesión principal
• Timezone — configuración de zona horaria

AI Setup Assistant