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

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 зафиксирует тайм-аут, поэтому ожидающая работа чата не остается за устаревшим обрабатываемым сеансом.
• Если изолированный агентский ход зависает до старта исполнителя или до первого вызова модели, cron фиксирует тайм-аут с указанием фазы, например setup timed out before runner start или stalled before first model call (last phase: context-engine). Эти сторожевые проверки покрывают встроенные провайдеры и провайдеры на основе CLI до фактического запуска их внешнего процесса CLI и ограничиваются отдельно от длинных значений timeoutSeconds, чтобы сбои холодного старта, аутентификации или контекста проявлялись быстро, а не ждали полного бюджета задания.
• Если вы используете системный cron или другой внешний планировщик для запуска openclaw agent, оберните его жесткой эскалацией завершения, даже если CLI обрабатывает SIGTERM/SIGINT. Запуски через Gateway просят Gateway прервать принятые запуски; локальные и встроенные резервные запуски получают тот же сигнал прерывания. Для GNU timeout предпочитайте timeout -k 60 600 openclaw agent ... вместо простого timeout 600 ...; значение -k — это страховка супервизора на случай, если процесс не сможет завершиться штатно. Для systemd-юнитов сохраняйте ту же форму: используйте стоп-сигнал SIGTERM плюс окно ожидания, например TimeoutStopSec, перед любым окончательным завершением. Если повторная попытка повторно использует --run-id, пока исходный запуск Gateway еще активен, дубликат считается находящимся в выполнении, а не запускает второй запуск.

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

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

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

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

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

Параметры полезной нагрузки для изолированных задач

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

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

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

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

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

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

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

Перед тем как изолированный запуск cron войдет в runner агента, OpenClaw проверяет доступные локальные endpoint-адреса провайдера для настроенных провайдеров api: "ollama" и api: "openai-completions", у которых baseUrl является loopback, частной сетью или .local. Если этот endpoint недоступен, запуск записывается как skipped с понятной ошибкой провайдера/модели вместо запуска вызова модели. Результат endpoint кэшируется на 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 чувствительны к регистру; используйте точный идентификатор комнаты или форму room:!room:server из Matrix.

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

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

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

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

Язык вывода

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

openclaw cron edit <jobId> \  --message "Summarize the updates. Respond in Chinese; keep URLs, code, and product names unchanged."

Для файлов шаблонов держите языковую инструкцию в отрендеренном запросе и проверяйте, что placeholders, такие как {{language}}, заполнены до запуска задачи. Если вывод смешивает языки, сделайте правило явным, например: "Use Chinese for narrative text and keep technical terms in English."

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

• 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 endpoint-адреса webhook для внешних триггеров. Включите в конфигурации:

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

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

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

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

Токены в query-string отклоняются.

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 при загрузке и автоматически продлевает watch. Задайте 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",    },  },}

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

# Список всех заданийopenclaw cron list # Получить одно сохраненное задание как JSONopenclaw cron get <jobId> # Показать одно задание, включая разрешенный маршрут доставкиopenclaw cron show <jobId> # Изменить заданиеopenclaw cron edit <jobId> --message "Updated prompt" --model "opus" # Принудительно запустить задание сейчасopenclaw cron run <jobId> # Принудительно запустить задание сейчас и дождаться его конечного статусаopenclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s # Запустить только если срок наступилopenclaw cron run <jobId> --due # Просмотреть историю запусковopenclaw cron runs --id <jobId> --limit 50 # Просмотреть один точный запускopenclaw cron runs --id <jobId> --run-id <runId> # Удалить заданиеopenclaw cron remove <jobId> # Выбор агента (настройки с несколькими агентами)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, чтобы отправить payload завершенного запуска методом POST на конечную точку HTTP. Доставку Webhook нельзя сочетать с флагами доставки в чат, такими как --announce, --channel, --to, --thread-id или --account. В cron edit флаги --clear-channel, --clear-to, --clear-thread-id и --clear-account по отдельности сбрасывают эти поля маршрутизации (каждый отклоняется вместе с соответствующим флагом установки), что отличается от --no-deliver, который отключает резервную доставку runner.

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

{  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 — периодические ходы основной сессии
• Часовой пояс — конфигурация часового пояса