Skip to main content
Gunakan halaman ini untuk penyiapan awal dan operasi lanjutan layanan Gateway.

Pemecahan masalah mendalam

Diagnostik berbasis gejala dengan urutan perintah yang tepat dan ciri khas log.

Konfigurasi

Panduan penyiapan berorientasi tugas + referensi konfigurasi lengkap.

Pengelolaan rahasia

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

Kontrak rencana rahasia

Aturan target/jalur secrets apply yang tepat dan perilaku profil autentikasi khusus referensi.

​
Penyiapan lokal dalam 5 menit

1

Mulai Gateway

2

Verifikasi kesehatan layanan

Tolok ukur sehat: Runtime: running, Connectivity probe: ok, dan baris Capability yang sesuai dengan harapan Anda. Gunakan openclaw gateway status --require-rpc sebagai bukti RPC cakupan baca, bukan sekadar keterjangkauan.
3

Validasi kesiapan kanal

Dengan gateway yang dapat dijangkau, perintah ini menjalankan probe kanal langsung per akun dan audit opsional. Jika gateway tidak dapat dijangkau, CLI beralih ke ringkasan kanal berbasis konfigurasi saja.
Pemuatan ulang konfigurasi Gateway memantau jalur berkas konfigurasi aktif (ditentukan dari nilai default profil/status, atau OPENCLAW_CONFIG_PATH jika ditetapkan). Mode default adalah gateway.reload.mode="hybrid". Setelah pemuatan pertama berhasil, proses yang berjalan menyajikan snapshot konfigurasi aktif dalam memori; pemuatan ulang yang berhasil menukar snapshot tersebut secara atomik.

​
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

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:
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:
Penyiapan terperinci: /gateway/multiple-gateways.

​
Akses jarak jauh

Disarankan: Tailscale/VPN. Alternatif: tunnel SSH.
Kemudian hubungkan klien secara lokal ke ws://127.0.0.1:18789.
Tunnel SSH tidak melewati autentikasi gateway. Untuk autentikasi rahasia bersama, klien tetap harus mengirim token/password bahkan melalui tunnel. Untuk mode yang membawa identitas, permintaan tetap harus memenuhi jalur autentikasi tersebut.
Lihat: Gateway Jarak Jauh, Autentikasi, Tailscale.

​
Supervisi dan siklus hidup layanan

Gunakan proses yang diawasi untuk keandalan seperti produksi.
Gunakan openclaw gateway restart untuk memulai ulang. Jangan merangkai openclaw gateway stop dan openclaw gateway start sebagai pengganti mulai ulang.Di macOS, gateway stop menggunakan launchctl bootout secara default. Tindakan ini menghapus LaunchAgent dari sesi boot saat ini tanpa menyimpan status nonaktif, sehingga pemulihan otomatis KeepAlive tetap berfungsi setelah crash tak terduga dan gateway start dapat mengaktifkannya kembali dengan bersih. Untuk terus menekan pemunculan ulang otomatis setelah boot ulang, teruskan --disable: openclaw gateway stop --disable.Label LaunchAgent adalah ai.openclaw.gateway (default) atau ai.openclaw.<profile> (profil bernama). openclaw doctor mengaudit dan memperbaiki penyimpangan konfigurasi layanan.
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

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

​
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