Tareas programadas

Cron es el programador integrado del Gateway. Conserva los trabajos, activa al agente en el momento adecuado y puede entregar la salida a un canal de chat, un Webhook o a ningún destino.

Inicio rápido

openclaw cron create "2027-02-01T16:00:00Z" \  --name "Recordatorio" \  --session main \  --system-event "Recordatorio: revisar el borrador de la documentación de cron" \  --wake now \  --delete-after-run

openclaw cron listopenclaw cron get <job-id>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. El Gateway debe estar en ejecución para que se activen las programaciones.
• Las definiciones de trabajos, el estado de ejecución y el historial de ejecuciones se conservan en la base de datos SQLite de estado compartido de OpenClaw, por lo que los reinicios no hacen que se pierdan las programaciones.
• Cada ejecución de cron crea un registro de tarea en segundo plano.
• Los trabajos únicos (--at) se eliminan automáticamente después de completarse correctamente de forma predeterminada; pase --keep-after-run para conservarlos.
• Presupuesto de tiempo real por ejecución: --timeout-seconds cuando se establece. De lo contrario, los trabajos de turno del agente aislados o desacoplados están limitados por el supervisor propio de cron de 60 minutos antes de que pudiera aplicarse el tiempo de espera del turno del agente subyacente (agents.defaults.timeoutSeconds, 48 horas de forma predeterminada); los trabajos de comandos tienen un valor predeterminado de 10 minutos y las cargas útiles de scripts, de 5 minutos.
• Al iniciarse el Gateway, los trabajos de turno del agente aislados y vencidos se reprograman en lugar de reproducirse inmediatamente, lo que mantiene el trabajo de arranque del modelo y las herramientas fuera del intervalo de conexión del canal.
• Si ejecuta openclaw agent desde el cron del sistema u otro programador externo, envuélvalo con un mecanismo de escalamiento que fuerce la terminación, aunque la CLI ya gestione SIGTERM/SIGINT. Las ejecuciones respaldadas por el Gateway solicitan al Gateway que cancele las ejecuciones aceptadas; las ejecuciones --local reciben la misma señal de cancelación. Para timeout de GNU, se recomienda timeout -k 60 600 openclaw agent ... en lugar de timeout 600 ... sin más: el valor -k actúa como último recurso si el proceso no puede finalizar a tiempo. Para unidades systemd, use una señal de detención SIGTERM con un periodo de gracia (TimeoutStopSec) antes de la terminación definitiva. Si se reutiliza un --run-id mientras la ejecución original del Gateway sigue activa, el duplicado se informa como en curso en lugar de iniciar una segunda ejecución.

Tipos de programación

Las marcas de tiempo sin zona horaria se consideran UTC. Añada --tz America/New_York para interpretar una fecha y hora --at sin desplazamiento, o para evaluar una expresión cron, en esa zona horaria de IANA. Las expresiones cron sin --tz usan la zona horaria del host del Gateway. --tz no es válido con --every ni --on-exit.

Las expresiones recurrentes al inicio de la hora (minuto 0 con un campo de hora comodín) se escalonan automáticamente hasta 5 minutos para reducir los picos de carga. Use --exact para forzar una temporización precisa o --stagger 30s para establecer un intervalo explícito (solo programaciones cron).

Migración de tareas de Heartbeat

La zona de trabajo temporal anterior de Heartbeat admitía un bloque estructurado tasks:. Ejecute openclaw doctor --fix después de actualizar para convertir cada entrada en un trabajo cron normal y editable de la sesión principal. Doctor conserva el intervalo y la hora de la ejecución anterior, crea los trabajos antes de eliminar el bloque y, al volver a ejecutarse, hace converger de forma segura las mismas claves de declaración.

Estos trabajos migrados contienen cargas útiles públicas systemEvent, por lo que openclaw cron list, get, edit y remove, junto con la herramienta cron, los gestionan como los demás trabajos. Su ejecución usa la activación protegida de tareas de Heartbeat: siguen aplicándose las horas activas, el espaciado mínimo, el control de saturación y los reintentos por ocupación, mientras que cron controla la cadencia independiente de cada tarea. Los trabajos que vencen en el mismo intervalo de agrupación pueden compartir un turno de Heartbeat. Una ejecución programada fuera de las horas activas de Heartbeat se omite y se vuelve a intentar en la siguiente ejecución del trabajo.

La zona de trabajo temporal de Heartbeat ahora solo contiene texto de supervisión. Los Heartbeat del entorno de ejecución no interpretan el texto tasks: como programaciones; cree el nuevo trabajo recurrente con cron.

Orígenes de flujo

Una programación de flujo mantiene en ejecución un comando argv creado por el operador bajo el Gateway y activa el trabajo a partir de sus líneas de stdout y stderr. Las programaciones de flujo se controlan mediante eventos, nunca vencen por tiempo y requieren cron.triggers.enabled: true, porque el comando de larga duración pertenece a la misma clase de confianza sin supervisión que los scripts desencadenadores. Al deshabilitar o eliminar el trabajo, se detiene el proceso; al apagarse, el Gateway espera a que se desmonte el árbol de procesos. Los fallos rápidos se reinician con el retroceso de errores integrado de cron. Cinco ejecuciones consecutivas de menos de 60 segundos dejan el trabajo en estado de error y utilizan la ruta normal de alertas de fallo; vuelva a habilitar manualmente el trabajo para eliminar el límite de reinicios.

openclaw cron add \  --name "Flujo de eventos de compilación" \  --stream-command '["node","scripts/build-events.mjs"]' \  --stream-mode match \  --stream-match '^(failed|recovered):' \  --stream-batch-ms 250 \  --session isolated \  --message "Investiga estos eventos de compilación."

mode: "line" (el valor predeterminado) acepta todas las líneas. mode: "match" acepta únicamente las líneas que coinciden con la expresión regular match compilada. Un lote se cierra después de batchMs de inactividad (250 ms de forma predeterminada, limitado a 50–5000) o al alcanzar maxBatchBytes (16384 de forma predeterminada, limitado a 1024–65536). Al alcanzar el límite de bytes, el lote termina con [truncated]. El modo de coincidencia siempre evalúa líneas completas respecto a todo su texto, incluso después de maxBatchBytes (solo se trunca el lote entregado); una línea cortada en el límite acotado de entrada sin procesar es únicamente un prefijo, por lo que se considera que no coincide en lugar de permitir que un patrón anclado al final se active sobre el texto cortado. El lote se añade al texto del evento del sistema o al mensaje del turno del agente. Las cargas útiles de comandos se rechazan en las programaciones de flujo porque el comando de origen y el comando de la carga útil tendrían una propiedad de proceso ambigua.

Solo se conserva por trabajo una activación de carga útil y un lote pendiente acotado. Las líneas que llegan mientras se ejecuta una carga útil, o antes de que transcurra el intervalo integrado de 30 segundos entre desencadenadores, se agrupan en ese lote pendiente en lugar de formar una cola sin límites. Un único propietario serializado registra las omisiones de la condición, los errores de la carga útil y los envíos mientras no está en ejecución en streamDroppedBatches; las combinaciones acotadas incrementan streamCoalescedBatches. Las cargas útiles fallidas no se vuelven a intentar porque podrían no ser idempotentes. La identidad lógica del origen permanece estable entre reinicios supervisados del proceso secundario, pero cambia cuando el origen se deshabilita, elimina o sustituye, de modo que los lotes en cola del origen retirado no puedan activarse ni siquiera después de una edición de A a B y de nuevo a A. Cuando finaliza una detención, las llamadas tardías de un proceso secundario anterior quedan inertes. V1 no incluye un origen WebSocket nativo; conéctelo mediante un comando argv como websocat wss://example.invalid/events.

Cuando un trabajo de flujo también tiene trigger.script, la condición se ejecuta una vez por cada lote cerrado. El lote actual está disponible como la cadena profundamente inmutable trigger.streamBatch junto con trigger.state. fire: false descarta ese lote después de conservar el estado de la condición. fire: true mantiene la semántica existente del mensaje desencadenador y, a continuación, añade el lote a la carga útil resultante. Un trabajo de flujo puede usar en su lugar una carga útil de script sin una condición; ese script recibe el lote mediante el mismo valor trigger.streamBatch. Se rechaza la combinación de una carga útil de script con una condición porque ambas serían propietarias de la ranura persistente trigger.state.

Cadencia dinámica (ritmo)

Los trabajos recurrentes pueden establecer pacing.min o pacing.max, o ambos, en cadenas de duración como 15m o 4h; se requiere al menos un límite. Use --pacing-min y --pacing-max con cron add|edit (--clear-pacing elimina ambos límites).

Durante una ejecución aislada, un trabajo con ritmo controlado puede llamar a la herramienta cron con action: "next_check" y in: "30m". La propuesta se aplica únicamente al trabajo que se está ejecutando en ese momento y se mide desde la finalización correcta de la ejecución. OpenClaw la ajusta silenciosamente a los límites configurados.

El ritmo controlado sin una propuesta deja sin cambios la programación normal. Las ejecuciones fallidas, agotadas por tiempo o omitidas descartan la propuesta, por lo que tienen prioridad el comportamiento existente de reintentos y la espera incremental por errores. Forzar manualmente un trabajo recurrente queda fuera de la secuencia y conserva su franja natural o con ritmo controlado pendiente. En los trabajos activados por condiciones, el intervalo mínimo integrado sigue siendo un límite inferior, incluso cuando una propuesta solicita una comprobación anterior.

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

Las expresiones Cron se analizan mediante croner. Cuando tanto el campo de día del mes como el de día de la semana no son comodines, croner encuentra una coincidencia cuando coincide cualquiera de los campos, no ambos. Este es el comportamiento estándar de cron de Vixie.

# Previsto: "A las 9 a. m. del día 15, solo si es lunes"# Real:     "A las 9 a. m. de cada día 15 Y a las 9 a. m. de cada lunes"0 9 15 * 1

Esto se activa aproximadamente entre 5 y 6 veces al mes en lugar de entre 0 y 1 veces al mes. Para exigir ambas condiciones, use el modificador de día de la semana + de croner (0 9 15 * +1), o programe según un campo y compruebe el otro en el prompt o comando del trabajo.

Activadores de eventos (supervisores de condiciones)

Un activador de eventos añade un script de condición sin interfaz a una programación every, cron o stream. Las programaciones temporales lo evalúan cuando corresponde; las programaciones de flujo lo evalúan para cada lote cerrado. Cron ejecuta la carga útil normal únicamente cuando el script devuelve fire: true:

{  schedule: { kind: "every", everyMs: 30000 },  trigger: {    // Se activa únicamente cuando el estado observado difiere del de la última evaluación.    script: "const res = await tools.call('exec', { command: 'gh pr checks 123 --json state -q \\'.[].state\\' | sort -u' }); const status = String(res?.result?.details?.aggregated ?? '').trim(); json({ fire: status !== trigger.state?.status, message: `CI del PR 123: ${trigger.state?.status ?? 'desconocido'} -> ${status}`, state: { status } });",    once: false,  },  payload: { kind: "agentTurn", message: "Investiga el cambio de estado de la CI." },}

El script debe devolver { fire, message?, state? }. El estado JSON anterior está disponible como trigger.state, profundamente congelado; las compuertas de flujo también reciben el lote actual como trigger.streamBatch. Devuelva un nuevo valor state para conservarlo. El estado está limitado a 16 KB. Cuando un resultado de activación incluye message, Cron lo añade al texto del evento del sistema o al mensaje del turno del agente antes de la ejecución. once: true desactiva el trabajo después de su primera carga útil activada correctamente.

fire: false conserva el estado y los contadores de la evaluación y, a continuación, vuelve a programar sin crear un historial de ejecuciones. Si falla una ejecución de carga útil activada, el valor state devuelto no se conserva: la siguiente evaluación ve el estado anterior y puede volver a activarse, por lo que los scripts deben ser comprobaciones de solo lectura y las acciones deben permanecer en la carga útil. Las programaciones de activadores tienen un intervalo mínimo integrado de 30 segundos. Cada evaluación dispone de un límite de tiempo de reloj de 30 segundos y hasta 5 llamadas a herramientas.

Diseñe los supervisores en torno a un estado que permita actuar, no solo al éxito: un supervisor que deja de emitir resultados cuando su comprobación falla o agota el tiempo parece estar en buen estado aunque esté averiado. Compare la observación con trigger.state y devuelva un estado nuevo para eliminar duplicados; no dependa de la memoria del modelo ni del proceso. Al activarse, haga que message sea autosuficiente, ya que se convierte en el contexto completo del evento de la ejecución activada.

Cree un supervisor a partir de un archivo de script local (- lee el script desde la entrada estándar):

openclaw cron add \  --name "Supervisor de CI del PR" \  --every 30s \  --trigger-script ./watch-pr-ci.js \  --message "Responde al cambio de estado de la CI" \  --session isolated

Cargas útiles

Cada trabajo contiene exactamente un tipo de carga útil, elegido mediante una opción:

Un tipo adicional de carga útil, heartbeat, es propiedad del sistema: el Gateway converge una tarea de supervisión de Heartbeat por cada agente con Heartbeat habilitado (consulte Heartbeat). Aparece en cron list --all, pero no se puede crear ni editar mediante la CLI ni la API. La configuración de Heartbeat se escribe en la programación persistente del supervisor al iniciar, al recargar la configuración o mediante openclaw doctor --fix. Cuando Cron está deshabilitado, el supervisor no se activa y no se ejecuta ningún temporizador alternativo de Heartbeat.

Opciones de turno del agente

Las tareas nuevas que pueden ejecutar herramientas siempre almacenan una política de herramientas explícita. Las tareas creadas por un agente se limitan a las herramientas disponibles para el turno que las crea, y el agente no puede ampliar la lista almacenada. Las tareas creadas por un operador autenticado sin --tools almacenan una política * sin restricciones; cron edit --clear-tools restaura esa política explícita sin restricciones. Las tareas existentes anteriores a una política de herramientas explícita conservan su comportamiento actual hasta que su política de herramientas se edite explícitamente o se vuelva a crear la tarea.

--model establece el modelo principal de la tarea; no reemplaza una sustitución de sesión /model, por lo que las cadenas configuradas de modelos alternativos siguen aplicándose sobre este. Un modelo no resuelto o no permitido hace que la ejecución falle con un error de validación explícito en lugar de recurrir silenciosamente al predeterminado. Si una tarea tiene --model, pero ninguna lista explícita o configurada de modelos alternativos, OpenClaw pasa una sustitución vacía de modelos alternativos en lugar de añadir silenciosamente el modelo principal del agente como destino oculto de reintento.

Precedencia de selección de modelos para tareas aisladas, de mayor a menor:

1. Carga útil por tarea model (configuración explícita; un modelo no permitido hace que la ejecución falle)
2. Sustitución del modelo del hook de Gmail (solo cuando la ejecución procede de Gmail y esa sustitución está permitida)
3. Sustitución del modelo almacenada para la sesión de Cron seleccionada por el usuario
4. Selección del modelo del agente/predeterminado

El modo rápido sigue la selección activa resuelta. Si la configuración del modelo seleccionado tiene params.fastMode, Cron aislado lo usa de forma predeterminada; una sustitución de sesión almacenada fastMode (y después una fastModeDefault del agente) sigue teniendo prioridad sobre la configuración del modelo en cualquier dirección. El modo automático usa el límite params.fastAutoOnSeconds del modelo, con un valor predeterminado de 60 segundos.

Si una ejecución alcanza una transferencia activa por cambio de modelo, Cron vuelve a intentarlo con el proveedor/modelo al que se cambió y conserva esa selección (y cualquier perfil de autenticación nuevo) para la ejecución activa. Los reintentos están limitados: después del intento inicial y 2 reintentos por cambio, Cron se interrumpe en lugar de entrar en un bucle.

Antes de iniciar una ejecución aislada, OpenClaw comprueba los endpoints locales accesibles de los proveedores api: "ollama" y api: "openai-completions" configurados cuyo baseUrl sea de bucle invertido, de red privada o .local. Esta comprobación preliminar recorre la cadena configurada de modelos alternativos de la tarea y solo marca la ejecución como skipped cuando todos los candidatos son inaccesibles; --fallbacks "" limita estrictamente ese recorrido al modelo principal. Un endpoint inactivo registra la ejecución como skipped con un error claro en lugar de iniciar una llamada al modelo. El resultado se almacena en caché durante 5 minutos por endpoint (no por tarea ni modelo), por lo que muchas tareas programadas que comparten un servidor local Ollama/vLLM/SGLang/LM Studio inactivo generan una sola comprobación en lugar de una avalancha de solicitudes. Las ejecuciones omitidas en la comprobación preliminar no incrementan el retardo por errores de ejecución; establezca failureAlert.includeSkipped para habilitar alertas repetidas de omisión.

Cargas útiles de comandos

Las cargas útiles de comandos ejecutan scripts deterministas dentro del planificador del Gateway sin iniciar un turno respaldado por un modelo. Se ejecutan en el host del Gateway, capturan stdout/stderr, registran la ejecución en el historial de Cron y reutilizan los mismos modos de entrega announce, webhook y none que las tareas de turno del agente.

openclaw cron create "*/15 * * * *" \  --name "Sondeo de profundidad de la cola" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

--command <shell> almacena argv: ["sh", "-lc", <shell>]. Use --command-argv '["node","scripts/report.mjs"]' para ejecutar argv de forma exacta sin análisis del shell. Los parámetros opcionales --command-env KEY=VALUE (repetible), --command-input, --timeout-seconds (valor predeterminado de 10 minutos), --no-output-timeout-seconds y --output-max-bytes controlan el entorno del proceso, stdin y los límites de salida.

El texto entregado se deriva de la salida del proceso: stdout no vacío tiene prioridad; si stdout está vacío y stderr no lo está, se entrega stderr; si ambos están presentes, Cron envía un pequeño bloque stdout: / stderr:. El código de salida 0 registra la ejecución como ok; una salida distinta de cero, una señal, un tiempo de espera agotado o un tiempo de espera agotado sin salida registra error y puede activar alertas de fallo. Un comando que solo imprime NO_REPLY usa la supresión normal de tokens silenciosos de Cron y no publica nada en el chat.

Cargas útiles de scripts

Las cargas útiles de script se ejecutan sin interfaz en el mismo ejecutor de modo de código que los scripts de activación, sin iniciar un turno de agente conversacional. Habilite cron.triggers.enabled antes de crearlas o ejecutarlas; esta barrera para automatizaciones peligrosas abarca tanto los scripts de activación como las cargas útiles de script. Los trabajos de script solo admiten los destinos de sesión main y isolated.

openclaw cron create "0 * * * *" \  --name "Hourly queue check" \  --script ./automation/check-queue.js \  --script-timeout-seconds 300 \  --script-tool-budget 50 \  --session isolated \  --announce

Use --script <file|-> para leer JavaScript desde un archivo o desde la entrada estándar. El tiempo de espera predeterminado es de 300 segundos, con un máximo de 900; el presupuesto de herramientas predeterminado es de 50 llamadas, con un máximo de 200. Estos presupuestos de carga útil son independientes de los presupuestos de evaluación más pequeños de la barrera de activación.

El script puede devolver un objeto con estos campos opcionales:

• notify: Texto entregado mediante el modo de entrega announce, webhook o none del trabajo. Si se omite, no se entrega nada. Para un trabajo main, el texto se convierte en un evento del sistema.
• wake: "now" solicita un heartbeat inmediato después de poner en cola notify (o un evento de finalización compacto); "next-heartbeat" pone el evento en cola para el siguiente heartbeat.
• state: Estado JSON, limitado a 16 KB y persistido únicamente después de una ejecución correcta. La siguiente ejecución recibe una copia inmutable como trigger.state, igual que los scripts de activación. Como ese espacio de nombres tiene un único propietario persistente, una carga útil de script no puede combinarse con un activador condicional en el mismo trabajo.
• nextCheck: Una duración, como "15m". Solo es válida para trabajos con control de ritmo habilitado y utiliza el mismo límite de ritmo que las propuestas de turnos de agente.

Las excepciones, los tiempos de espera agotados, los presupuestos de herramientas agotados, los resultados no válidos y nextCheck sin control de ritmo son errores normales de ejecución de cron: se incorporan al historial de ejecuciones, al aplazamiento progresivo y a la gestión de alertas de fallo sin persistir el estado devuelto.

Estilos de ejecución

Entrega y salida

Use --announce --channel telegram --to "-1001234567890" para la entrega por canal. Para los temas de foros de Telegram, use -1001234567890:topic:123; OpenClaw también acepta la forma abreviada -1001234567890:123, propiedad de Telegram. Los invocadores directos de RPC/configuración pueden proporcionar delivery.threadId como cadena o número. Los destinos de Slack/Discord/Mattermost utilizan prefijos explícitos (channel:<id>, user:<id>). Los identificadores de sala de Matrix distinguen entre mayúsculas y minúsculas; use el identificador de sala exacto o la forma room:!room:server de Matrix.

Cuando la entrega de anuncios utiliza 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 la sesión o a un único canal configurado. Solo los prefijos anunciados por el Plugin cargado actúan como selectores de proveedor. Si delivery.channel es explícito, el prefijo del destino debe indicar el mismo proveedor; channel: "whatsapp" con to: "telegram:123" se rechaza en lugar de permitir que WhatsApp interprete el identificador de Telegram como un número de teléfono. Los prefijos de tipo de destino y servicio (channel:<id>, user:<id>, imessage:<handle>, sms:<number>) siguen siendo sintaxis de destino propiedad del canal, no selectores de proveedor.

En los trabajos aislados, la entrega por chat es compartida: si hay disponible una ruta de chat, el agente puede utilizar la herramienta message incluso con --no-deliver. Si el agente envía al destino configurado/actual, OpenClaw omite el anuncio alternativo. De lo contrario, announce, webhook y none solo controlan lo que hace el ejecutor 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 activo conservado para la ruta de anuncio alternativa. 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 está disponible el contexto de chat actual.

La entrega implícita de anuncios utiliza listas de canales permitidos configuradas para validar y redirigir destinos obsoletos. Las aprobaciones del almacén de vinculaciones de mensajes directos no son destinatarios de automatización alternativos; establezca delivery.to o configure la entrada allowFrom del canal cuando un trabajo programado deba enviar mensajes de forma proactiva a un mensaje directo.

Notificaciones de fallo

Las notificaciones de fallo siguen una ruta de destino independiente:

• cron.failureDestination establece un valor global predeterminado para las notificaciones de fallo.
• job.delivery.failureDestination lo anula para cada trabajo.
• Si ninguno está establecido y el trabajo ya realiza entregas mediante announce, las notificaciones de fallo recurren a ese destino principal de anuncios.
• delivery.failureDestination solo es compatible con trabajos sessionTarget="isolated", salvo que el modo de entrega principal sea webhook.
• failureAlert.includeSkipped: true permite que un trabajo o una política global de alertas de cron reciba alertas repetidas de ejecuciones omitidas. Las ejecuciones omitidas mantienen un contador consecutivo independiente, por lo que no afectan al aplazamiento progresivo por errores de ejecución.
• openclaw cron edit expone el ajuste de alertas por trabajo: --failure-alert/--no-failure-alert, --failure-alert-after <n>, --failure-alert-channel, --failure-alert-to, --failure-alert-cooldown, --failure-alert-include-skipped/--failure-alert-exclude-skipped, --failure-alert-mode y --failure-alert-account-id.

Idioma de salida

Los trabajos de cron no deducen el idioma de respuesta a partir del canal, la configuración regional ni los mensajes anteriores. Incluya la regla de idioma en el mensaje o la plantilla programados:

openclaw cron edit <jobId> \  --message "Resuma las actualizaciones. Responda en chino; mantenga sin cambios las URL, el código y los nombres de productos."

En los archivos de plantilla, mantenga la instrucción de idioma en el prompt renderizado y compruebe que los marcadores de posición como {{language}} estén rellenados antes de ejecutar el trabajo. Si la salida mezcla idiomas, haga explícita la regla, por ejemplo: «Use chino para el texto narrativo y mantenga los términos técnicos en inglés».

Ejemplos de CLI

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

openclaw cron create "0 7 * * *" \  "Summarize overnight updates." \  --name "Morning brief" \  --tz "America/Los_Angeles" \  --session isolated \  --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

openclaw cron create "0 18 * * 1-5" \  "Summarize today's deploys as JSON." \  --name "Deploy digest" \  --webhook "https://example.invalid/openclaw/cron"

openclaw cron create "*/15 * * * *" \  --name "Queue depth probe" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

Gestión de trabajos

# Enumerar trabajos habilitadosopenclaw cron list # Incluir trabajos deshabilitadosopenclaw cron list --all # Obtener un trabajo almacenado como JSONopenclaw cron get <jobId> # Mostrar un trabajo, incluida la ruta de entrega resueltaopenclaw cron show <jobId> # Habilitar/deshabilitar sin eliminaropenclaw cron enable <jobId>openclaw cron disable <jobId> # Editar un trabajoopenclaw cron edit <jobId> --message "Prompt actualizado" --model "opus" # Forzar la ejecución inmediata de un trabajoopenclaw cron run <jobId> # Forzar la ejecución inmediata de un trabajo y esperar su estado terminalopenclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s # Ejecutar solo si correspondeopenclaw cron run <jobId> --due # Ver el historial de ejecucionesopenclaw cron runs --id <jobId> --limit 50 # Ver una ejecución exactaopenclaw cron runs --id <jobId> --run-id <runId> # Eliminar un trabajoopenclaw cron remove <jobId> # Selección de agente (configuraciones multiagente)openclaw cron create "0 6 * * *" "Revisar la cola de operaciones" --name "Revisión de operaciones" --session isolated --agent opsopenclaw cron edit <jobId> --clear-agent

Archivar una sesión (desde la interfaz de control o mediante sessions.patch { archived: true } desde un llamador administrador-operador) deshabilita todos los trabajos de Cron habilitados vinculados a esa sesión: su sesión aislada cron:<jobId>, un destino session:<key> o un canal de entrega/activación sessionKey. Restaurar la sesión no vuelve a habilitar esos trabajos; utilice openclaw cron enable <jobId>. Las sesiones con un trabajo vinculado habilitado muestran una insignia de reloj en la barra lateral de la interfaz de control.

openclaw cron run <jobId> retorna después de poner en cola la ejecución manual. Utilice --wait para enlaces de apagado, scripts de mantenimiento u otras automatizaciones que deban bloquearse hasta que finalice la ejecución en cola; consulta periódicamente el runId retornado (tiempo de espera predeterminado 10m, intervalo de consulta 2s) y sale con 0 para el estado ok, y con un valor distinto de cero para error, skipped o un tiempo de espera agotado.

La herramienta cron del agente retorna resúmenes compactos de trabajos (id, name, enabled, nextRunAtMs, scheduleKind, lastRunStatus) desde cron(action: "list"); utilice cron(action: "get", jobId: "...") para obtener la definición completa de un trabajo. Los llamadores directos del Gateway pueden pasar compact: true a cron.list; omitirlo conserva la respuesta completa con vistas previas de entrega.

openclaw cron create es un alias de openclaw cron add. Los trabajos nuevos pueden utilizar una programación posicional ("0 9 * * 1", "every 1h", "20m" o una marca de tiempo ISO) seguida de un prompt posicional para el agente. Utilice --webhook <url> en cron add|create o cron edit para enviar mediante POST la carga útil de la ejecución finalizada a un endpoint HTTP; la entrega mediante Webhook no puede combinarse con indicadores de entrega por chat (--announce, --channel, --to, --thread-id, --account). En cron edit, --clear-channel, --clear-to, --clear-thread-id y --clear-account, desconfigure esos campos de enrutamiento individualmente (cada uno se rechaza junto con su indicador de configuración correspondiente), a diferencia de --no-deliver, que solo deshabilita la entrega alternativa del ejecutor.

Webhooks

El Gateway puede exponer endpoints de Webhook HTTP para activadores externos. Habilítelos en la configuración:

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

Autenticación

Cada solicitud debe incluir el token del enlace mediante un encabezado:

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

Los tokens en cadenas 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":"Nuevo correo electrónico recibido","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"message":"Resumir la bandeja de entrada","name":"Correo electrónico","model":"openai/gpt-5.6-sol"}'

Integración con Gmail PubSub

Conecte los activadores de la bandeja de entrada de Gmail con OpenClaw mediante Google PubSub.

Configuración mediante el asistente (recomendada)

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

Esto escribe la configuración hooks.gmail, habilita el preajuste de Gmail y utiliza Tailscale Funnel de forma predeterminada para el endpoint de envío (--tailscale funnel|serve|off).

Inicio automático del Gateway

Cuando hooks.enabled=true y hooks.gmail.account están establecidos, el Gateway inicia gog gmail watch serve durante el arranque y renueva automáticamente la supervisión. Establezca OPENCLAW_SKIP_GMAIL_WATCHER=1 para deshabilitarlo.

Configuración manual única

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

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

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: "openai/gpt-5.6-sol",      thinking: "high",    },  },}

Utilice el modelo de última generación y del mejor nivel disponible de su proveedor para las bandejas de entrada no confiables. El valor anterior es un ejemplo; el modelo debe existir en el catálogo y la lista de permitidos configurados.

Configuración

{  cron: {    enabled: true,    store: "~/.openclaw/cron/jobs.json",    triggers: {      enabled: false,    },    webhookToken: "replace-with-dedicated-webhook-token",    sessionRetention: "24h",  },}

webhookToken se envía como Authorization: Bearer <token> en los POST de Webhook de Cron.

cron.store es una clave lógica de almacenamiento y una ruta de migración de doctor, no un archivo JSON activo que deba editarse manualmente. Los datos de los trabajos se encuentran en SQLite; utilice la CLI o la API del Gateway para realizar cambios.

Deshabilite Cron mediante cron.enabled: false o OPENCLAW_SKIP_CRON=1.

Solución de problemas

Secuencia de comandos

openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --followopenclaw doctor

Contenido relacionado

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