Yerel olarak OpenClaw'u (topluluk çatalları veya paketlerinde genellikle **Moltbot/Clawdbot** olarak geçer) çalıştırmaya çalışıyorsanız, zor kısım genellikle depoyu klonlamak değil; çalışma zamanı sürümlerini, ortam değişkenlerini ve platforma özgü derleme sorunlarını yönetmektir.
Bu kılavuz size pratik, çapraz platform bir kurulum yolu sunar ve işler ters gittiğinde yardımcı olacak hata ayıklama adımlarını içerir.
Düğme
OpenClaw kurulumu tipik olarak neler içerir?
Çoğu OpenClaw dağıtımı aynı dağıtım şeklini izler:
- Git'ten kaynak kodunu klonlayın.
- Dil/çalışma zamanı bağımlılıklarını yükleyin.
- Bir `.env` dosyasını yapılandırın (anahtarlar, DB, API anahtarları).
- Depolamayı başlatın (derlemeye bağlı olarak SQLite/Postgres/Redis).
- Taşıma/önyükleme betiklerini çalıştırın.
- Hizmeti başlatın ve sağlık uç noktalarını doğrulayın.
Belirli çatalınız farklı olsa bile, bu kontrol listesi neredeyse her kuruluma uyar.
Önkoşullar (tüm işletim sistemleri)
İşletim sistemine özgü adımlardan önce, bu temel bilgileri onaylayın:
- Git: klonlama ve güncellemeleri çekmek için.
- Çalışma Zamanı: çatalına bağlı olarak genellikle Node.js (LTS) veya Python (3.10+).
- Paket yöneticisi: Node için npm/pnpm/yarn, Python için pip/poetry.
- Veritabanı (isteğe bağlı): yerel hızlı başlangıç için SQLite, ekip/hazırlık kullanımı için Postgres.
- Terminal kabuğu: PowerShell (Windows), zsh/bash (macOS/Linux).
Araçlarınızı doğrulayın
bash git --version node -v npm -v python3 --version pip --version
Proje belgeleriniz kesin sürümleri belirtiyorsa, şimdi sabitleyin. Sürüm kayması, "benim makinemde çalışıyor" kurulum hatalarının 1 numaralı nedenidir.
OpenClaw'u macOS/Linux'a kurun
macOS veya Linux'ta, birleşik yükleyiciyi çalıştırın:
curl -fsSL https://openclaw.ai/install.sh | bash
Alternatif kurulum yöntemleri ve ayrıntılı sistem gereksinimleri için **Kurulum** bölümüne bakın.
1. İlk Kurulum Sihirbazını Çalıştırın
openclaw onboard --install-daemon
Bu sihirbaz kimlik doğrulamasını, ağ geçidi yapılandırmasını ve isteğe bağlı mesajlaşma kanallarını (WhatsApp, Telegram vb.) ayarlar.
Tam bir kılavuz için İlk Kurulum Sihirbazı belgelerine bakın.
2. Ağ Geçidini Doğrulayın
Arka plan hizmetini (daemon) kurduysanız, zaten çalışıyor olmalıdır. Durumunu şununla kontrol edin:
openclaw gateway status
3. Kontrol Kullanıcı Arayüzünü Açın
Panoyu başlatın:
openclaw dashboard
Artık OpenClaw örneğinize tarayıcı tabanlı kontrol kullanıcı arayüzü aracılığıyla erişebilirsiniz.
OpenClaw'u Windows'a kurun
Windows'ta (PowerShell ile), birleşik yükleyiciyi çalıştırın:
iwr -useb https://openclaw.ai/install.ps1 | iexAlternatif kurulum yöntemleri ve ayrıntılı sistem gereksinimleri için **Kurulum** bölümüne bakın.
1. İlk Kurulum Sihirbazını Çalıştırın
openclaw onboard --install-daemon
Bu sihirbaz kimlik doğrulamasını, ağ geçidi yapılandırmasını ve isteğe bağlı mesajlaşma kanallarını (WhatsApp, Telegram vb.) ayarlar.
Tam bir kılavuz için İlk Kurulum Sihirbazı belgelerine bakın.
2. Ağ Geçidini Doğrulayın
Arka plan hizmetini (daemon) kurduysanız, zaten çalışıyor olmalıdır. Durumunu şununla kontrol edin:
openclaw gateway status
3. Kontrol Kullanıcı Arayüzünü Açın
Panoyu başlatın:
openclaw dashboard
Artık OpenClaw örneğinize tarayıcı tabanlı kontrol kullanıcı arayüzü aracılığıyla erişebilirsiniz.
Docker tabanlı kurulum (tutarlılık için önerilir)
Daha az ana bilgisayar düzeyinde bağımlılık sorunu yaşamak istiyorsanız, OpenClaw'u Docker Compose ile çalıştırın.
Örnek `docker-compose.yml` deseni:
yaml version: '3.9' services: app: build: . ports: - "3000:3000" env_file: - .env depends_on: - db - redis
db: image: postgres:15 environment: POSTGRES_USER: openclaw POSTGRES_PASSWORD: openclaw POSTGRES_DB: openclaw ports: - "5432:5432"
redis: image: redis:7 ports: - "6379:6379"
Başlatın:
bash docker compose up --build
Bu yaklaşım, özellikle ekipler için macOS, Windows ve Linux'ta yeniden üretilebilir ortamlar sağlar.
Yaygın kurulum hataları ve düzeltmeleri
1) MODULE_NOT_FOUND veya içe aktarma hataları
Neden: bağımlılıklar yüklü değil, yanlış kilit dosyası veya uyumsuz çalışma zamanı.
Düzeltme:
- `node_modules` klasörünü kaldırın ve `npm ci` ile yeniden yükleyin.
- Çalışma zamanını proje belgeleriyle eşleştirin (`.nvmrc`, `pyproject.toml`, `runtime.txt`).
- Depo desteklemediği sürece paket yöneticilerini karıştırmayın.
2) Veritabanı bağlantısı reddedildi
Neden: DB hizmeti kapalı veya `DATABASE_URL` yanlış.
Düzeltme:
- Hizmet durumunu onaylayın (`systemctl status postgresql`, `brew services list`).
- Ana bilgisayar/port/kullanıcı/parola/DB adını doğrulayın.
- Bağlantıyı `psql` ile bağımsız olarak test edin.
3) Bağlantı noktası zaten kullanımda
Düzeltme: çakışan işlemi bulun ve durdurun.
macOS/Linux:
bash lsof -i :3000 kill -9
Windows:
powershell netstat -ano | findstr :3000 taskkill /PID /F
4) Linux/macOS'ta izin reddedildi
Neden: betiğin yürütme izni yok.
bash chmod +x ./scripts/*.sh
Kesinlikle gerekmedikçe uygulama komutlarını `sudo` ile çalıştırmaktan kaçının.
5) Ortam değişkeni yüklenmedi
Düzeltme:
- `.env` dosyasının proje kök dizininde olduğundan emin olun.
- `.env` değişikliğinden sonra işlemi yeniden başlatın.
- Yükleyici paketinin (`dotenv`) erken başlatıldığını doğrulayın.
Kurulum sonrası güvenlik kontrol listesi
OpenClaw başarıyla başladıktan sonra, ekip arkadaşlarınızla paylaşmadan önce bunları yapın:
- Varsayılan anahtarları döndürün.
- Güçlü API anahtarları uygulayın.
- CORS ve geri çağırma URL'lerini kısıtlayın.
- Üretime uygun günlük seviyeleri ayarlayın.
- Sağlık/hazırlık kontrolleri ekleyin.
- DB birimleri için yedekleme stratejisi yapılandırın.
Yerel ana bilgisayarın ötesinde açığa çıkarırsanız, TLS ile bir ters proxy (Nginx/Caddy) arkasına koyun.
OpenClaw API'lerini hızlıca doğrulayın ve test edin
Kurulumdan sonra, yalnızca süreç başlangıcını değil, uç nokta davranışını da doğrulamanız gerekir.
Hızlı bir desen:
- OpenClaw'un OpenAPI dosyasını içe aktarın (sağlanmışsa).
- Yerel/hazırlık URL'leri için ortam değişkenleri oluşturun.
- Kimlik doğrulama, CRUD ve webhook uç noktaları için regresyon kontrolleri oluşturun.
İşte bu noktada **Apidog** sürtünmeyi azaltmaya yardımcı olur. API'leri tek bir çalışma alanında tasarlayabilir, hata ayıklayabilir, test edebilir ve belgeleyebilir, böylece kurulum doğrulaması birden fazla araca yayılmaz.
Apidog'daki pratik iş akışı:
- Şemayı içe aktarın ve istek koleksiyonları oluşturun.
- Senaryo tabanlı iddialarla otomatik test ekleyin.
- Eksik bağımlılıkları dinamik yanıtlarla taklit edin.
- Kararlı hale geldiğinde ekibinizle etkileşimli belgeleri paylaşın.
Sık sık değişiklik gösteren OpenClaw çatallarını test ediyorsanız, bu tek iş akışı, betikleri ve ayrı belgeleri manuel olarak sürdürmekten daha hızlıdır.
OpenClaw çatalları için yükseltme stratejisi
Açık kaynak bot/araç çatalları hızla gelişir. Tekrarlanabilir bir güncelleme yolu kullanın:
bash git fetch origin git checkout main git pull npm ci npm run migrate npm test npm run dev
Python derlemeleri için:
bash pip install -r requirements.txt python manage.py migrate pytest
Yukarı akış değişikliklerini birleştirmeden önce dal tabanlı test kullanın. Ekibiniz API sözleşmeleri kullanıyorsa, şema farkı kontrolleri sessizce bozucu değişiklikleri önler.
Son düşünceler
OpenClaw'u (Moltbot/Clawdbot) macOS, Windows veya Linux'a kurmak, üç değişkeni kontrol ettiğinizde oldukça basittir: **çalışma zamanı sürümü**, **ortam yapılandırması** ve **hizmet bağımlılıkları**.
Bir ekip için kuruyorsanız, Docker Compose genellikle en güvenilir temeldir. Yerel geliştirme için kuruyorsanız, yerel kurulum iyidir; sadece sürümleri sabitleyin ve başlangıç betiklerini işleyin.
OpenClaw çalışmaya başladıktan sonra, API doğrulamasını doğru yapılmış kurulumun bir parçası olarak kabul edin. Uç noktaları Apidog'a aktarabilir ve test edebilir, otomatik kontroller oluşturabilir ve çatalınız geliştikçe belgeleri senkronize tutabilirsiniz.
Ücretsiz deneyin – kredi kartı gerekmez – ve ilk önyüklemeden regresyon testine kadar OpenClaw API iş akışınızı sabitlemek için kullanın.Düğme