Panduan operasional Gateway

Gunakan halaman ini untuk startup hari ke-1 dan operasi hari ke-2 layanan Gateway.

Startup lokal 5 menit

openclaw gateway --port 18789# debug/trace dicerminkan ke stdioopenclaw gateway --port 18789 --verbose# hentikan paksa listener pada port yang dipilih, lalu mulaiopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

Model runtime

• Satu proses selalu aktif untuk routing, control plane, dan koneksi channel.
• Satu port multipleks untuk:
  • Kontrol/RPC WebSocket
  • API HTTP, kompatibel OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • UI kontrol dan hook
• Mode bind default: loopback.
• Autentikasi 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

Permukaan kompatibilitas OpenClaw dengan dampak tertinggi sekarang adalah:

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

Mengapa rangkaian ini penting:

• Sebagian besar integrasi Open WebUI, LobeChat, dan LibreChat mem-probe /v1/models terlebih dahulu.
• Banyak pipeline RAG dan memori mengharapkan /v1/embeddings.
• Klien agent-native semakin memilih /v1/responses.

Catatan perencanaan:

• /v1/models mengutamakan agen: endpoint ini mengembalikan openclaw, openclaw/default, dan openclaw/<agentId>.
• openclaw/default adalah alias stabil yang selalu dipetakan ke agen default yang dikonfigurasi.
• Gunakan x-openclaw-model saat Anda menginginkan override provider/model backend; jika tidak, model normal dan penyiapan embedding agen yang dipilih tetap memegang kendali.

Semua ini berjalan pada port Gateway utama dan menggunakan batas autentikasi operator tepercaya yang sama seperti API HTTP Gateway lainnya.

Prioritas port dan bind

Layanan gateway yang diinstal mencatat --port yang diselesaikan dalam metadata supervisor. Setelah mengubah gateway.port, jalankan openclaw doctor --fix atau openclaw gateway install --force agar launchd/systemd/schtasks memulai proses pada port baru.

Startup Gateway menggunakan port dan bind efektif yang sama saat menyemai origin UI Kontrol lokal untuk bind non-loopback. Misalnya, --bind lan --port 3000 menyemai http://localhost:3000 dan http://127.0.0.1:3000 sebelum validasi runtime berjalan. Tambahkan origin browser jarak jauh apa pun, seperti URL proxy HTTPS, ke gateway.controlUi.allowedOrigins secara eksplisit.

Mode hot reload

Kumpulan perintah operator

openclaw gateway statusopenclaw gateway status --deep   # menambahkan pemindaian layanan tingkat sistemopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep adalah untuk penemuan layanan tambahan (LaunchDaemons/unit sistem systemd/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 agen dan channel.

Anda hanya membutuhkan beberapa gateway saat sengaja menginginkan isolasi atau bot penyelamat.

Pemeriksaan berguna:

openclaw gateway status --deepopenclaw gateway probe

Yang perlu diharapkan:

• gateway status --deep dapat melaporkan Other gateway-like services detected (best effort) dan mencetak petunjuk pembersihan saat instalasi launchd/systemd/schtasks yang usang masih ada.
• gateway probe dapat memperingatkan tentang multiple reachable gateways saat lebih dari satu target menjawab.
• Jika itu disengaja, isolasikan port, konfigurasi/state, dan root workspace per gateway.

Checklist per instans:

• 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 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

Penyiapan terperinci: /gateway/multiple-gateways.

Akses jarak jauh

Disarankan: Tailscale/VPN. Fallback: 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.

Lihat: Gateway Jarak Jauh, Autentikasi, Tailscale.

Supervisi dan siklus hidup layanan

Gunakan run yang diawasi untuk reliabilitas seperti produksi.

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 143KillMode=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

Jalur cepat profil dev

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

Default mencakup state/konfigurasi terisolasi dan port gateway dasar 19001.

Referensi cepat protokol (tampilan operator)

• Frame klien pertama harus berupa connect.
• Gateway mengembalikan snapshot hello-ok (presence, health, stateVersion, uptimeMs, batas/kebijakan).
• hello-ok.features.methods / events adalah daftar penemuan konservatif, bukan dump yang dihasilkan dari setiap rute helper yang dapat dipanggil.
• Permintaan: 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 agen terdiri dari dua tahap:

1. Ack diterima segera (status:"accepted")
2. Respons penyelesaian final (status:"ok"|"error"), dengan event agent yang di-stream di antaranya.

Lihat dokumen protokol lengkap: Protokol Gateway.

Pemeriksaan operasional

Liveness

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

Readiness

openclaw gateway statusopenclaw channels status --probeopenclaw health

Pemulihan gap

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

Tanda tangan kegagalan umum

Untuk tangga diagnosis lengkap, gunakan Pemecahan Masalah Gateway.

Jaminan keamanan

• Klien protokol Gateway gagal cepat saat Gateway tidak tersedia (tanpa fallback saluran langsung implisit).
• Frame pertama yang tidak valid/tidak tersambung ditolak dan ditutup.
• Shutdown yang anggun memancarkan event shutdown sebelum socket ditutup.

Terkait:

• Pemecahan Masalah
• Proses Latar Belakang
• Konfigurasi
• Kesehatan
• Doctor
• Autentikasi

Terkait

• Konfigurasi
• Pemecahan masalah Gateway
• Akses jarak jauh
• Manajemen rahasia