Langsung ke konten utama

​
Runbook Gateway

Gunakan halaman ini untuk startup hari pertama dan operasi hari kedua dari layanan Gateway.

Pemecahan masalah mendalam

Diagnostik berbasis gejala dengan urutan perintah yang tepat dan signature log.

Konfigurasi

Panduan penyiapan berorientasi tugas + referensi konfigurasi lengkap.

Manajemen secret

Kontrak SecretRef, perilaku snapshot runtime, dan operasi migrasi/muat ulang.

Kontrak rencana secret

Aturan target/path secrets apply yang tepat dan perilaku auth-profile hanya-ref.

​
Startup lokal 5 menit

1

Mulai Gateway

openclaw gateway --port 18789
# debug/trace dicerminkan ke stdio
openclaw gateway --port 18789 --verbose
# paksa matikan listener pada port yang dipilih, lalu mulai
openclaw gateway --force
2

Verifikasi kesehatan layanan

openclaw gateway status
openclaw status
openclaw logs --follow
Baseline sehat: Runtime: running, Connectivity probe: ok, dan Capability: ... yang sesuai dengan yang Anda harapkan. Gunakan openclaw gateway status --require-rpc saat Anda memerlukan bukti RPC cakupan baca, bukan sekadar keterjangkauan.
3

Validasi kesiapan channel

openclaw channels status --probe
Dengan gateway yang dapat dijangkau, ini menjalankan probe channel per-akun secara live dan audit opsional. Jika gateway tidak dapat dijangkau, CLI akan kembali ke ringkasan channel berbasis konfigurasi saja alih-alih output probe live.
Reload konfigurasi Gateway memantau path file konfigurasi aktif (di-resolve dari default profile/state, atau OPENCLAW_CONFIG_PATH jika disetel). Mode default adalah gateway.reload.mode="hybrid". Setelah pemuatan berhasil pertama, proses yang berjalan menyajikan snapshot konfigurasi aktif di memori; reload yang berhasil menukar snapshot tersebut secara atomik.

​
Model runtime

  • Satu proses yang selalu aktif untuk routing, control plane, dan koneksi channel.
  • Satu port termultipleks untuk:
    • WebSocket control/RPC
    • HTTP API, kompatibel OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • Control UI dan hook
  • Mode bind default: loopback.
  • Auth diwajibkan secara default. Penyiapan shared-secret menggunakan gateway.auth.token / gateway.auth.password (atau OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), dan penyiapan reverse-proxy non-loopback dapat menggunakan gateway.auth.mode: "trusted-proxy".

​
Endpoint kompatibel OpenAI

Surface kompatibilitas dengan leverage tertinggi OpenClaw saat ini adalah:
  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses
Mengapa set ini penting:
  • Sebagian besar integrasi Open WebUI, LobeChat, dan LibreChat melakukan probe ke /v1/models terlebih dahulu.
  • Banyak pipeline RAG dan memori mengharapkan /v1/embeddings.
  • Klien native agent semakin memilih /v1/responses.
Catatan perencanaan:
  • /v1/models bersifat agent-first: endpoint ini mengembalikan openclaw, openclaw/default, dan openclaw/<agentId>.
  • openclaw/default adalah alias stabil yang selalu dipetakan ke agent default yang dikonfigurasi.
  • Gunakan x-openclaw-model saat Anda menginginkan override provider/model backend; jika tidak, pengaturan model dan embedding normal milik agent yang dipilih tetap mengendalikan.
Semua ini berjalan pada port utama Gateway dan menggunakan batas auth operator tepercaya yang sama seperti bagian lain dari HTTP API Gateway.

​
Prioritas port dan bind

SettingUrutan resolusi
Port Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Mode bindCLI/override → gateway.bind → loopback

​
Mode hot reload

gateway.reload.modePerilaku
offTidak ada reload konfigurasi
hotTerapkan hanya perubahan yang aman-hot
restartRestart pada perubahan yang memerlukan reload
hybrid (default)Terapkan secara hot saat aman, restart saat diperlukan

​
Set perintah operator

openclaw gateway status
openclaw gateway status --deep   # menambahkan pemindaian layanan tingkat sistem
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor
gateway status --deep digunakan untuk penemuan layanan tambahan (unit LaunchDaemons/systemd system/schtasks), bukan probe kesehatan RPC yang lebih mendalam.

​
Beberapa gateway (host yang sama)

Sebagian besar instalasi sebaiknya menjalankan satu gateway per mesin. Satu gateway dapat menampung beberapa agent dan channel. Anda hanya memerlukan beberapa gateway saat Anda sengaja menginginkan isolasi atau rescue bot. Pemeriksaan yang berguna: 
openclaw gateway status --deep
openclaw gateway probe
Yang diharapkan:
  • gateway status --deep dapat melaporkan Other gateway-like services detected (best effort) dan menampilkan petunjuk pembersihan saat instalasi launchd/systemd/schtasks lama masih ada.
  • gateway probe dapat memperingatkan tentang multiple reachable gateways saat lebih dari satu target merespons.
  • Jika itu memang disengaja, isolasikan root port, config/state, dan workspace untuk tiap gateway.
Penyiapan terperinci: /gateway/multiple-gateways.

​
Akses jarak jauh

Yang disarankan: Tailscale/VPN. Cadangan: tunnel SSH. 
ssh -N -L 18789:127.0.0.1:18789 user@host
Lalu hubungkan klien secara lokal ke ws://127.0.0.1:18789.
Tunnel SSH tidak melewati auth gateway. Untuk auth shared-secret, klien tetap harus mengirim token/password bahkan melalui tunnel. Untuk mode yang membawa identitas, permintaan tetap harus memenuhi jalur auth tersebut.
Lihat: Gateway Jarak Jauh, Autentikasi, Tailscale.

​
Supervisi dan siklus hidup layanan

Gunakan proses yang disupervisi untuk keandalan yang menyerupai produksi. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
Label LaunchAgent adalah ai.openclaw.gateway (default) atau ai.openclaw.<profile> (profile bernama). openclaw doctor mengaudit dan memperbaiki drift konfigurasi layanan.

​
Beberapa gateway pada satu host

Sebagian besar penyiapan sebaiknya menjalankan satu Gateway. Gunakan beberapa hanya untuk isolasi/redundansi ketat (misalnya profile rescue). Checklist per instance:
  • gateway.port unik
  • OPENCLAW_CONFIG_PATH unik
  • OPENCLAW_STATE_DIR unik
  • agents.defaults.workspace unik
Contoh: 
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
Lihat: Beberapa gateway.

​
Jalur cepat profile dev

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
Default mencakup state/config yang terisolasi dan port dasar gateway 19001.

​
Referensi cepat protokol (tampilan operator)

  • Frame klien pertama harus berupa connect.
  • Gateway mengembalikan snapshot hello-ok (presence, health, stateVersion, uptimeMs, limits/policy).
  • hello-ok.features.methods / events adalah daftar discovery konservatif, bukan dump yang dihasilkan dari setiap helper route yang dapat dipanggil.
  • Request: req(method, params) → res(ok/payload|error).
  • Event umum mencakup connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, event siklus hidup pairing/approval, dan shutdown.
Run agent terdiri dari dua tahap:
  1. Ack penerimaan langsung (status:"accepted")
  2. Respons penyelesaian akhir (status:"ok"|"error"), dengan event agent yang di-stream di antaranya.
Lihat dokumentasi protokol lengkap: Protokol Gateway.

​
Pemeriksaan operasional

​
Liveness

  • Buka WS dan kirim connect.
  • Harapkan respons hello-ok dengan snapshot.

​
Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

​
Pemulihan gap

Event tidak diputar ulang. Pada gap sequence, segarkan state (health, system-presence) sebelum melanjutkan.

​
Signature kegagalan umum

SignatureKemungkinan masalah
refusing to bind gateway ... without authBind non-loopback tanpa jalur auth gateway yang valid
another gateway instance is already listening / EADDRINUSEKonflik port
Gateway start blocked: set gateway.mode=localKonfigurasi disetel ke mode remote, atau stamp mode lokal hilang dari konfigurasi yang rusak
unauthorized during connectKetidakcocokan auth antara klien dan gateway
Untuk urutan diagnosis lengkap, gunakan Pemecahan Masalah Gateway.

​
Jaminan keamanan

  • Klien protokol Gateway gagal cepat saat Gateway tidak tersedia (tanpa fallback direct-channel implisit).
  • Frame pertama yang tidak valid/bukan-connect ditolak dan koneksi ditutup.
  • Shutdown graceful mengirim event shutdown sebelum socket ditutup.
Terkait: