English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Advanced setup

Kurulum

Kısaca

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

  • Kişiselleş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ı yükleyin ve paketlenmiş Gateway’i onun ç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 Yerel modda bağlanmasına izin verin.

Önkoşullar (kaynaktan)

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

Kişiselleştirme stratejisi (güncellemeler sorun çıkarmasın diye)

"Tamamen bana göre" ve kolay güncelleme istiyorsanız özelleştirmenizi şuralarda tutun:

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

Bir kez başlatın:

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ırma

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 yükleyin ve başlatın (menü çubuğu).
  2. İlk kullanım/izinler kontrol listesini tamamlayın (TCC istemleri).
  3. Gateway’in Yerel olduğundan ve çalıştığından emin olun (uygulama bunu yönetir).
  4. Yüzeyleri bağlayın (örnek: WhatsApp):
openclaw channels login
  1. Sağlık kontrolü yapın:
openclaw health

İlk kullanım akışı derlemenizde yoksa:

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

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

Amaç: TypeScript Gateway üzerinde çalışmak, sıcak yeniden yükleme 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 kullanmak 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 setup
pnpm 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şimli olmayan kabuklar 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 ön plan izleme modu için pnpm gateway:watch:raw kullanın. İzleyici, ilgili kaynak, yapılandırma ve paketlenmiş-plugin meta veri 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 amaçlı onarım geçişini devre dışı bırakmak için OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 ayarlayın. pnpm openclaw setup, taze 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 öğesini 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: Yerel 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 aynı portta kalsın.
  • Durumun bulunduğu yer:
    • 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ğrulama hata ayıklarken veya neleri yedekleyeceğinize karar verirken bunu kullanın:

  • WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Telegram bot token’ı: yapılandırma/env veya channels.telegram.tokenFile (yalnızca normal dosya; symlink’ler reddedilir)
  • Discord bot token’ı: yapılandırma/env veya SecretRef (env/file/exec sağlayıcıları)
  • Slack token’ları: yapılandırma/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 yükü (isteğe bağlı): ~/.openclaw/secrets.json
  • Eski OAuth içe aktarımı: ~/.openclaw/credentials/oauth.json Daha fazla ayrıntı: Güvenlik.

Güncelleme (kurulumunuzu bozmadan)

  • ~/.openclaw/workspace ve ~/.openclaw/ öğelerini "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ı bir 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 kullanım akışı sizin için kalıcılığı 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 bir sistem servisi düşünün (kalıcılık gerekmez). systemd notları için bkz. Gateway çalışma kılavuzu.

İlgili belgeler