OpenClaw (Moltbot/Clawdbot) Nasıl Güncellenir? En Son Sürüm Yükleme Rehberi

OpenClaw (eskiden Moltbot/Clawdbot) hızla gelişiyor. Bu hız, özellikler için harika, ancak aynı zamanda sık sık şu alanlarda değişiklikler olduğu anlamına geliyor:

• ajan orkestrasyonu davranışı
• kalp atışı mantığı (önce ucuz kontroller, model çağrıları yalnızca gerektiğinde)
• ortam değişkeni adları
• kalıcılık şeması ve geçiş akışı
• eklenti ve araç sözleşmesi varsayımları

Eğer sıradan bir şekilde (git pull && restart) güncellerseniz, fark edilmeyen sorunlarla karşılaşma riski taşırsınız: çalışanlar sağlıklı görünür ancak görevleri tamamlamayı bırakır, şema kayması nedeniyle araç adaptörleri başarısız olur veya kalp atışı/model eşikleri değiştiği için maliyet artışları meydana gelir.

Bu rehber, size somut komutlar ve doğrulama adımlarıyla birlikte üretime güvenli bir güncelleme stratejisi sunar.

Güncellemeden önce: kurulum topolojinizi belirleyin

Çoğu gerçek OpenClaw dağıtımı şu modellerden birine uyar:

1. Tek düğümlü Docker çalıştırması (hızlı kendi kendine barındırma)
2. Docker Compose yığını (OpenClaw + Veritabanı + Redis + yan uygulamalar)
3. Systemd + venv (VPS'e kaynak kurulumu)
4. Hibrit uç kurulumu (EC2 + Tailscale + özel kontrol düzlemi)

Güncelleme planınız, geri alma mekanikleri farklılık gösterdiği için topolojinize uygun olmalıdır.

• Docker/Compose: görüntü etiketi yeniden sabitleme yoluyla geri alma.
• Kaynak kurulumu: git etiketi + bağımlılık kilidi yoluyla geri alma.
• Yönetilen Veritabanı: şema geri alma önemsiz olmayabilir.

Mevcut topolojinizi henüz belgelediyseniz, önce bunu yapın.

Adım 1: mevcut sürümünüzü sabitleyin ve çalışma zamanı durumunu yakalayın

Bunu geri yükleme noktanız olarak kabul edin.

A. Sürüm/derleme meta verilerini kaydedin

Konteyner görüntüsü

docker ps --format 'table {{.Names}}\t{{.Image}}'

Eğer OpenClaw sürüm uç noktası sağlıyorsa

curl -s http://localhost:8080/version | jq

Git tabanlı kurulum

cd /opt/openclaw git rev-parse --short HEAD git describe --tags --always

B. Ortam ve yapılandırma anlık görüntüsü alın

cp /etc/openclaw/.env /backups/openclaw-env-$(date +%F).bak cp -r /etc/openclaw/config /backups/openclaw-config-$(date +%F)

Ayrıca gizli referansları (ham gizli dizileri değil) dışa aktarın ve token sağlayıcılarını, model yönlendirme ayarlarını ve kalp atışı eşiklerini doğrulayın.

C. Kalıcı verileri yedekleyin

Postgres için:

pg_dump -Fc -h  -U   > /backups/openclaw-$(date +%F).dump

Redis için (eğer durum bilgisi olan kuyruklar/kontrol noktaları önemliyse):

redis-cli -h  BGSAVE

Bu adımı atlarsanız, bir geri alma planınız olmaz.

Adım 2: geçiş işaretleri ve davranış değişiklikleri için sürüm notlarını okuyun

Son OpenClaw gelişimi (yeniden adlandırma dönemi refaktörleri dahil) göz önüne alındığında, sürüm notları genellikle aşağıdaki gibi bir defalık gereksinimleri içerir:

• ortam değişkeni yeniden adlandırması (CLAW_*'dan OPENCLAW_* desenlerine)
• geçiş komutu değişiklikleri
• kalp atışı zamanlayıcısı varsayılanları
• araç/eklenti manifest format güncellemeleri
• eski model adaptör arayüzlerinin kullanımdan kaldırılması

Sürüm notlarından kısa bir kontrol listesi oluşturun:

• gerekli yapılandırma yeniden adlandırmaları
• geçiş komutu
• kuyruk/konu değişiklikleri
• yeni sağlık uç noktası semantiği
• varsayılan zaman aşımı/maliyet koruma değişiklikleri

Adım 3: güncellemeyi bir ön üretim ortamında sahneleyin

Üretimde asla önce test etmeyin. Dağıtım şeklinizi klonlayın.

Minimum sahneleme doğruluğu:

• aynı OpenClaw sürüm farkı (mevcut -> hedef)
• aynı veritabanı motoru ana sürümü
• aynı kuyruk arka ucu
• aynı model sağlayıcı adaptörleri
• temsili gerçek iş akışları (en az 5–10)

Ekibinizin OpenClaw etrafında API'ları (özel araçlar, webhook'lar, iş kontrolü) varsa, Apidog tam da burada hemen yardımcı olur.

Apidog'u şunlar için kullanın:

• OpenAPI tanımlarınızı içe aktarın/güncelleyin
• araç uç noktalarınız için istek/yanıt sözleşmelerini doğrulayın
• dağıtımdan önce senaryo tabanlı regresyon testleri çalıştırın
• değişen uç noktalar için etkileşimli belgeler yayınlayın, böylece ön uç/QA ekipleri hızlıca uyum sağlar

Bu, "OpenClaw sorunsuz yükseltildi, ancak entegrasyonlar bozuldu" gibi olayları önler.

Adım 4: dağıtım türüne göre güncelleme

Seçenek A: Docker Compose

docker-compose.yml dosyasında açık etiketleri sabitleyin (üretimde latest kullanmaktan kaçının).

services: openclaw: image: ghcr.io/openclaw/openclaw:v1.14.2 env_file: - .env depends_on: - postgres - redis

Güncelleme süreci:

docker compose pull openclaw docker compose up -d openclaw

Eğer geçişler ayrıysa:

docker compose run --rm openclaw openclaw migrate

Ardından çalışanları yeniden başlatın:

docker compose up -d worker scheduler

Seçenek B: Yalın Docker

docker pull ghcr.io/openclaw/openclaw:v1.14.2 docker stop openclaw docker rm openclaw

docker run -d   --name openclaw   --env-file /etc/openclaw/.env   -p 8080:8080   ghcr.io/openclaw/openclaw:v1.14.2

Gerekirse geçiş komutunu çalıştırın.

Seçenek C: Kaynak + systemd

cd /opt/openclaw git fetch --tags git checkout v1.14.2

Ortamı yeniden oluşturun

source .venv/bin/activate pip install -r requirements.txt

Geçiş yapın

openclaw migrate

Yeniden başlatın

sudo systemctl restart openclaw-api openclaw-worker openclaw-scheduler

systemd birim geçersiz kılmalarının hala yeni CLI argümanlarıyla eşleştiğini doğrulayın.

Adım 5: "işlem çalışıyor" ötesinde sağlığı doğrulayın

Çalışan bir süreç sağlıklı bir ajan sistemi değildir.

Hemen çalıştırılacak sağlık kontrolleri

API canlılığı/hazırlığı

curl -f http://localhost:8080/health/live curl -f http://localhost:8080/health/ready

Kuyruk verimi

• test işini kuyruğa ekle
• çalışan talebini onayla
• tamamlama gecikmesini onayla

1. Kalp atışı davranışı
   Son kalp atışı tasarım trendleri (önce ucuz kontroller) göz önüne alındığında, şunları sağlayın:

• ucuz propların zamanında çalışmasını
• model destekli kontrollerin yalnızca beklenen eşiklerde tetiklenmesini
• kazara sürekli LLM çağrısı yapılmamasını

Maliyet ve gecikme korumaları
Aynı test iş yükü için güncelleme öncesi/sonrası token/maliyet telemetrisini kontrol edin.

Eklenti/araç çağırma
Kritik araç adaptörü başına en az bir çağrı çalıştırın.

Adım 6: Apidog ile API sözleşmesi ve regresyon testleri çalıştırın

Birçok OpenClaw operatörünün güvenilirliği hızla artırabileceği yer burasıdır.

OpenClaw'un dahili API'lerle (görev API'leri, araç API'leri, geri arama uç noktaları) etkileşime girmesi durumunda, Apidog'u bir kalite kapısı olarak kullanın:

• Tasarım: uç nokta şemalarını OpenAPI öncelikli bir iş akışında hizalı tutun.
• Test: başarı, zaman aşımı, yeniden deneme ve hatalı yüklere yönelik otomatik test senaryoları oluşturun.
• Sahte Nesne Kullanımı (Mocking): aşağı akış araçları çevrimdışı olsa bile OpenClaw davranışını test etmek için akıllı sahte uç noktalar kullanın.
• Dokümantasyon: değişen sözleşmeler için otomatik olarak belgeler oluşturun, böylece ekipler eski örnekleri kullanmayı bırakır.
• CI/CD: her sürüm yükseltmesinde, dağıtım promosyonundan önce regresyon paketini çalıştırın.

Pratik desen:

1. Mevcut koleksiyonu/spesifikasyonu Apidog'a aktarın.
2. OpenClaw'un bağlı olduğu alanlar (task_id, status, tool_result, correlation_id) için doğrulamalar ekleyin.
3. Negatif durumlar (429, 500, zaman aşımı) ekleyin.
4. Yükseltme dalında CI'da çalıştırın.
5. Sözleşmeyi bozan farklılıklar ortaya çıkarsa sürümü engelleyin.

Bu, yeniden başlatma sonrası iki uç noktayı manuel olarak test etmekten çok daha güvenlidir.

Adım 7: üretim için dağıtım stratejisi

Tek düğümlü kurulumlar için kısa bir bakım penceresi planlayın.

Çok örnekli kurulumlar için, kademeli/kanarya dağıtımı yapın:

1. bir API örneğini güncelleyin
2. bir çalışan havuzu segmentini güncelleyin
3. 15-30 dakika boyunca hata oranını, kuyruk gecikmesini, token harcamasını gözlemleyin
4. stabilse dağıtıma devam edin

Bu metrikleri izleyin:

• görev başarı oranı
• yeniden deneme hacmi
• özel mesaj kuyruğu (dead-letter queue) büyümesi
• p95 görev tamamlama süresi
• LLM istek oranı/token kullanımı

Küçük bir yapılandırma değişikliği sağlık kontrollerini geçebilir ancak verimi düşürebilir.

Yaygın yükseltme sorunları ve düzeltmeleri

1) Başarılı API başlangıcından sonra çalışanlar boşta kalıyor

Neden: kuyruk ad alanı/konusu değişti veya ortam değişkeni yeniden adlandırması gözden kaçtı.

Çözüm: eski/yeni ortam dosyalarını karşılaştırın ve kuyruk ön eki ayarlarını doğrulayın.

2) Kalp atışları aşırı model çağrılarını tetikliyor

Neden: varsayılanlar değişti; ucuz kontrol eşiği ayarlanmadı.

Çözüm: yapılandırmada kalp atışı katmanlarını ve model yükseltme limitlerini açıkça ayarlayın.

3) Şema hataları ile araç/eklenti hataları

Neden: yükseltmeden sonra yük sözleşmesi kayması.

Çözüm: Apidog sözleşme testlerini çalıştırın; araç adaptörlerini yeni gerekli alanlara güncelleyin.

4) Yükseltme sonrası token maliyetinde artış

Neden: yeniden deneme politikası + kalp atışı değişiklikleri + daha uzun bağlam pencereleri.

Çözüm: yeniden deneme sayısını sınırlayın, bütçe politikasını uygulayın, istek izlerini önceki sürümle karşılaştırın.

5) Yeniden adlandırma karmaşası (Moltbot/Clawdbot/OpenClaw)

Neden: karışık paket adları, konteyner etiketleri, eski belgeler.

Çözüm: dahili çalışma kitaplarını tek bir kanonik artefakt kaynağı ve etiketleme kuralı üzerinde standartlaştırın.

Kendi kendine barındıranlar için güvenlik ve ağ notları

Birçok geliştirici, OpenClaw'u EC2/VPS üzerinde özel ağ erişimi (örneğin, Tailscale benzeri topoloji) ile dağıtır. Güncellemeler sırasında:

• güvenlik duvarı kurallarının gerilemediğini doğrulayın
• yönetici uç noktalarının özel kaldığından emin olun
• güncelleme gizli dizi işleme değişiklikleri içeriyorsa API anahtarlarını döndürün
• konteyner/görüntü değişimlerinden sonra TLS sonlandırmayı doğrulayın

Ayrıca webhook geri arama izin listelerinin hala çıkış IP'si veya tünel kimliğiyle eşleştiğini onaylayın.

Önerilen üretim güncelleme kontrol listesi

Bunu her zaman kullanın:

• Mevcut sürümü/etiketi/işlemeyi belirleyin
• Veritabanı + yapılandırma + ortam referanslarını yedekleyin
• Sürüm notlarını okuyun ve zorunlu geçiş eylemlerini çıkarın
• Gerçekçi bir ön üretim ortamında güncellemeyi sahneleyin
• Apidog regresyon ve sözleşme testlerini çalıştırın
• Kontrollü üretim dağıtımı gerçekleştirin (kanarya/kademeli)
• Kuyruk, kalp atışı, araç yürütme ve maliyet metriklerini doğrulayın
• Test edilmiş geri alma komut dizisini hazır tutun
• Son sürümü ve yapılandırma farklılıklarını çalışma kitabına belgeleyin

Tutarlılık, hızdan daha önemlidir.

Son düşünceler

OpenClaw'u güvenli bir şekilde güncellemek, tek bir komutdan ziyade bir mühendislik disiplinidir. Moltbot/Clawdbot'tan OpenClaw'a uzanan yeniden adlandırma süreci, hızla gelişen bir projeyi yansıtmaktadır ve operasyonel sürecinizin buna ayak uydurması gerekmektedir.

Sağlam bir dağıtım/geri alma yöntemini API sözleşmesi testleriyle birleştirirseniz, çoğu yükseltme sıkıntısından kaçınacaksınız. Apidog burada doğal bir uyum sağlar: API sözleşmelerini tasarlayın ve sürümleyin, otomatik regresyon kontrolleri çalıştırın, sahneleme sırasında bağımlılıkları taklit edin ve OpenClaw'un dokunduğu her arayüz için doğru belgeler yayınlayın.

Mevcut güncelleme iş akışınız çoğunlukla manuel ise, küçük adımlarla başlayın: bu hafta bir sahneleme geçidi ve bir otomatik Apidog test paketi ekleyin. Bu tek değişiklik genellikle bir sonraki sürüme kadar karşılığını verir.