Gateway çalıştırma kılavuzu

Bu sayfayı Gateway hizmetinin 1. gün başlangıcı ve 2. gün operasyonları için kullanın.

5 dakikalık yerel başlangıç

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

Çalışma zamanı modeli

• Yönlendirme, denetim düzlemi ve kanal bağlantıları için her zaman açık tek süreç.
• Şunlar için tek çoklanmış port:
  • WebSocket denetim/RPC
  • HTTP API'leri (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • İsteğe bağlı /api/v1/admin/rpc gibi Plugin HTTP rotaları
  • Denetim UI'ı ve hook'lar
• Varsayılan bağlama modu: loopback.
• Kimlik doğrulama varsayılan olarak gereklidir. Paylaşılan gizli bilgi kurulumları gateway.auth.token / gateway.auth.password (veya OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD) kullanır ve loopback olmayan ters proxy kurulumları gateway.auth.mode: "trusted-proxy" kullanabilir.

OpenAI uyumlu uç noktalar

OpenClaw'un en yüksek kaldıraçlı uyumluluk yüzeyi artık şudur:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /v1/responses

Bu küme neden önemlidir:

• Çoğu Open WebUI, LobeChat ve LibreChat entegrasyonu önce /v1/models yoklar.
• Birçok RAG ve bellek hattı /v1/embeddings bekler.
• Agent-yerel istemciler giderek daha fazla /v1/responses tercih eder.

Planlama notu:

• /v1/models agent önceliklidir: openclaw, openclaw/default ve openclaw/<agentId> döndürür.
• openclaw/default, her zaman yapılandırılmış varsayılan agent'a eşlenen kararlı takma addır.
• Arka uç sağlayıcısı/model geçersiz kılması istediğinizde x-openclaw-model kullanın; aksi halde seçili agent'ın normal modeli ve embedding kurulumu denetimde kalır.

Bunların tümü ana Gateway portunda çalışır ve Gateway HTTP API'sinin geri kalanıyla aynı güvenilir operatör kimlik doğrulama sınırını kullanır.

Yönetici HTTP RPC (POST /api/v1/admin/rpc), WebSocket RPC kullanamayan ana makine araçları için ayrı, varsayılan olarak kapalı bir Plugin rotasıdır. Bkz. Yönetici HTTP RPC.

Port ve bağlama önceliği

Kurulu gateway hizmetleri, çözümlenen --port değerini supervisor metadata'sına kaydeder. gateway.port değiştirildikten sonra launchd/systemd/schtasks süreci yeni portta başlatsın diye openclaw doctor --fix veya openclaw gateway install --force çalıştırın.

Gateway başlangıcı, loopback olmayan bağlamalar için yerel Denetim UI kaynaklarını tohumlarken aynı etkin portu ve bağlamayı kullanır. Örneğin, --bind lan --port 3000 çalışma zamanı doğrulaması çalışmadan önce http://localhost:3000 ve http://127.0.0.1:3000 kaynaklarını tohumlar. HTTPS proxy URL'leri gibi uzak tarayıcı kaynaklarını gateway.controlUi.allowedOrigins içine açıkça ekleyin.

Sıcak yeniden yükleme modları

Operatör komut kümesi

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep, daha derin bir RPC sağlık yoklaması için değil, ek hizmet keşfi (LaunchDaemons/systemd sistem birimleri/schtasks) içindir.

Birden çok gateway (aynı ana makine)

Çoğu kurulum makine başına bir gateway çalıştırmalıdır. Tek bir gateway birden çok agent ve kanal barındırabilir.

Yalnızca bilinçli olarak izolasyon veya bir kurtarma botu istediğinizde birden çok gateway gerekir.

Yararlı denetimler:

openclaw gateway status --deepopenclaw gateway probe

Beklenecekler:

• gateway status --deep, eski launchd/systemd/schtasks kurulumları hâlâ duruyorsa Other gateway-like services detected (best effort) raporlayabilir ve temizlik ipuçları yazdırabilir.
• gateway probe, farklı gateway'ler yanıt verdiğinde veya OpenClaw erişilebilir hedeflerin aynı gateway olduğunu kanıtlayamadığında multiple reachable gateway identities uyarısı verebilir. Aynı gateway'e giden bir SSH tüneli, proxy URL'si veya yapılandırılmış uzak URL, taşıma portları farklı olsa bile birden çok taşıması olan tek gateway'dir.
• Bu bilinçliyse, her gateway için portları, yapılandırma/durumu ve çalışma alanı köklerini izole edin.

Her örnek için denetim listesi:

• Benzersiz gateway.port
• Benzersiz OPENCLAW_CONFIG_PATH
• Benzersiz OPENCLAW_STATE_DIR
• Benzersiz agents.defaults.workspace

Örnek:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

Ayrıntılı kurulum: /gateway/multiple-gateways.

Uzaktan erişim

Tercih edilen: Tailscale/VPN. Geri dönüş: SSH tüneli.

ssh -N -L 18789:127.0.0.1:18789 user@host

Ardından istemcileri yerel olarak ws://127.0.0.1:18789 adresine bağlayın.

Bkz.: Uzak Gateway, Kimlik Doğrulama, Tailscale.

Gözetim ve hizmet yaşam döngüsü

Üretim benzeri güvenilirlik için gözetimli çalıştırmaları kullanın.

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now openclaw-gateway[-<profile>].service

Geliştirme profili hızlı yolu

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

Varsayılanlar izole durum/yapılandırma ve temel gateway portu 19001 içerir.

Protokol hızlı başvurusu (operatör görünümü)

• İlk istemci çerçevesi connect olmalıdır.
• Gateway hello-ok anlık görüntüsü döndürür (presence, health, stateVersion, uptimeMs, sınırlar/politika).
• hello-ok.features.methods / events, çağrılabilir her yardımcı rotanın oluşturulmuş dökümü değil, tutucu bir keşif listesidir.
• İstekler: req(method, params) → res(ok/payload|error).
• Yaygın olaylar arasında connect.challenge, agent, chat, session.message, session.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, eşleştirme/onay yaşam döngüsü olayları ve shutdown bulunur.

Agent çalıştırmaları iki aşamalıdır:

1. Anında kabul onayı (status:"accepted")
2. Arada stream edilen agent olaylarıyla birlikte son tamamlama yanıtı (status:"ok"|"error").

Tam protokol belgelerine bakın: Gateway Protokolü.

Operasyonel denetimler

Canlılık

• WS açın ve connect gönderin.
• Anlık görüntüyle birlikte hello-ok yanıtı bekleyin.

Hazır olma

openclaw gateway statusopenclaw channels status --probeopenclaw health

Boşluk kurtarma

Olaylar yeniden oynatılmaz. Sıra boşluklarında, devam etmeden önce durumu (health, system-presence) yenileyin.

Yaygın hata imzaları

Tam tanılama basamakları için Gateway Sorun Giderme sayfasını kullanın.

Güvenlik garantileri

• Gateway protokol istemcileri Gateway kullanılamadığında hızlı başarısız olur (örtük doğrudan kanal yedeği yoktur).
• Geçersiz/bağlantı olmayan ilk frame'ler reddedilir ve kapatılır.
• Zarif kapatma, soket kapanmadan önce shutdown olayı yayar.

İlgili:

• Sorun Giderme
• Arka Plan Süreci
• Yapılandırma
• Sağlık
• Doctor
• Kimlik Doğrulama

İlgili

• Yapılandırma
• Gateway sorun giderme
• Uzaktan erişim
• Gizli bilgiler yönetimi