Gateway operasyon kılavuzu

Bu sayfayı Gateway hizmetinin ilk gün başlatılması ve sonraki günlerde işletilmesi için kullanın.

5 dakikada yerel başlatma

openclaw gateway --port 18789# hata ayıklama/izleme stdio'ya yansıtılıropenclaw gateway --port 18789 --verbose# seçili porttaki dinleyiciyi zorla sonlandırın, ardından başlatınopenclaw 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 sürekli çalışan tek süreç.
• Şunlar için çoklanmış tek port:
  • WebSocket denetimi/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 Arayüzü ve kancalar
• Varsayılan bağlama modu: loopback. Algılanan bir konteyner ortamında geçerli varsayılan auto olur (port yönlendirme için 0.0.0.0 olarak çözümlenir); ancak Tailscale sunma/tünelleme etkinse her zaman loopback kullanılması zorlanır.
• Kimlik doğrulama varsayılan olarak zorunludur. Paylaşılan gizli bilgi kurulumları gateway.auth.token / gateway.auth.password (veya OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD) kullanır; döngüsel olmayan ters proxy kurulumları ise gateway.auth.mode: "trusted-proxy" kullanabilir.

OpenAI uyumlu uç noktalar

OpenClaw'ın en yüksek etkili uyumluluk yüzeyi:

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

Bu kümenin önemli olmasının nedenleri:

• Open WebUI, LobeChat ve LibreChat entegrasyonlarının çoğu önce /v1/models yoklaması yapar.
• Birçok RAG ve bellek işlem hattı /v1/embeddings bekler.
• Ajan odaklı istemciler giderek daha fazla /v1/responses tercih etmektedir.

/v1/models öncelikle ajanlara yöneliktir: yapılandırılan her ajan için openclaw, openclaw/default ve openclaw/<agentId> döndürür. openclaw/default, her zaman yapılandırılmış varsayılan ajanla eşlenen kararlı takma addır. Arka uç sağlayıcısını/modelini geçersiz kılmak istediğinizde x-openclaw-model gönderin; aksi takdirde seçili ajanın normal modeli ve gömme kurulumu denetimi elinde tutar.

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'si (POST /api/v1/admin/rpc), WebSocket RPC kullanamayan ana makine araçları için ayrı ve varsayılan olarak kapalı bir Plugin rotasıdır. Bkz. Yönetici HTTP RPC'si.

Port ve bağlama önceliği

Kurulu Gateway hizmetleri, çözümlenen --port değerini gözetmen meta verilerine kaydeder. gateway.port değerini değiştirdikten sonra launchd/systemd/schtasks'in süreci yeni portta başlatması için openclaw doctor --fix veya openclaw gateway install --force çalıştırın.

Gateway başlatılırken, döngüsel olmayan bağlamalar için yerel Denetim Arayüzü kaynakları oluşturulurken aynı etkin port ve bağlama kullanılı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 değerlerini oluşturur. HTTPS proxy URL'leri gibi tüm uzak tarayıcı kaynaklarını gateway.controlUi.allowedOrigins öğesine açıkça ekleyin.

Çalışırken yeniden yükleme modları

Operatör komut kümesi

openclaw gateway statusopenclaw gateway status --deep   # sistem düzeyinde hizmet taraması ekleropenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

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

Birden fazla Gateway (aynı ana makine)

Çoğu kurulum, makine başına bir Gateway çalıştırmalıdır. Tek bir Gateway birden fazla ajanı ve kanalı barındırabilir. Yalnızca bilinçli olarak yalıtım veya bir kurtarma botu istediğinizde birden fazla Gateway'e ihtiyacınız vardır.

Yararlı kontroller:

openclaw gateway status --deepopenclaw gateway probe

Beklenecekler:

• gateway status --deep, eski launchd/systemd/schtasks kurulumları hâlâ mevcutsa Other gateway-like services detected (best effort) bildirebilir ve temizleme 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 hakkında uyarabilir. Aynı Gateway'e yönelik bir SSH tüneli, proxy URL'si veya yapılandırılmış uzak URL, aktarım portları farklı olsa bile birden fazla aktarıma sahip tek bir Gateway'dir.
• Bu bilinçliyse her Gateway için portları, yapılandırmayı/durumu ve çalışma alanı köklerini yalıtın.

Örnek başına kontrol 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. Alternatif: SSH tüneli.

ssh -N -L 18789:127.0.0.1:18789 user@gateway-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 $(whoami)

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=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

Geçersiz yapılandırma hataları 78 koduyla çıkar. Linux systemd birimleri, yapılandırma düzeltilene kadar yeniden başlatmayı durdurmak için RestartPreventExitStatus=78 kullanır. launchd ve Windows Görev Zamanlayıcı'da çıkış koduna göre durdurmaya yönelik eşdeğer bir kural bulunmadığından Gateway ayrıca hızlı ve temiz olmayan önyükleme geçmişini kalıcı olarak saklar ve yinelenen başlatma hatalarından sonra kanal/sağlayıcı hesaplarının otomatik başlatılmasını engeller. Bu güvenli modda denetim düzlemi inceleme ve onarım için çalışmaya devam eder; yapılandırmanın çalışırken yeniden yüklenmesi ve secrets.reload, kanalların otomatik yeniden başlatılmasını reddeder ve operatörün açık bir channels.start isteği engellemeyi geçersiz kılabilir.

Geliştirme profili için hızlı yol

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

Varsayılanlar, yalıtılmış durum/yapılandırmayı ve 19001 temel Gateway portunu içerir.

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

• İlk istemci çerçevesi connect olmalıdır.
• Gateway, bir snapshot (presence, health, stateVersion, uptimeMs) ve policy sınırları (maxPayload, maxBufferedBytes, tickIntervalMs) içeren bir hello-ok çerçevesi döndürür.
• hello-ok.features.methods / events, çağrılabilir tüm yardımcı rotaların oluşturulmuş bir dökümü değil, ölçülü 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, isteğe bağlı session.approval, sessions.changed, presence, tick, health, heartbeat, eşleştirme/onay yaşam döngüsü olayları ve shutdown bulunur.

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

1. Anında kabul bildirimi (status:"accepted")
2. Arada akışla iletilen agent olaylarıyla birlikte nihai tamamlanma yanıtı (status:"ok"|"error").

Protokol belgelerinin tamamına bakın: Gateway Protokolü.

İşletim denetimleri

Canlılık

• WS bağlantısını açın ve connect gönderin.
• Anlık görüntüyü içeren hello-ok yanıtını bekleyin.

Hazır olma durumu

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 belirtileri

Tanılama adımlarının tamamı için Gateway Sorun Giderme bölümünü kullanın.

Güvenlik garantileri

• Gateway kullanılamadığında Gateway protokolü istemcileri hızla başarısız olur (örtük doğrudan kanal geri dönüşü yoktur).
• Geçersiz/bağlantı kurma amaçlı olmayan ilk çerçeveler reddedilir ve bağlantı kapatılır.
• Sorunsuz kapatma, soket kapanmadan önce shutdown olayını yayınlar.

İlgili

• Yapılandırma
• Gateway sorun giderme
• Arka plan işlemi
• Sistem durumu
• Doctor
• Kimlik doğrulama
• Uzaktan erişim
• Gizli bilgi yönetimi