OpenClaw hızlı ilerledi: Moltbot'tan Clawdbot adlandırma karmaşasından istikrarlı bir kimliğe ve hızla büyüyen topluluk benimsemesine geçti. Buradaysanız, muhtemelen pratik bir sonuç istiyorsunuz: evde veya uçta güvenebileceğiniz, Raspberry Pi üzerinde çalışan güvenilir bir OpenClaw düğümü. Bu kılavuz derin teknik geliştiriciler içindir. OpenClaw'u şunlarla kuracaksınız: * yeniden üretilebilir sistem bağımlılıkları, * hizmet izolasyonu, * kalp atışı odaklı sağlık kontrolleri (önce uygun fiyatlı kontroller), * seçici model çağırma, * isteğe bağlı güvenli sanal alan kalıpları, * ve API düzeyinde gözlemlenebilirlik. Bu süreçte, Apidog'un nerede yardımcı olduğunu göstereceğim: OpenClaw uç noktalarını doğrulama, regresyon testleri oluşturma ve ekibinizin kullanımı için yerel API yüzeyinizi belgeleme. düğme
1) Kurulumdan önce mimari kararlar
`apt`'ye dokunmadan önce, Pi'nizin çıkarım iş akışlarını nasıl çalıştıracağına karar verin.
Seçenek A: Pi orkestratör olarak, model dışa aktarılmış
Sınırlı RAM'e sahip Raspberry Pi 4/5 için en iyisi. * OpenClaw orkestrasyonu, zamanlamayı, eklentileri ve kalp atışlarını yerel olarak çalıştırır. * Yoğun LLM çıkarımı uzak sağlayıcılara veya bir LAN model sunucusuna yönlendirilir. * Daha düşük termal yük, daha iyi çalışma süresi.
Seçenek B: Pi sadece hafif yerel modeller için
Kesin gizlilik ve çevrimdışı görevler için iyi. * Kompakt modeller kullanın (nicelendirilmiş, küçük bağlam pencereleri). * Ağır işlem hatlarını ve uzun zincirleri kısıtlayın. * Gecikme ödünleşmeleri bekleyin.
Seçenek C: Hibrit yönlendirme
En pratik mimari. * Önce ucuz deterministik kontroller. * Sadece gerektiğinde model çağrılarına yükseltme. * Düşük riskli görevleri yerel, yüksek karmaşıklıkta uzaktan yönlendirme. Bu "önce ucuz kontroller, modeller sadece gerektiğinde" kalıbı, maliyeti, termal baskıyı ve gecikme artışlarını kontrol ettiği için çekirdek bir OpenClaw güvenilirlik stratejisi haline gelmiştir.
2) Donanım ve İşletim Sistemi temeli
Önerilen donanım
* Tercihen Raspberry Pi 5 (8GB)* Raspberry Pi 4 (4GB+) daha hafif iş yükleri için çalışır * Dayanıklılık için microSD yerine NVMe veya yüksek kaliteli SSD * Kararlı güç kaynağı ve aktif soğutma
İşletim Sistemi
Raspberry Pi OS Lite (64-bit) veya ARM64 için Ubuntu Server 24.04 kullanın. Sonra güncelleyin: bash sudo apt update && sudo apt upgrade -y sudo reboot Ana bilgisayar adını ve zaman senkronizasyonunu ayarlayın (günlükler ve belirteç süreleri için önemli): bash sudo hostnamectl set-hostname openclaw-pi sudo timedatectl set-ntp true
3) Çalışma zamanı bağımlılıklarını yükleyin
OpenClaw yığınları, eklentilere bağlı olarak genellikle Python ve/veya Node işçilerini kullanır. Gelişen modüllerle uyumlu kalmak için her ikisini de yükleyin. ``` sudo apt install -y git curl wget jq build-essential pkg-config python3 python3-venv python3-pip nodejs npm redis-server sqlite3 ``` Sürümleri kontrol edin: bash python3 --version node --version npm --version redis-server --version Neden Redis + SQLite? * Redis: düşük gecikmeli kuyruk/durum sinyali. * SQLite: tek düğümlü kurulumlar için hafif yerel kalıcılık. Daha sonra çok düğümlü için kalıcılığı Postgres'e taşıyın.
4) Özel bir hizmet kullanıcısı oluşturun
Aracıları `pi` veya `root` olarak çalıştırmaktan kaçının. ``` sudo useradd -m -s /bin/bash openclaw sudo usermod -aG sudo openclaw sudo mkdir -p /opt/openclaw sudo chown -R openclaw:openclaw /opt/openclaw ``` Kullanıcı değiştirin: bash sudo su - openclaw cd /opt/openclaw
5) OpenClaw'u klonlayın ve yapılandırın
bash git clone https://github.com//.git app cd app
OpenClaw proje sayfasından mevcut resmi depo yolunu ile değiştirin.
Python ortamı oluşturun: ``` python3 -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install -r requirements.txt ``` Bir Node hizmeti varsa: ``` npm ci ``` Ortam şablonunu kopyalayın: ``` cp .env.example .env ``` Tipik `.env` şekli: ``` env OPENCLAW_HOST=0.0.0.0 OPENCLAW_PORT=8080 OPENCLAW_LOG_LEVEL=info STATE_BACKEND=redis REDIS_URL=redis://127.0.0.1:6379 DB_URL=sqlite:////opt/openclaw/app/data/openclaw.db MODEL_ROUTER=hybrid LOCAL_MODEL_ENABLED=true REMOTE_MODEL_ENABLED=true REMOTE_MODEL_API_KEY=your_key_here HEARTBEAT_INTERVAL_SEC=15 HEARTBEAT_TIMEOUT_SEC=5 CHEAP_CHECKS_ENABLED=true SANDBOX_MODE=on SANDBOX_PROVIDER=process ``` Sırları korumak için `chmod 600 .env` kullanın.
6) Güvenilirlik için systemd hizmeti ekleyin
`/etc/systemd/system/openclaw.service` oluşturun: ``` ini [Unit] Description=OpenClaw Agent Service After=network-online.target redis.service Wants=network-online.target [Service] Type=simple User=openclaw WorkingDirectory=/opt/openclaw/app Environment="PYTHONUNBUFFERED=1" ExecStart=/opt/openclaw/app/.venv/bin/python -m openclaw.server Restart=always RestartSec=3 TimeoutStartSec=30 TimeoutStopSec=20 ```
Temel güvenlik güçlendirme
NoNewPrivileges=true PrivateTmp=true ProtectSystem=full ProtectHome=true ReadWritePaths=/opt/openclaw/app/data /opt/openclaw/app/logs [Install] WantedBy=multi-user.target Etkinleştirin ve başlatın: ``` sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw sudo systemctl status openclaw ``` Günlükleri takip edin: bash journalctl -u openclaw -f
7) Kalp atışı stratejisi uygulayın (önce ucuz kontroller)
Tekrarlanan bir topluluk dersi: bariz hataları tespit etmek için model belirteçlerini harcamayın.
Önerilen katmanlı kalp atışı
- L0 işlem kontrolü: hizmet canlı, bağlantı noktası açık.
- L1 bağımlılık kontrolü: Redis/DB erişilebilir, kuyruk gecikmesi kabul edilebilir.
- L2 deterministik görev kontrolü: statik doğrulama betiği çalıştırın.
- L3 model destekli prob: yalnızca önceki kontroller geçerliyse ancak güven düşükse.
Örnek sözde yapılandırma: yaml heartbeat: interval_sec: 15 timeout_sec: 5 stages: - name: process type: tcp target: 127.0.0.1:8080 - name: deps type: internal checks: [redis_ping, db_read] - name: deterministic type: task command: "python scripts/selfcheck.py" - name: model_probe type: llm enabled_on: degraded_only Bu kalıp, kısıtlı donanımda çalışma süresini korurken maliyeti ve yanlış alarmları azaltır.
8) Sanal alan sınırlarıyla güvenli yürütme
OpenClaw araçlar (kabuk, tarayıcı, dosya yazma) çalıştırıyorsa, yürütmeyi izole edin. Pi üzerinde minimum temel: * ayrıcalıksız kullanıcı altında araçları çalıştırın, * geniş dosya sistemi yazmalarını reddedin, * dizinleri beyaz listeye alın, * alt işlem zaman aşımı ve bellek tavanları ayarlayın. Yığınınız güçlendirilmiş sanal alanları (güvenli aracı sanal alan modellerine benzer) destekliyorsa, güvenilmeyen araç çağrıları için bunu kullanın. Pratik koruma önlemleri: env TOOL_EXEC_TIMEOUT_MS=12000 TOOL_MAX_STDOUT_KB=256 TOOL_ALLOWED_PATHS=/opt/openclaw/app/workdir TOOL_BLOCK_NETWORK_BY_DEFAULT=true Ağ özellikli araçlar için yalnızca açık ana bilgisayar listelerine izin verin.
9) OpenClaw API'lerini Apidog ile doğrulayın
OpenClaw kurulduktan sonra, onu herhangi bir API ürünü gibi ele alın: sözleşmeleri tanımlayın, davranışı test edin ve regresyonları takip edin.
Apidog burada neden var?
Apidog'u şunlar için kullanabilirsiniz: * OpenClaw OpenAPI spesifikasyonunuzu içe aktarın veya tasarlayın, * yerel Pi uç noktalarına karşı otomatik testler çalıştırın, * kalp atışı yükleri için görsel iddialar oluşturun, * çevrimdışı hata ayıklama için alt akış bağımlılıklarını taklit edin, * ekip üyeleri için etkileşimli belgeler yayınlayın.
Örnek sağlık uç noktası testi
Uç nokta varsayalım: `GET /healthz` Beklenen yanıt: ``` { "status": "ok", "checks": { "redis": "ok", "db": "ok", "queue_lag_ms": 12 } } ``` Apidog'da bir test senaryosu oluşturun:
- HTTP 200'ü onaylayın.
- `status == ok` olduğunu onaylayın.
- `checks.queue_lag_ms < 100` olduğunu onaylayın.
- Redis'in durdurulduğu negatif bir ortam ekleyin; bozuk durum bekleyin.
Bu, "iyi görünüyor" ifadesini tekrarlanabilir API kalite geçitlerine dönüştürür.
10) Raspberry Pi'de performans ayarlaması
CPU ve termal kontrol
İzleme: bash vcgencmd measure_temp uptime top Sıcaklık güvenli sürekli limitleri aşarsa, kısma nedeniyle çıkarım gecikmesi artacaktır.
Bellek baskısı
Gerektiğinde zram veya mütevazı takas (swap) etkinleştirin, ancak gerçek zamanlı akışlar için takas yoğun iş yüklerinden kaçının.
Kuyruk ve eşzamanlılık
Muhafazakar başlayın: env WORKER_CONCURRENCY=1 MAX_INFLIGHT_TASKS=4 Ardından p95 gecikmesi ve hata oranları gözlemlendikten sonra artırın.
Günlük döndürme
SD/SSD aşınmasını önleyin: bash sudo apt install -y logrotate `/opt/openclaw/app/logs/*.log` için döndürme kuralları ekleyin.
11) Sorun giderme kılavuzu
Hizmet birkaç saniyede bir dalgalanıyor
* Hatalı ortam anahtarlarını veya eksik API anahtarını kontrol edin. * Tam izleme bilgisi görmek için uygulamayı manuel olarak venv içinde çalıştırın. bash sudo su - openclaw cd /opt/openclaw/app source .venv/bin/activate python -m openclaw.server
Redis bağlantısı reddedildi
bash sudo systemctl status redis redis-cli ping `PONG` değilse, OpenClaw'da hata ayıklamadan önce Redis'i düzeltin.
Birkaç dakika sonra yüksek gecikme
Muhtemelen termal kısma veya bellek baskısı. * model bağlamını azaltın, * işçi eşzamanlılığını düşürün, * ağır çağrıları uzak modele taşıyın.
Kalp atışları geçiyor ancak görevler başarısız oluyor
Kontrolleriniz çok yüzeysel. Gerçek iş akışlarını taklit eden deterministik görev probları ekleyin (dosya okuma, ayrıştırma, özetleme, yanıt kodlama).
12) Üretime yakın uç kullanım için güçlendirme kontrol listesi
- Özel kullanıcı (`openclaw`), kök ayrıcalığı olmayan çalışma zamanı
- systemd yeniden başlatma politikası ve kaynak kısıtlamaları
- Sıkı izinlere sahip `.env` içindeki sırlar
- Ters proxy (Caddy/Nginx) aracılığıyla TLS sonlandırma
- Güvenlik duvarı izin listesi (yalnızca LAN/VPN)
- Model probu yükseltmeli kalp atışı katmanları
- Araç sanal alanı kısıtlamaları
- Apidog'da API sözleşme testleri
- Yapılandırma değişiklikleri için CI/CD'de otomatik test çalıştırma
Arka uç, QA ve ön uç ekipleri arasında işbirliği yapıyorsanız, OpenClaw API spesifikasyonunu paylaşılan bir Apidog çalışma alanına koyun. Şema değişikliklerini, testleri, sahte verileri ve belgeleri araçlar arasında dağıtmak yerine senkronize tutacaksınız.
13) Açığa çıkarmanız gereken örnek uç nokta haritası
Yüzeyi küçük ve açık tutun: * `GET /healthz` — temel sağlık * `GET /readyz` — bağımlılık hazır olma durumu * `GET /metrics` — Prometheus uyumlu metrikler * `POST /v1/tasks` — görev gönder * `GET /v1/tasks/{id}` — durumu sorgula * `POST /v1/chat/completions` — isteğe bağlı uyumluluk uç noktası Bunları OpenAPI'de belgeleyin. Ardından Apidog'un şema öncelikli iş akışını kullanarak yanıt tutarlılığını zorunlu kılın ve OpenClaw modülleri geliştikçe tüketicileri bozmaktan kaçının.
Sonuç
Bir Raspberry Pi üzerinde OpenClaw çalıştırmak, kısıtlamalar için tasarım yaptığınızda kesinlikle uygulanabilirdir: * yerel olarak düzenleyin, seçici olarak çıkarım yapın, * önce ucuz kontrollerle kalp atışı katmanları kullanın, * araç yürütmeyi sanal alana alın, * yerel aracınızı testler ve belgelerle gerçek bir API hizmeti olarak ele alın. Bu kombinasyon size günlük otomasyon için uygun fiyatlı, özel ve yeterince kararlı bir düğüm sunar. Temiz bir sonraki adım istiyorsanız, OpenClaw uç noktalarınızı Apidog'a aktarın ve bugün üç otomatik test oluşturun: `healthz`, `readyz` ve bir uçtan uca görev akışı. Regresyonları erken yakalayacak ve aracı yığınınız büyüdükçe Pi dağıtımınızın güvenilirliğini koruyacaksınız. düğme