Panduan operasional Gateway

Gunakan halaman ini untuk penyiapan awal dan operasi lanjutan layanan Gateway.

Penyiapan lokal dalam 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 yang selalu aktif untuk perutean, bidang kontrol, dan koneksi kanal.
• Satu port termultipleks untuk:
  • Kontrol/RPC WebSocket
  • API HTTP (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Rute HTTP Plugin, seperti /api/v1/admin/rpc opsional
  • UI Kontrol dan hook
• Mode bind default: loopback. Di dalam lingkungan kontainer yang terdeteksi, default efektifnya adalah auto (ditentukan menjadi 0.0.0.0 untuk penerusan port), kecuali serve/funnel Tailscale aktif, yang selalu memaksakan loopback.
• Autentikasi diwajibkan secara default. Penyiapan rahasia bersama menggunakan gateway.auth.token / gateway.auth.password (atau OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), dan penyiapan proksi balik non-loopback dapat menggunakan gateway.auth.mode: "trusted-proxy".

Endpoint yang kompatibel dengan OpenAI

Permukaan kompatibilitas OpenClaw dengan dampak tertinggi:

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

Alasan kumpulan ini penting:

• Sebagian besar integrasi Open WebUI, LobeChat, dan LibreChat memeriksa /v1/models terlebih dahulu.
• Banyak pipeline RAG dan memori mengharapkan /v1/embeddings.
• Klien khusus agen semakin memilih /v1/responses.

/v1/models mengutamakan agen: endpoint ini mengembalikan openclaw, openclaw/default, dan openclaw/<agentId> untuk setiap agen yang dikonfigurasi. openclaw/default adalah alias stabil yang selalu dipetakan ke agen default yang dikonfigurasi. Kirim x-openclaw-model saat Anda menginginkan penggantian penyedia/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 dengan API HTTP Gateway lainnya.

RPC HTTP admin (POST /api/v1/admin/rpc) adalah rute Plugin terpisah yang dinonaktifkan secara default untuk alat host yang tidak dapat menggunakan RPC WebSocket. Lihat RPC HTTP Admin.

Prioritas port dan bind

Layanan gateway yang terpasang mencatat --port yang ditentukan 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.

Penyiapan awal Gateway menggunakan port dan bind efektif yang sama saat mengisi origin UI Kontrol lokal untuk bind non-loopback. Sebagai contoh, --bind lan --port 3000 mengisi http://localhost:3000 dan http://127.0.0.1:3000 sebelum validasi runtime dijalankan. Tambahkan origin browser jarak jauh, seperti URL proksi HTTPS, secara eksplisit ke gateway.controlUi.allowedOrigins.

Mode pemuatan ulang langsung

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 ditujukan untuk penemuan layanan tambahan (LaunchDaemon/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 kanal. Anda hanya memerlukan beberapa gateway jika sengaja menginginkan isolasi atau bot penyelamat.

Pemeriksaan yang berguna:

openclaw gateway status --deepopenclaw gateway probe

Hal yang dapat diharapkan:

• gateway status --deep dapat melaporkan Other gateway-like services detected (best effort) dan mencetak petunjuk pembersihan saat instalasi launchd/systemd/schtasks usang masih ada.
• gateway probe dapat memperingatkan tentang multiple reachable gateway identities saat gateway yang berbeda merespons, atau saat OpenClaw tidak dapat membuktikan bahwa target yang dapat dijangkau adalah gateway yang sama. Tunnel SSH, URL proksi, atau URL jarak jauh yang dikonfigurasi ke gateway yang sama merupakan satu gateway dengan beberapa transportasi, meskipun port transportasinya berbeda.
• Jika hal tersebut disengaja, pisahkan port, konfigurasi/status, dan root ruang kerja untuk setiap gateway.

Daftar periksa 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. Alternatif: tunnel SSH.

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

Kemudian hubungkan klien secara lokal ke ws://127.0.0.1:18789.

Lihat: Gateway Jarak Jauh, Autentikasi, Tailscale.

Supervisi dan siklus hidup layanan

Gunakan proses yang diawasi untuk keandalan 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 $(whoami)

[Unit]Description=Gateway OpenClawAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=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

Kesalahan konfigurasi yang tidak valid keluar dengan kode 78. Unit systemd Linux menggunakan RestartPreventExitStatus=78 untuk menghentikan peluncuran ulang sampai konfigurasi diperbaiki. launchd dan Windows Task Scheduler tidak memiliki aturan penghentian per kode keluar yang setara, sehingga Gateway juga menyimpan riwayat boot tidak bersih yang terjadi cepat dan menekan mulai otomatis akun kanal/penyedia setelah kegagalan penyiapan awal berulang. Dalam mode aman tersebut, bidang kontrol tetap dimulai untuk pemeriksaan dan perbaikan, pemuatan ulang langsung konfigurasi dan secrets.reload menolak mulai ulang kanal secara otomatis, dan permintaan eksplisit operator channels.start dapat menggantikan penekanan tersebut.

Jalur cepat profil pengembangan

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

Nilai default mencakup status/konfigurasi terisolasi dan port gateway dasar 19001.

Referensi cepat protokol (tampilan operator)

• Frame klien pertama harus berupa connect.
• Gateway mengembalikan frame hello-ok dengan snapshot (presence, health, stateVersion, uptimeMs) beserta batas policy (maxPayload, maxBufferedBytes, tickIntervalMs).
• hello-ok.features.methods / events merupakan daftar penemuan konservatif, bukan hasil pencurahan yang dibuat secara otomatis dari setiap rute pembantu yang dapat dipanggil.
• Permintaan: req(method, params) → res(ok/payload|error).
• Peristiwa umum mencakup connect.challenge, agent, chat, session.message, session.operation, session.tool, session.approval yang bersifat opsional, sessions.changed, presence, tick, health, heartbeat, peristiwa siklus hidup pemasangan/persetujuan, dan shutdown.

Proses agen terdiri dari dua tahap:

1. Konfirmasi penerimaan langsung (status:"accepted")
2. Respons penyelesaian akhir (status:"ok"|"error"), dengan peristiwa agent yang dialirkan di antaranya.

Lihat dokumentasi protokol lengkap: Protokol Gateway.

Pemeriksaan operasional

Keaktifan

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

Kesiapan

openclaw gateway statusopenclaw channels status --probeopenclaw health

Pemulihan kesenjangan

Peristiwa tidak diputar ulang. Jika terdapat kesenjangan urutan, segarkan keadaan (health, system-presence) sebelum melanjutkan.

Tanda kegagalan umum

Untuk langkah-langkah diagnosis lengkap, gunakan Pemecahan Masalah Gateway.

Jaminan keamanan

• Klien protokol Gateway langsung gagal saat Gateway tidak tersedia (tanpa fallback saluran langsung implisit).
• Frame pertama yang tidak valid/bukan koneksi ditolak dan ditutup.
• Pematian secara tertib memancarkan peristiwa shutdown sebelum soket ditutup.

Terkait

• Konfigurasi
• Pemecahan masalah Gateway
• Proses latar belakang
• Kesehatan
• Doctor
• Autentikasi
• Akses jarak jauh
• Pengelolaan rahasia