Kurulum

TL;DR

Güncellemeleri ne sıklıkta istediğinize ve Gateway'i kendiniz çalıştırmak isteyip istemediğinize göre bir kurulum iş akışı seçin:

• Özelleştirme repo dışında yaşar: yapılandırmanızı ve çalışma alanınızı ~/.openclaw/openclaw.json ve ~/.openclaw/workspace/ içinde tutun; böylece repo güncellemeleri bunlara dokunmaz.
• Kararlı iş akışı (çoğu kişi için önerilir): macOS uygulamasını kurun ve paketlenmiş Gateway'i çalıştırmasına izin verin.
• En yeni iş akışı (dev): Gateway'i pnpm gateway:watch ile kendiniz çalıştırın, ardından macOS uygulamasının Local modda bağlanmasına izin verin.

Önkoşullar (kaynaktan)

• Node 24 önerilir (Node 22 LTS, şu anda 22.19+, hâlâ desteklenir)
• Kaynak checkout'ları için pnpm gerekir. OpenClaw, dev modunda paketlenmiş plugin'leri extensions/* pnpm çalışma alanı paketlerinden yükler; bu nedenle kökte npm install tam kaynak ağacını hazırlamaz.
• Docker (isteğe bağlı; yalnızca konteynerleştirilmiş kurulum/e2e için - bkz. Docker)

Özelleştirme stratejisi (güncellemeler sorun çıkarmasın diye)

"%100 bana göre özelleştirilmiş" ve kolay güncellemeler istiyorsanız, özelleştirmelerinizi şurada tutun:

• Yapılandırma: ~/.openclaw/openclaw.json (JSON/JSON5 benzeri)
• Çalışma alanı: ~/.openclaw/workspace (skills, istemler, bellekler; bunu özel bir git reposu yapın)

Bir kez önyükleyin:

openclaw setup

Bu repo içinden yerel CLI girişini kullanın:

openclaw setup

Henüz global kurulumunuz yoksa pnpm openclaw setup ile çalıştırın.

Gateway'i bu repodan çalıştırın

pnpm build sonrasında paketlenmiş CLI'yi doğrudan çalıştırabilirsiniz:

node openclaw.mjs gateway --port 18789 --verbose

Kararlı iş akışı (önce macOS uygulaması)

1. OpenClaw.app'i (menü çubuğu) kurun ve başlatın.
2. İlk katılım/izinler kontrol listesini tamamlayın (TCC istemleri).
3. Gateway'in Local olduğundan ve çalıştığından emin olun (uygulama yönetir).
4. Yüzeyleri bağlayın (örnek: WhatsApp):

openclaw channels login

5. Sağlamlık kontrolü:

openclaw health

İlk katılım derlemenizde mevcut değilse:

• openclaw setup çalıştırın, ardından openclaw channels login çalıştırın, sonra Gateway'i manuel başlatın (openclaw gateway).

En yeni iş akışı (Gateway bir terminalde)

Hedef: TypeScript Gateway üzerinde çalışmak, hot reload almak, macOS uygulama UI'ını bağlı tutmak.

0) (İsteğe bağlı) macOS uygulamasını da kaynaktan çalıştırın

macOS uygulamasını da en yeni sürümde istiyorsanız:

./scripts/restart-mac.sh

1) Dev Gateway'i başlatın

pnpm install# Yalnızca ilk çalıştırmada (veya yerel OpenClaw yapılandırmasını/çalışma alanını sıfırladıktan sonra)pnpm openclaw setuppnpm gateway:watch

gateway:watch, Gateway izleme sürecini adlandırılmış bir tmux oturumunda başlatır veya yeniden başlatır ve etkileşimli terminallerden otomatik bağlanır. Etkileşimsiz shell'ler ayrık kalır ve tmux attach -t openclaw-gateway-watch-main yazdırır; etkileşimli bir çalıştırmayı ayrık tutmak için OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch kullanın veya foreground izleme modu için pnpm gateway:watch:raw kullanın. İzleyici ilgili kaynak, yapılandırma ve paketlenmiş plugin meta verisi değişikliklerinde yeniden yükler. İzlenen Gateway başlangıç sırasında çıkarsa, gateway:watch openclaw doctor --fix --non-interactive komutunu bir kez çalıştırır ve yeniden dener; bu yalnızca dev'e özel onarım geçişini devre dışı bırakmak için OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 ayarlayın. pnpm openclaw setup, yeni bir checkout için tek seferlik yerel yapılandırma/çalışma alanı başlatma adımıdır. pnpm gateway:watch, dist/control-ui'ı yeniden derlemez; bu nedenle ui/ değişikliklerinden sonra pnpm ui:build komutunu yeniden çalıştırın veya Control UI geliştirirken pnpm ui:dev kullanın.

2) macOS uygulamasını çalışan Gateway'inize yönlendirin

OpenClaw.app içinde:

• Bağlantı Modu: Local Uygulama, yapılandırılmış porttaki çalışan gateway'e bağlanır.

3) Doğrulayın

• Uygulama içi Gateway durumu "Mevcut gateway kullanılıyor …" olarak görünmelidir
• Veya CLI ile:

openclaw health

Yaygın tuzaklar

• Yanlış port: Gateway WS varsayılanı ws://127.0.0.1:18789; uygulama + CLI'yi aynı portta tutun.
• Durumun nerede yaşadığı:
  • Kanal/sağlayıcı durumu: ~/.openclaw/credentials/
  • Model kimlik doğrulama profilleri: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Oturumlar: ~/.openclaw/agents/<agentId>/sessions/
  • Günlükler: /tmp/openclaw/

Kimlik bilgisi depolama haritası

Kimlik doğrulamayı hata ayıklarken veya nelerin yedekleneceğine karar verirken bunu kullanın:

• WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Telegram bot token'ı: config/env veya channels.telegram.tokenFile (yalnızca normal dosya; sembolik bağlantılar reddedilir)
• Discord bot token'ı: config/env veya SecretRef (env/file/exec sağlayıcıları)
• Slack token'ları: config/env (channels.slack.*)
• Eşleştirme izin listeleri:
  • ~/.openclaw/credentials/<channel>-allowFrom.json (varsayılan hesap)
  • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (varsayılan olmayan hesaplar)
• Model kimlik doğrulama profilleri: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Dosya destekli gizli bilgi payload'ı (isteğe bağlı): ~/.openclaw/secrets.json
• Eski OAuth içe aktarma: ~/.openclaw/credentials/oauth.json Daha fazla ayrıntı: Güvenlik.

Güncelleme (kurulumunuzu bozmadan)

• ~/.openclaw/workspace ve ~/.openclaw/ konumlarını "size ait şeyler" olarak tutun; kişisel istemleri/yapılandırmayı openclaw reposuna koymayın.
• Kaynağı güncelleme: git pull + pnpm install + pnpm gateway:watch kullanmaya devam edin.

Linux (systemd kullanıcı servisi)

Linux kurulumları systemd kullanıcı servisi kullanır. Varsayılan olarak systemd, oturum kapatma/boşta kalma durumunda kullanıcı servislerini durdurur; bu da Gateway'i sonlandırır. İlk katılım sizin için lingering'i etkinleştirmeyi dener (sudo isteyebilir). Hâlâ kapalıysa şunu çalıştırın:

sudo loginctl enable-linger $USER

Her zaman açık veya çok kullanıcılı sunucular için kullanıcı servisi yerine sistem servisini düşünün (lingering gerekmez). systemd notları için bkz. Gateway runbook.

İlgili dokümanlar

• Gateway runbook (bayraklar, gözetim, portlar)
• Gateway yapılandırması (yapılandırma şeması + örnekler)
• Discord ve Telegram (yanıt etiketleri + replyToMode ayarları)
• OpenClaw assistant kurulumu
• macOS uygulaması (gateway yaşam döngüsü)