Zamanlanmış görevler

Cron, Gateway'in yerleşik zamanlayıcısıdır. İşleri kalıcı hale getirir, aracıyı doğru zamanda uyandırır ve çıktıyı bir sohbet kanalına veya Webhook uç noktasına geri iletebilir.

# Hızlı başlangıç

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

openclaw cron list
openclaw cron show <job-id>

openclaw cron runs --id <job-id>

# Cron nasıl çalışır?

• Cron, Gateway işleminin içinde çalışır (modelin içinde değil).
• İş tanımları ~/.openclaw/cron/jobs.json içinde kalıcı hale getirilir, böylece yeniden başlatmalar zamanlamaları kaybettirmez.
• Çalışma zamanı yürütme durumu bunun yanında ~/.openclaw/cron/jobs-state.json içinde kalıcı hale getirilir. Cron tanımlarını git içinde izliyorsanız jobs.json dosyasını izleyin ve jobs-state.json dosyasını gitignore'a ekleyin.
• Ayrımdan sonra eski OpenClaw sürümleri jobs.json dosyasını okuyabilir, ancak çalışma zamanı alanları artık jobs-state.json içinde yaşadığı için işleri yeniymiş gibi değerlendirebilir.
• Gateway çalışırken veya durdurulmuşken jobs.json düzenlendiğinde OpenClaw, değişen zamanlama alanlarını bekleyen çalışma zamanı yuvası meta verileriyle karşılaştırır ve eski nextRunAtMs değerlerini temizler. Yalnızca biçimlendirme veya yalnızca anahtar sırası değişiklikleri bekleyen yuvayı korur.
• Tüm Cron yürütmeleri arka plan görevi kayıtları oluşturur.
• Gateway başlatıldığında, süresi geçmiş izole aracı turu işleri hemen yeniden oynatılmak yerine kanal bağlanma penceresinin dışına yeniden zamanlanır; böylece Discord/Telegram başlangıcı ve yerel komut kurulumu yeniden başlatmalardan sonra duyarlı kalır.
• Tek seferlik işler (--at) varsayılan olarak başarıdan sonra otomatik silinir.
• İzole Cron çalıştırmaları, çalışma tamamlandığında cron:<jobId> oturumları için izlenen tarayıcı sekmelerini/işlemlerini en iyi çabayla kapatır; böylece ayrılmış tarayıcı otomasyonu arkada yetim işlemler bırakmaz.
• Dar Cron kendi kendini temizleme yetkisini alan izole Cron çalıştırmaları yine de zamanlayıcı durumunu ve geçerli işlerinin kendi kendine filtrelenmiş listesini okuyabilir; böylece durum/Heartbeat denetimleri daha geniş Cron değiştirme erişimi kazanmadan kendi zamanlamalarını inceleyebilir.
• İzole Cron çalıştırmaları eski onay yanıtlarına karşı da koruma sağlar. İlk sonuç yalnızca geçici bir durum güncellemesiyse (on it, pulling everything together ve benzeri ipuçları) ve nihai yanıttan hâlâ hiçbir alt aracı çalıştırması sorumlu değilse OpenClaw, teslimden önce gerçek sonucu almak için bir kez yeniden istem gönderir.
• İzole Cron çalıştırmaları önce gömülü çalıştırmadan yapılandırılmış yürütme reddi meta verilerini tercih eder, ardından SYSTEM_RUN_DENIED ve INVALID_REQUEST gibi bilinen nihai özet/çıktı işaretlerine geri döner; böylece engellenmiş bir komut başarılı çalıştırma olarak raporlanmaz.
• İzole Cron çalıştırmaları, yanıt yükü üretilmediğinde bile çalıştırma düzeyindeki aracı hatalarını iş hatası olarak değerlendirir; böylece model/sağlayıcı hataları, işi başarılı sayarak temizlemek yerine hata sayaçlarını artırır ve hata bildirimlerini tetikler.
• İzole bir aracı turu işi timeoutSeconds değerine ulaştığında Cron alttaki aracı çalıştırmasını iptal eder ve ona kısa bir temizleme penceresi verir. Çalıştırma boşalmazsa Gateway sahipli temizleme, Cron zaman aşımını kaydetmeden önce o çalıştırmanın oturum sahipliğini zorla temizler; böylece kuyruğa alınmış sohbet işi eski bir işleme oturumunun arkasında kalmaz.

# Zamanlama türleri

Saat dilimi olmayan zaman damgaları UTC olarak değerlendirilir. Yerel duvar saati zamanlaması için --tz America/New_York ekleyin.

Saat başında yinelenen ifadeler, yük sıçramalarını azaltmak için otomatik olarak 5 dakikaya kadar kademelendirilir. Kesin zamanlamayı zorlamak için --exact, açık bir pencere için --stagger 30s kullanın.

# Ayın günü ve haftanın günü OR mantığını kullanır

Cron ifadeleri croner tarafından ayrıştırılır. Hem ayın günü hem de haftanın günü alanları joker değilse croner, alanlardan herhangi biri eşleştiğinde eşleşir — ikisi birden değil. Bu standart Vixie Cron davranışıdır.

# 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

Bu, ayda 0-1 kez yerine yaklaşık 5-6 kez tetiklenir. OpenClaw burada Croner'ın varsayılan OR davranışını kullanır. Her iki koşulu da zorunlu kılmak için Croner'ın + haftanın günü değiştiricisini (0 9 15 * +1) kullanın veya bir alana göre zamanlayıp diğerini işinizin isteminde ya da komutunda denetleyin.

# Yürütme stilleri

# İzole işler için yük seçenekleri

--model, seçilen izinli modeli o işin birincil modeli olarak kullanır. Bu, sohbet oturumu /model geçersiz kılmasıyla aynı değildir: iş birincili başarısız olduğunda yapılandırılmış geri dönüş zincirleri yine uygulanır. İstenen modele izin verilmiyorsa veya model çözümlenemiyorsa Cron, işin aracı/varsayılan model seçimine sessizce geri dönmek yerine çalıştırmayı açık bir doğrulama hatasıyla başarısız kılar.

Eski veya elle düzenlenmiş jobs.json girişleri payload.model değerini "default", "null", boş bir dize veya JSON null olarak saklıyorsa openclaw doctor --fix çalıştırın. Doctor bu geçersiz kalıcı geçersiz kılma nöbetçilerini kaldırır; çalışma zamanı bunları geri dönüş takma adları olarak desteklemez. Normal aracı/varsayılan model seçimini kullanmak için model alanını atlayın.

Cron işleri yük düzeyinde fallbacks de taşıyabilir. Mevcut olduğunda bu liste, iş için yapılandırılmış geri dönüş zincirinin yerini alır. Yalnızca seçilen modeli deneyen katı bir Cron çalıştırması istediğinizde iş yükünde/API'de fallbacks: [] kullanın. Bir işte --model varsa ancak ne yük ne de yapılandırılmış geri dönüşler varsa OpenClaw, aracı birincilinin gizli ek yeniden deneme hedefi olarak eklenmemesi için açık bir boş geri dönüş geçersiz kılması geçirir.

İzole işler için model seçimi önceliği şöyledir:

1. Gmail hook model geçersiz kılması (çalıştırma Gmail'den geldiğinde ve bu geçersiz kılmaya izin verildiğinde)
2. İş başına yük model
3. Kullanıcı tarafından seçilmiş kayıtlı Cron oturumu model geçersiz kılması
4. Aracı/varsayılan model seçimi

Hızlı mod da çözümlenen canlı seçimi izler. Seçilen model yapılandırmasında params.fastMode varsa izole Cron varsayılan olarak bunu kullanır. Kayıtlı oturum fastMode geçersiz kılması ise her iki yönde de yapılandırmaya üstün gelir.

İzole bir çalıştırma canlı model değiştirme devrine girerse Cron, değiştirilen sağlayıcı/model ile yeniden dener ve yeniden denemeden önce bu canlı seçimi etkin çalıştırma için kalıcı hale getirir. Değişiklik yeni bir auth profili de taşıyorsa Cron bu auth profili geçersiz kılmasını da etkin çalıştırma için kalıcı hale getirir. Yeniden denemeler sınırlıdır: ilk deneme artı 2 değiştirme yeniden denemesinden sonra Cron sonsuz döngüye girmek yerine iptal eder.

İzole bir Cron çalıştırması aracı çalıştırıcısına girmeden önce OpenClaw, baseUrl değeri loopback, özel ağ veya .local olan yapılandırılmış api: "ollama" ve api: "openai-completions" sağlayıcıları için erişilebilir yerel sağlayıcı uç noktalarını denetler. Bu uç nokta kapalıysa çalıştırma, model çağrısı başlatmak yerine net bir sağlayıcı/model hatasıyla skipped olarak kaydedilir. Uç nokta sonucu 5 dakika önbelleğe alınır; böylece aynı kapalı yerel Ollama, vLLM, SGLang veya LM Studio sunucusunu kullanan çok sayıda zamanı gelmiş iş, istek fırtınası oluşturmak yerine tek küçük probu paylaşır. Atlanan sağlayıcı ön denetimi çalıştırmaları yürütme hatası geri çekilmesini artırmaz; yinelenen atlama bildirimleri istediğinizde failureAlert.includeSkipped etkinleştirin.

# Teslimat ve çıktı

Kanal teslimi için --announce --channel telegram --to "-1001234567890" kullanın. Telegram forum konuları için -1001234567890:topic:123 kullanın; doğrudan RPC/config çağıranlar delivery.threadId değerini string veya sayı olarak da geçebilir. Slack/Discord/Mattermost hedefleri açık prefix'ler kullanmalıdır (channel:<id>, user:<id>). Matrix oda ID'leri büyük/küçük harfe duyarlıdır; Matrix'ten gelen tam oda ID'sini veya room:!room:server biçimini kullanın.

Announce teslimi channel: "last" kullandığında veya channel değerini atladığında, telegram:123 gibi sağlayıcı prefix'li bir hedef, cron oturum geçmişine veya tek bir yapılandırılmış kanala fallback yapmadan önce kanalı seçebilir. Yalnızca yüklenen Plugin tarafından duyurulan prefix'ler sağlayıcı seçicileridir. delivery.channel açıkça belirtilmişse, hedef prefix'i aynı sağlayıcıyı adlandırmalıdır; örneğin, channel: "whatsapp" ile to: "telegram:123" kullanımı, WhatsApp'ın Telegram ID'sini telefon numarası olarak yorumlamasına izin vermek yerine reddedilir. channel:<id>, user:<id>, imessage:<handle> ve sms:<number> gibi hedef türü ve servis prefix'leri, sağlayıcı seçicileri değil, kanalın sahip olduğu hedef söz dizimi olarak kalır.

Yalıtılmış işler için sohbet teslimi paylaşılır. Bir sohbet rotası varsa, iş --no-deliver kullansa bile ajan message aracını kullanabilir. Ajan yapılandırılmış/geçerli hedefe gönderirse, OpenClaw fallback announce adımını atlar. Aksi halde announce, webhook ve none yalnızca ajan turundan sonra runner'ın son yanıtla ne yapacağını kontrol eder.

Bir ajan etkin sohbetten yalıtılmış bir hatırlatıcı oluşturduğunda, OpenClaw fallback announce rotası için korunmuş canlı teslim hedefini saklar. Dahili oturum anahtarları küçük harfli olabilir; geçerli sohbet bağlamı kullanılabilir olduğunda sağlayıcı teslim hedefleri bu anahtarlardan yeniden oluşturulmaz.

Örtük announce teslimi, eskimiş hedefleri doğrulamak ve yeniden yönlendirmek için yapılandırılmış kanal allowlist'lerini kullanır. DM pairing-store onayları fallback otomasyon alıcıları değildir; zamanlanmış bir işin proaktif olarak bir DM'ye göndermesi gerekiyorsa delivery.to değerini ayarlayın veya kanal allowFrom girdisini yapılandırın.

Hata bildirimleri ayrı bir hedef yolunu izler:

• cron.failureDestination, hata bildirimleri için global varsayılanı ayarlar.
• job.delivery.failureDestination, bunu iş bazında geçersiz kılar.
• Hiçbiri ayarlanmamışsa ve iş zaten announce üzerinden teslim ediyorsa, hata bildirimleri artık birincil announce hedefine fallback yapar.
• delivery.failureDestination, birincil teslim modu webhook olmadığı sürece yalnızca sessionTarget="isolated" işlerinde desteklenir.
• failureAlert.includeSkipped: true, bir işi veya global cron uyarı politikasını yinelenen atlanmış çalıştırma uyarılarına dahil eder. Atlanmış çalıştırmalar ayrı bir ardışık atlama sayacı tutar, bu nedenle yürütme hatası backoff'unu etkilemez.

# CLI örnekleri

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

openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize overnight updates." \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 1" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Weekly deep analysis of project progress." \
  --model "opus" \
  --thinking high \
  --announce

# Webhook'lar

Gateway, dış tetikleyiciler için HTTP Webhook uç noktalarını sunabilir. Config içinde etkinleştirin:

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

# Kimlik doğrulama

Her istek hook token'ını header üzerinden içermelidir:

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

Query-string token'ları reddedilir.

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 entegrasyonu

Gmail gelen kutusu tetikleyicilerini Google PubSub üzerinden OpenClaw'a bağlayın.

# Sihirbaz kurulumu (önerilir)

openclaw webhooks gmail setup --account [email protected]

Bu, hooks.gmail config'ini yazar, Gmail preset'ini etkinleştirir ve push uç noktası için Tailscale Funnel kullanır.

# Gateway otomatik başlatma

hooks.enabled=true ve hooks.gmail.account ayarlandığında, Gateway açılışta gog gmail watch serve başlatır ve watch'ı otomatik olarak yeniler. Devre dışı bırakmak için OPENCLAW_SKIP_GMAIL_WATCHER=1 ayarlayın.

# Manuel tek seferlik kurulum

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

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

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

# Gmail model geçersiz kılması

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

# İşleri yönetme

# List all jobs
openclaw cron list

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

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

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

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

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

# Delete a job
openclaw cron remove <jobId>

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

# Yapılandırma

{
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1,
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
    },
    webhookToken: "replace-with-dedicated-webhook-token",
    sessionRetention: "24h",
    runLog: { maxBytes: "2mb", keepLines: 2000 },
  },
}

maxConcurrentRuns hem zamanlanmış cron dispatch'i hem de yalıtılmış ajan turu yürütmesini sınırlar. Yalıtılmış cron ajan turları, kuyruk içinde özel cron-nested yürütme lane'ini kullanır; bu nedenle bu değeri artırmak, bağımsız cron LLM çalıştırmalarının yalnızca dış cron wrapper'larını başlatmak yerine paralel ilerlemesini sağlar. Paylaşılan cron dışı nested lane'i bu ayarla genişletilmez.

Runtime durum sidecar'ı cron.store değerinden türetilir: ~/clawd/cron/jobs.json gibi bir .json store, ~/clawd/cron/jobs-state.json kullanır; .json soneki olmayan bir store yolu ise -state.json ekler.

jobs.json dosyasını elle düzenlerseniz, jobs-state.json dosyasını kaynak kontrolü dışında bırakın. OpenClaw bu sidecar'ı bekleyen slot'lar, etkin işaretleyiciler, son çalıştırma metadata'sı ve harici olarak düzenlenen bir işin yeni bir nextRunAtMs değerine ne zaman ihtiyaç duyduğunu scheduler'a söyleyen zamanlama kimliği için kullanır.

Cron'u devre dışı bırakın: cron.enabled: false veya OPENCLAW_SKIP_CRON=1.

# Sorun giderme

# Komut sıralaması

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

# İlgili

• Otomasyon ve Görevler — tüm otomasyon mekanizmalarına genel bakış
• Arka Plan Görevleri — cron yürütmeleri için görev defteri
• Heartbeat — periyodik ana oturum turları
• Zaman Dilimi — zaman dilimi yapılandırması