Gateway runbook

Bu sayfayı Gateway hizmetinin ilk gün kurulumu ve sonraki operasyonları için kullanın.

Derin sorun giderme

Belirti odaklı tanılama, tam komut sıraları ve günlük imzalarıyla birlikte.

Yapılandırma

Görev odaklı kurulum kılavuzu + tam yapılandırma başvurusu.

Gizli değer yönetimi

SecretRef sözleşmesi, çalışma zamanı anlık görüntü davranışı ve taşıma/yeniden yükleme işlemleri.

Gizli değer planı sözleşmesi

Tam secrets apply hedef/yol kuralları ve yalnızca ref kullanan auth-profile davranışı.

5 dakikada yerel başlangıç

Gateway'i başlatın

openclaw gateway --port 18789
# stdio'ya yansıtılmış debug/trace
openclaw gateway --port 18789 --verbose
# seçilen bağlantı noktasındaki dinleyiciyi zorla sonlandır, sonra başlat
openclaw gateway --force

Hizmet sağlığını doğrulayın

openclaw gateway status
openclaw status
openclaw logs --follow

Sağlıklı temel durum: Runtime: running ve RPC probe: ok.

Kanal hazır olma durumunu doğrulayın

openclaw channels status --probe

Erişilebilir bir gateway ile bu komut, hesap başına canlı kanal yoklamalarını ve isteğe bağlı denetimleri çalıştırır. Gateway’e erişilemiyorsa, CLI canlı yoklama çıktısı yerine yalnızca yapılandırma tabanlı kanal özetlerine geri döner.

Gateway yapılandırma yeniden yüklemesi etkin yapılandırma dosyası yolunu izler (profil/durum varsayılanlarından çözülür veya ayarlanmışsa OPENCLAW_CONFIG_PATH kullanılır). Varsayılan mod gateway.reload.mode="hybrid" şeklindedir. İlk başarılı yüklemeden sonra çalışan süreç etkin bellek içi yapılandırma anlık görüntüsünü sunar; başarılı bir yeniden yükleme bu anlık görüntüyü atomik olarak değiştirir.

Çalışma zamanı modeli

Yönlendirme, kontrol düzlemi ve kanal bağlantıları için her zaman açık tek süreç.
Aşağıdakiler için tek çoklanmış bağlantı noktası:
- WebSocket denetim/RPC
- HTTP API’leri, OpenAI uyumlu (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
- Kontrol UI’si ve hook’lar
Varsayılan bind modu: loopback.
Kimlik doğrulama varsayılan olarak gereklidir. Paylaşılan gizli değer kurulumları gateway.auth.token / gateway.auth.password (veya OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD) kullanır ve loopback dışı reverse-proxy kurulumları gateway.auth.mode: "trusted-proxy" kullanabilir.

OpenAI uyumlu uç noktalar

OpenClaw’ın en yüksek etkili 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ümenin neden önemli olduğu:

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 çok /v1/responses tercih ediyor.

Planlama notu:

/v1/models ajan odaklıdır: openclaw, openclaw/default ve openclaw/<agentId> döndürür.
openclaw/default, her zaman yapılandırılmış varsayılan ajana eşlenen kararlı takma addır.
Bir arka uç sağlayıcı/model geçersiz kılması istediğinizde x-openclaw-model kullanın; aksi takdirde seçilen ajanın normal model ve embedding kurulumu denetimde kalır.

Bunların tümü ana Gateway bağlantı noktasında çalışır ve Gateway HTTP API’sinin geri kalanıyla aynı güvenilen operatör auth sınırını kullanır.

Bağlantı noktası ve bind önceliği

Ayar	Çözümleme sırası
Gateway portu	`--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789`
Bind modu	CLI/override → `gateway.bind` → `loopback`

Anında yeniden yükleme modları

`gateway.reload.mode`	Davranış
`off`	Yapılandırma yeniden yüklemesi yok
`hot`	Yalnızca anında uygulanması güvenli değişiklikleri uygula
`restart`	Yeniden yükleme gerektiren değişikliklerde yeniden başlat
`hybrid` (varsayılan)	Güvenliyse anında uygula, gerekirse yeniden başlat

Operatör komut kümesi

openclaw gateway status
openclaw gateway status --deep   # sistem düzeyi hizmet taraması ekler
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

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

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 kurtarma botu istiyorsanız birden fazla gateway gerekir. Yararlı kontroller:

openclaw gateway status --deep
openclaw gateway probe

Beklenmesi gerekenler:

gateway status --deep, Other gateway-like services detected (best effort) bildirebilir ve eski launchd/systemd/schtasks kurulumları hâlâ mevcutsa temizleme ipuçları yazdırabilir.
gateway probe, birden fazla hedef yanıt verdiğinde multiple reachable gateways uyarısı verebilir.
Bu kasıtlıysa, gateway başına bağlantı noktalarını, yapılandırma/durum ve çalışma alanı köklerini yalıtın.

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

Uzak 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 yerelde ws://127.0.0.1:18789 adresine bağlayın.

SSH tünelleri gateway auth’u atlatmaz. Paylaşılan gizli değer auth için istemciler tünel üzerinden bile hâlâ token/password göndermelidir. Kimlik taşıyan modlarda, isteğin yine de o auth yolunu sağlaması gerekir.

Bkz.: Remote Gateway, Authentication, Tailscale.

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

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

macOS (launchd)
Linux (systemd kullanıcısı)
Windows (yerel)
Linux (sistem hizmeti)

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

LaunchAgent etiketleri ai.openclaw.gateway (varsayılan) veya ai.openclaw.<profile> (adlandırılmış profil) şeklindedir. openclaw doctor, hizmet yapılandırma kaymasını denetler ve onarır.

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

Çıkış yaptıktan sonra da kalıcılık için lingering etkinleştirin:

sudo loginctl enable-linger <user>

Özel bir kurulum yoluna ihtiyacınız olduğunda el ile kullanıcı birimi örneği:

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

Yerel Windows yönetilen başlangıcı, OpenClaw Gateway (adlandırılmış profiller için OpenClaw Gateway (<profile>)) adlı bir Scheduled Task kullanır. Scheduled Task oluşturma reddedilirse, OpenClaw durum dizini içindeki gateway.cmd dosyasını işaret eden kullanıcı başına Startup-folder başlatıcısına geri döner.

Çok kullanıcılı/her zaman açık ana makineler için sistem birimi kullanın.

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

Kullanıcı birimiyle aynı hizmet gövdesini kullanın, ancak bunu /etc/systemd/system/openclaw-gateway[-<profile>].service altına kurun ve openclaw ikiliniz başka bir yerdeyse ExecStart= değerini ayarlayın.

Tek ana makinede birden fazla gateway

Çoğu kurulum tek bir Gateway çalıştırmalıdır. Birden fazlasını yalnızca katı yalıtım/yedeklilik için kullanın (örneğin bir kurtarma profili). Her örnek için 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 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

Bkz.: Multiple gateways.

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

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

Varsayılanlara yalıtılmış durum/yapılandırma ve temel gateway bağlantı noktası 19001 dahildir.

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

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

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

Anında kabul onayı (status:"accepted")
Arada akışlı agent olaylarıyla birlikte son tamamlanma yanıtı (status:"ok"|"error").

Tam protokol belgeleri için bkz.: Gateway Protocol.

Operasyonel kontroller

Liveness

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

Hazır olma

openclaw gateway status
openclaw channels status --probe
openclaw health

Boşluk kurtarma

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

Yaygın hata imzaları

İmza	Olası sorun
`refusing to bind gateway ... without auth`	Geçerli bir gateway auth yolu olmadan loopback dışı bind
`another gateway instance is already listening` / `EADDRINUSE`	Bağlantı noktası çakışması
`Gateway start blocked: set gateway.mode=local`	Yapılandırma uzak moda ayarlı veya hasarlı yapılandırmada yerel mod damgası eksik
`unauthorized` during connect	İstemci ile gateway arasında auth uyuşmazlığı

Tam tanılama sıraları için Gateway Troubleshooting kullanın.

Güvenlik garantileri

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

İlgili:

Gateway

Remote access

Security

Nodes and media

Web interfaces

Gateway Runbook

Gateway runbook

Derin sorun giderme

Yapılandırma

Gizli değer yönetimi

Gizli değer planı sözleşmesi

5 dakikada yerel başlangıç

Çalışma zamanı modeli

OpenAI uyumlu uç noktalar

Bağlantı noktası ve bind önceliği

Anında yeniden yükleme modları

Operatör komut kümesi

Birden fazla gateway (aynı ana makine)

Uzak erişim

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

Tek ana makinede birden fazla gateway

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

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

Operasyonel kontroller

Liveness

Hazır olma

Boşluk kurtarma

Yaygın hata imzaları

Güvenlik garantileri

Gateway

Remote access

Security

Nodes and media

Web interfaces

​Gateway runbook

Derin sorun giderme

Yapılandırma

Gizli değer yönetimi

Gizli değer planı sözleşmesi

​5 dakikada yerel başlangıç

​Çalışma zamanı modeli

​OpenAI uyumlu uç noktalar

​Bağlantı noktası ve bind önceliği

​Anında yeniden yükleme modları

​Operatör komut kümesi

​Birden fazla gateway (aynı ana makine)

​Uzak erişim

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

​Tek ana makinede birden fazla gateway

​Geliştirici profili için hızlı yol

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

​Operasyonel kontroller

​Liveness

​Hazır olma

​Boşluk kurtarma

​Yaygın hata imzaları

​Güvenlik garantileri

Gateway runbook

5 dakikada yerel başlangıç

Çalışma zamanı modeli

OpenAI uyumlu uç noktalar

Bağlantı noktası ve bind önceliği

Anında yeniden yükleme modları

Operatör komut kümesi

Birden fazla gateway (aynı ana makine)

Uzak erişim

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

Tek ana makinede birden fazla gateway

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

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

Operasyonel kontroller

Liveness

Hazır olma

Boşluk kurtarma

Yaygın hata imzaları

Güvenlik garantileri