Gateway operasyon kılavuzu

Gateway hizmetinin 1. gün başlatma ve 2. gün operasyonları için bu sayfayı kullanın.

# 5 dakikalık yerel başlatma

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

openclaw gateway status
openclaw status
openclaw logs --follow

openclaw channels status --probe

# Çalışma zamanı modeli

• Yönlendirme, kontrol düzlemi ve kanal bağlantıları için her zaman açık tek süreç.
• Şunlar için tek çoklanmış port:
  • WebSocket kontrol/RPC
  • HTTP API'leri, OpenAI uyumlu (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Kontrol kullanıcı arayüzü 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'ın 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ümenin neden önemli olduğu:

• Ç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ı/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.

# Port ve bağlama önceliği

Yüklenen gateway hizmetleri çözümlenen --port değerini gözetmen meta verilerine kaydeder. gateway.port değiştirildikten sonra launchd/systemd/schtasks sürecin yeni portta başlaması için openclaw doctor --fix veya openclaw gateway install --force çalıştırın.

Gateway başlatması, loopback olmayan bağlamalar için yerel Kontrol UI kökenlerini eklerken 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 ekler. HTTPS proxy URL'leri gibi uzak tarayıcı kökenlerini açıkça gateway.controlUi.allowedOrigins içine ekleyin.

# Sıcak yeniden yükleme modları

# Operatör komut kümesi

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
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 probu değil, ek hizmet keşfi (LaunchDaemons/systemd sistem birimleri/schtasks) içindir.

# Birden çok gateway (aynı host)

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

Yalnızca bilinçli olarak yalıtım veya kurtarma botu istediğinizde birden çok gateway gerekir.

Yararlı kontroller:

openclaw gateway status --deep
openclaw gateway probe

Beklenenler:

• gateway status --deep, eskimiş launchd/systemd/schtasks kurulumları hâlâ mevcut olduğunda Other gateway-like services detected (best effort) bildirebilir ve temizleme ipuçları yazdırabilir.
• gateway probe, birden fazla hedef yanıt verdiğinde multiple reachable gateways hakkında uyarabilir.
• Bu bilinçliyse her gateway için portları, yapılandırma/durum verilerini 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 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

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 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 install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

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

sudo loginctl enable-linger <user>

[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

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

# Geliştirme profili hızlı yolu

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

Varsayılanlar yalıtılmış durum/yapılandırma ve temel gateway portu 19001 içerir.

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

• İlk istemci frame'i connect olmalıdır.
• Gateway hello-ok anlık görüntüsü (presence, health, stateVersion, uptimeMs, limitler/politika) döndürür.
• hello-ok.features.methods / events, çağrılabilir her yardımcı rotanın oluşturulmuş 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.

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

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

Tam protokol belgelerine bakın: Gateway Protokolü.

# Operasyonel kontroller

# 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 status
openclaw channels status --probe
openclaw 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 kullanın.

# Güvenlik garantileri

• Gateway protokol istemcileri, Gateway kullanılamadığında hızla başarısız olur (örtük doğrudan kanal geri dönüşü yoktur).
• Geçersiz/connect olmayan ilk çerçeveler reddedilip kapatılır.
• Zarif kapatma, soket kapanmadan önce shutdown olayını 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 bilgi yönetimi