Запланированные задачи

Cron — это встроенный планировщик Gateway. Он сохраняет задания, будит агента в нужное время и может доставлять вывод обратно в канал чата или конечную точку Webhook.

Быстрый старт

openclaw cron create "2026-02-01T16:00:00Z" \  --name "Reminder" \  --session main \  --system-event "Reminder: check the cron docs draft" \  --wake now \  --delete-after-run

openclaw cron listopenclaw cron get <job-id>openclaw cron show <job-id>

openclaw cron runs --id <job-id>

Как работает Cron

• Cron выполняется внутри процесса Gateway (не внутри модели).
• Определения заданий, состояние выполнения и история запусков сохраняются в общей базе данных состояния SQLite OpenClaw, поэтому перезапуски не теряют расписания.
• При обновлении выполните openclaw doctor --fix, чтобы импортировать устаревшие файлы ~/.openclaw/cron/jobs.json, jobs-state.json и runs/*.jsonl в SQLite и переименовать их с суффиксом .migrated. Некорректные строки заданий пропускаются во время выполнения и копируются в jobs-quarantine.json для последующего исправления или проверки.
• cron.store по-прежнему задает логический ключ хранилища Cron и путь импорта doctor. После импорта редактирование этого JSON-файла больше не меняет активные задания Cron; вместо этого используйте openclaw cron add|edit|remove или RPC-методы Cron в Gateway.
• Все выполнения Cron создают записи фоновых задач.
• При запуске Gateway просроченные задания изолированных ходов агента перепланируются за пределы окна подключения каналов, а не воспроизводятся немедленно, поэтому запуск Discord/Telegram и настройка нативных команд остаются отзывчивыми после перезапусков.
• Одноразовые задания (--at) по умолчанию автоматически удаляются после успешного выполнения.
• Изолированные запуски Cron по возможности закрывают отслеживаемые вкладки браузера/процессы для своего сеанса cron:<jobId> после завершения запуска, чтобы отсоединенная браузерная автоматизация не оставляла осиротевшие процессы.
• Изолированные запуски Cron, получившие узкое разрешение на самоочистку Cron, все еще могут читать состояние планировщика, самоотфильтрованный список своего текущего задания и историю запусков этого задания, поэтому проверки статуса/Heartbeat могут просматривать собственное расписание без получения более широкого доступа на изменение Cron.
• Изолированные запуски Cron также защищаются от устаревших подтверждающих ответов. Если первый результат — это только промежуточное обновление статуса (on it, pulling everything together и похожие подсказки), а ни один дочерний субагентский запуск больше не отвечает за финальный ответ, OpenClaw один раз повторно запрашивает фактический результат перед доставкой.
• Изолированные запуски Cron используют структурированные метаданные отказа выполнения из встроенного запуска, включая обертки node-host UNAVAILABLE, у которых вложенное сообщение об ошибке начинается с SYSTEM_RUN_DENIED или INVALID_REQUEST, поэтому заблокированная команда не отображается как успешный запуск, а обычный текст ассистента не считается отказом.
• Изолированные запуски Cron также считают ошибки агента на уровне запуска ошибками задания, даже когда полезная нагрузка ответа не создана, поэтому ошибки модели/провайдера увеличивают счетчики ошибок и запускают уведомления о сбоях, а не очищают задание как успешное.
• Когда изолированное задание хода агента достигает timeoutSeconds, Cron прерывает базовый запуск агента и дает ему короткое окно очистки. Если запуск не завершается, очистка, принадлежащая Gateway, принудительно очищает владение сеансом этого запуска до того, как Cron запишет тайм-аут, поэтому поставленная в очередь работа чата не остается за устаревшим обрабатывающим сеансом.
• Если изолированный ход агента зависает до старта runner или до первого вызова модели, Cron записывает тайм-аут с указанием фазы, например setup timed out before runner start или stalled before first model call (last phase: context-engine). Эти watchdog-механизмы покрывают встроенных провайдеров и провайдеров на базе CLI до фактического запуска их внешнего CLI-процесса и ограничиваются независимо от длинных значений timeoutSeconds, чтобы сбои холодного старта/аутентификации/контекста проявлялись быстро, а не ждали полного бюджета задания.
• Если вы используете системный cron или другой внешний планировщик для запуска openclaw agent, оберните его эскалацией жесткого завершения, даже несмотря на то что CLI обрабатывает SIGTERM/SIGINT. Запуски через Gateway просят Gateway прервать принятые запуски; локальные и встроенные резервные запуски получают тот же сигнал прерывания. Для GNU timeout предпочитайте timeout -k 60 600 openclaw agent ... вместо простого timeout 600 ...; значение -k — это аварийный предел супервизора, если процесс не может корректно завершиться. Для systemd units сохраняйте ту же форму, используя сигнал остановки SIGTERM плюс окно ожидания, например TimeoutStopSec, перед финальным завершением. Если повторная попытка переиспользует --run-id, пока исходный запуск Gateway все еще активен, дубликат отображается как выполняющийся, а не запускает второй запуск.

Типы расписаний

Временные метки без часового пояса считаются UTC. Добавьте --tz America/New_York для планирования по местному времени.

Повторяющиеся выражения на начало часа автоматически распределяются с разбросом до 5 минут, чтобы снизить пики нагрузки. Используйте --exact, чтобы принудительно задать точное время, или --stagger 30s для явного окна.

День месяца и день недели используют логику OR

Выражения Cron разбираются croner. Когда поля дня месяца и дня недели оба не являются wildcard, croner срабатывает, когда совпадает любое из полей, а не оба. Это стандартное поведение 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

Это срабатывает примерно 5-6 раз в месяц вместо 0-1 раза в месяц. Здесь OpenClaw использует стандартное поведение OR от Croner. Чтобы требовать оба условия, используйте модификатор дня недели + в Croner (0 9 15 * +1) или планируйте по одному полю, а другое проверяйте в промпте или команде задания.

Стили выполнения

Полезные нагрузки команд

Используйте полезные нагрузки команд для детерминированных скриптов, которые должны выполняться внутри планировщика Gateway без запуска изолированного хода агента на базе модели. Командные задания выполняются на хосте Gateway, захватывают stdout/stderr, записывают запуск в историю Cron и переиспользуют те же режимы доставки announce, webhook и none, что и изолированные задания.

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

--command <shell> сохраняет argv: ["sh", "-lc", <shell>]. Используйте --command-argv '["node","scripts/report.mjs"]', когда нужно точное выполнение argv без разбора shell. Необязательные поля --command-env KEY=VALUE, --command-input, --timeout-seconds, --no-output-timeout-seconds и --output-max-bytes управляют окружением процесса, stdin и ограничениями вывода.

Если stdout не пуст, этот текст является доставленным результатом. Если stdout пуст, а stderr не пуст, доставляется stderr. Если присутствуют оба потока, cron доставляет небольшой блок stdout: / stderr:. Нулевой код выхода записывает запуск как ok; ненулевой код выхода, сигнал, тайм-аут или тайм-аут отсутствия вывода записывает error и может запускать оповещения о сбоях. Команда, которая выводит только NO_REPLY, использует обычное подавление silent-token cron и ничего не отправляет обратно в чат.

Параметры payload для изолированных заданий

--model использует выбранную разрешенную модель как основную модель этого задания. Это не то же самое, что переопределение /model в чат-сессии: настроенные цепочки резервных вариантов по-прежнему применяются при сбое основной модели задания. Если запрошенная модель не разрешена или не может быть разрешена, cron завершает запуск с явной ошибкой валидации, а не незаметно возвращается к выбору модели агента/по умолчанию для задания.

Задания Cron также могут нести fallbacks на уровне payload. Если он присутствует, этот список заменяет настроенную цепочку резервных вариантов для задания. Используйте fallbacks: [] в payload/API задания, когда нужен строгий запуск cron, который пробует только выбранную модель. Если у задания есть --model, но нет ни payload, ни настроенных резервных вариантов, OpenClaw передает явное пустое переопределение резервных вариантов, чтобы основная модель агента не добавлялась как скрытая дополнительная цель повтора.

Предварительные проверки локальных провайдеров проходят по настроенным резервным вариантам перед тем, как пометить запуск cron как skipped; fallbacks: [] оставляет этот путь предварительной проверки строгим.

Приоритет выбора модели для изолированных заданий:

1. Переопределение модели Gmail hook (когда запуск пришел из Gmail и это переопределение разрешено)
2. model в payload отдельного задания
3. Выбранное пользователем сохраненное переопределение модели cron-сессии
4. Выбор модели агента/по умолчанию

Быстрый режим также следует разрешенному live-выбору. Если в конфигурации выбранной модели есть params.fastMode, изолированный cron использует его по умолчанию. Сохраненное переопределение fastMode сессии все равно имеет приоритет над конфигурацией в любую сторону. Автоматический режим использует порог params.fastAutoOnSeconds выбранной модели, если он присутствует, по умолчанию 60 секунд.

Если изолированный запуск попадает на live-передачу переключения модели, cron повторяет попытку с переключенным провайдером/моделью и сохраняет этот live-выбор для активного запуска перед повтором. Когда переключение также несет новый профиль аутентификации, cron сохраняет это переопределение профиля аутентификации для активного запуска. Повторы ограничены: после начальной попытки плюс 2 повтора переключения cron прерывает выполнение вместо бесконечного цикла.

Перед тем как изолированный запуск cron войдет в runner агента, OpenClaw проверяет доступные конечные точки локальных провайдеров для настроенных провайдеров api: "ollama" и api: "openai-completions", у которых baseUrl является loopback, адресом частной сети или .local. Если эта конечная точка недоступна, запуск записывается как skipped с понятной ошибкой провайдера/модели вместо начала вызова модели. Результат для конечной точки кэшируется на 5 минут, поэтому множество наступивших заданий, использующих один и тот же недоступный локальный сервер Ollama, vLLM, SGLang или LM Studio, совместно используют одну небольшую проверку вместо создания шквала запросов. Пропущенные из-за предварительной проверки провайдера запуски не увеличивают backoff ошибок выполнения; включите failureAlert.includeSkipped, если нужны повторяющиеся уведомления о пропусках.

Доставка и вывод

Используйте --announce --channel telegram --to "-1001234567890" для доставки в канал. Для тем форумов Telegram используйте -1001234567890:topic:123; OpenClaw также принимает принадлежащую Telegram сокращенную форму -1001234567890:123. Непосредственные вызывающие стороны RPC/config могут передавать delivery.threadId как строку или число. Цели Slack/Discord/Mattermost должны использовать явные префиксы (channel:<id>, user:<id>). Идентификаторы комнат Matrix чувствительны к регистру; используйте точный ID комнаты или форму room:!room:server из Matrix.

Когда доставка announce использует channel: "last" или опускает channel, цель с префиксом провайдера, такая как telegram:123, может выбрать канал до того, как cron вернется к истории сессии или единственному настроенному каналу. Только префиксы, объявленные загруженным Plugin, являются селекторами провайдера. Если delivery.channel задан явно, префикс цели должен называть того же провайдера; например, channel: "whatsapp" с to: "telegram:123" отклоняется, вместо того чтобы позволить WhatsApp интерпретировать Telegram ID как номер телефона. Префиксы типа цели и сервиса, такие как channel:<id>, user:<id>, imessage:<handle> и sms:<number>, остаются синтаксисом цели, принадлежащим каналу, а не селекторами провайдера.

Для изолированных заданий доставка в чат является общей. Если доступен маршрут чата, агент может использовать инструмент message, даже когда задание использует --no-deliver. Если агент отправляет сообщение настроенной/текущей цели, OpenClaw пропускает fallback-объявление. В противном случае announce, webhook и none управляют только тем, что runner делает с итоговым ответом после хода агента.

Когда агент создает изолированное напоминание из активного чата, OpenClaw сохраняет сохраненную live-цель доставки для fallback-маршрута announce. Внутренние ключи сессий могут быть в нижнем регистре; цели доставки провайдера не реконструируются из этих ключей, когда доступен текущий контекст чата.

Неявная доставка announce использует настроенные allowlist каналов для валидации и перенаправления устаревших целей. Подтверждения из DM pairing-store не являются получателями fallback-автоматизации; задайте delivery.to или настройте запись allowFrom канала, когда запланированное задание должно проактивно отправлять сообщения в DM.

Язык вывода

Задания Cron не выводят язык ответа из канала, локали или предыдущих сообщений. Поместите правило языка в запланированное сообщение или шаблон:

openclaw cron edit <jobId> \  --message "Суммируй обновления. Ответь на китайском; оставь URL, код и названия продуктов без изменений."

Для файлов шаблонов сохраняйте языковую инструкцию в сформированном промпте и проверяйте, что заполнены placeholders, такие как {{language}}, до запуска задания. Если вывод смешивает языки, задайте правило явно, например: "Используйте китайский для повествовательного текста и сохраняйте технические термины на английском."

Уведомления о сбоях используют отдельный путь назначения:

• cron.failureDestination задает глобальное значение по умолчанию для уведомлений о сбоях.
• job.delivery.failureDestination переопределяет его для отдельного задания.
• Если не задано ни одно из них, а задание уже доставляет сообщения через announce, уведомления о сбоях теперь используют этот основной целевой объект announce как резервный.
• delivery.failureDestination поддерживается только для заданий sessionTarget="isolated", если основной режим доставки не webhook.
• failureAlert.includeSkipped: true включает для задания или глобальной политики оповещений cron повторяющиеся оповещения о пропущенных запусках. Пропущенные запуски ведут отдельный счетчик последовательных пропусков, поэтому они не влияют на backoff при ошибках выполнения.

Примеры 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"

Webhooks

Gateway может предоставлять HTTP-эндпоинты Webhook для внешних триггеров. Включите в конфигурации:

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

Аутентификация

Каждый запрос должен включать токен hook через заголовок:

• Authorization: Bearer <token> (рекомендуется)
• x-openclaw-token: <token>

Токены в строке запроса отклоняются.

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

Интеграция Gmail PubSub

Подключите триггеры входящих Gmail к OpenClaw через Google PubSub.

Настройка мастером (рекомендуется)

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

Это записывает конфигурацию hooks.gmail, включает пресет Gmail и использует Tailscale Funnel для push-конечной точки.

Автозапуск Gateway

Когда задано hooks.enabled=true и установлен hooks.gmail.account, Gateway при запуске стартует gog gmail watch serve и автоматически продлевает наблюдение. Задайте OPENCLAW_SKIP_GMAIL_WATCHER=1, чтобы отказаться от этого.

Ручная одноразовая настройка

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

Переопределение модели Gmail

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

Управление заданиями

# List all jobsopenclaw cron list # Get one stored job as JSONopenclaw cron get <jobId> # Show one job, including resolved delivery routeopenclaw cron show <jobId> # Edit a jobopenclaw cron edit <jobId> --message "Updated prompt" --model "opus" # Force run a job nowopenclaw cron run <jobId> # Force run a job now and wait for its terminal statusopenclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s # Run only if dueopenclaw cron run <jobId> --due # View run historyopenclaw cron runs --id <jobId> --limit 50 # View one exact runopenclaw cron runs --id <jobId> --run-id <runId> # Delete a jobopenclaw cron remove <jobId> # Agent selection (multi-agent setups)openclaw cron create "0 6 * * *" "Check ops queue" --name "Ops sweep" --session isolated --agent opsopenclaw cron edit <jobId> --clear-agent

openclaw cron run <jobId> возвращается после постановки ручного запуска в очередь. Используйте --wait для хуков завершения, скриптов обслуживания или другой автоматизации, которая должна блокироваться до завершения поставленного в очередь запуска. Режим ожидания опрашивает точно возвращенный runId; он завершается с 0 для статуса ok и с ненулевым кодом для error, skipped или тайм-аута ожидания.

Инструмент агента cron возвращает компактные сводки заданий (id, name, enabled, nextRunAtMs, scheduleKind, lastRunStatus) из cron(action: "list"); используйте cron(action: "get", jobId: "...") для одного полного определения задания. Прямые вызывающие стороны Gateway могут передать compact: true в cron.list; если опустить это поле, сохраняется существующий полный ответ с предпросмотрами доставки.

openclaw cron create является псевдонимом для openclaw cron add, а новые задания могут использовать позиционное расписание ("0 9 * * 1", "every 1h", "20m" или ISO-метку времени), за которым следует позиционный промпт агента. Используйте --webhook <url> в cron add|create или cron edit, чтобы отправлять полезную нагрузку завершенного запуска POST-запросом на HTTP-конечную точку. Доставку Webhook нельзя сочетать с флагами доставки в чат, такими как --announce, --channel, --to, --thread-id или --account. В cron edit флаги --clear-channel, --clear-to, --clear-thread-id и --clear-account снимают эти поля маршрутизации по отдельности (каждый отклоняется вместе со своим соответствующим флагом установки), что отличается от --no-deliver, отключающего резервную доставку раннера.

Конфигурация

{  cron: {    enabled: true,    store: "~/.openclaw/cron/jobs.json",    maxConcurrentRuns: 8,    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 ограничивает и запланированную отправку cron, и выполнение изолированного агентского хода, а по умолчанию равно 8. Изолированные агентские ходы cron внутренне используют выделенную очередь выполнения cron-nested, поэтому увеличение этого значения позволяет независимым LLM-запускам cron продвигаться параллельно, а не только запускать их внешние оболочки cron. Общая не-cron очередь nested этим параметром не расширяется.

cron.store — это логический ключ хранилища и устаревший путь импорта doctor. Запустите openclaw doctor --fix, чтобы импортировать существующие JSON-хранилища в SQLite и архивировать их; будущие изменения cron должны проходить через CLI или API Gateway.

Отключить cron: cron.enabled: false или OPENCLAW_SKIP_CRON=1.

Устранение неполадок

Лестница команд

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

Связанные материалы

• Автоматизация — все механизмы автоматизации в одном обзоре
• Фоновые задачи — журнал задач для выполнений cron
• Heartbeat — периодические ходы основного сеанса
• Часовой пояс — конфигурация часового пояса