Panduan operasional Gateway

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

# Startup lokal 5 menit

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

# Model runtime

• Satu proses selalu aktif untuk routing, control plane, dan koneksi kanal.
• Satu port multiplexed untuk:
  • Kontrol/RPC WebSocket
  • API HTTP, 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

Permukaan kompatibilitas OpenClaw yang paling berdampak kini 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 memeriksa /v1/models terlebih dahulu.
• Banyak pipeline RAG dan memori mengharapkan /v1/embeddings.
• Klien agent-native makin sering 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 backend provider/model; jika tidak, model normal dan penyiapan embedding milik agen yang dipilih tetap memegang kendali.

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

# Prioritas port dan bind

Layanan gateway terinstal 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 menanam origin Control UI lokal untuk bind non-loopback. Misalnya, --bind lan --port 3000 menanam http://localhost:3000 dan http://127.0.0.1:3000 sebelum validasi runtime berjalan. Tambahkan origin browser jarak jauh apa pun, seperti URL proksi HTTPS, ke gateway.controlUi.allowedOrigins secara eksplisit.

# Mode hot reload

# Set perintah operator

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 digunakan untuk penemuan layanan tambahan (LaunchDaemons/systemd system units/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 menghosting beberapa agen dan kanal.

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

Pemeriksaan yang berguna:

openclaw gateway status --deep
openclaw gateway probe

Yang dapat diharapkan:

• gateway status --deep dapat melaporkan Other gateway-like services detected (best effort) dan mencetak petunjuk pembersihan saat instalasi launchd/systemd/schtasks lama masih ada.
• gateway probe dapat memperingatkan tentang multiple reachable gateways saat lebih dari satu target menjawab.
• Jika itu disengaja, isolasikan port, konfigurasi/status, 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 19001
OPENCLAW_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 eksekusi tersupervisi untuk keandalan seperti produksi.

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

# Jalur cepat profil dev

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

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

# Referensi cepat protokol (tampilan operator)

• Frame klien pertama harus 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 route helper 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 agen terdiri dari dua tahap:

1. Ack diterima langsung (status:"accepted")
2. Respons penyelesaian final (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. Saat ada gap urutan, segarkan status (health, system-presence) sebelum melanjutkan.

# Tanda kegagalan umum

Untuk rangkaian diagnosis lengkap, gunakan Pemecahan Masalah Gateway.

# Jaminan keselamatan

• Klien protokol Gateway gagal cepat saat Gateway tidak tersedia (tidak ada mekanisme pengalihan saluran langsung implisit).
• Frame pertama yang tidak valid/bukan koneksi ditolak dan ditutup.
• Penonaktifan tertib memancarkan peristiwa shutdown sebelum soket ditutup.

Terkait:

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

# Terkait

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