Langsung ke konten utama
Gunakan halaman ini untuk startup hari pertama dan operasi hari kedua layanan Gateway.

Deep troubleshooting

Diagnostik berbasis gejala dengan urutan perintah persis dan signature log.

Configuration

Panduan penyiapan berorientasi tugas + referensi konfigurasi lengkap.

Secrets management

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

Secrets plan contract

Aturan target/path secrets apply yang persis dan perilaku profil autentikasi hanya-ref.

​
Startup lokal 5 menit

1

Start the Gateway

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
2

Verify service health

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

Validate channel readiness

openclaw channels status --probe
Dengan Gateway yang dapat dijangkau, ini menjalankan probe channel langsung per akun dan audit opsional. Jika Gateway tidak dapat dijangkau, CLI beralih ke ringkasan channel hanya-konfigurasi alih-alih output probe langsung.
Muat ulang konfigurasi Gateway memantau path file konfigurasi aktif (diselesaikan dari default profil/state, atau OPENCLAW_CONFIG_PATH saat disetel). Mode default adalah gateway.reload.mode="hybrid". Setelah pemuatan berhasil pertama, proses yang berjalan menyajikan snapshot konfigurasi dalam memori yang aktif; muat ulang yang berhasil menukar snapshot tersebut secara atomik.

​
Model runtime

  • Satu proses selalu aktif untuk perutean, control plane, dan koneksi channel.
  • 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
    • Control UI 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 yang kompatibel dengan OpenAI

Permukaan kompatibilitas OpenClaw dengan leverage tertinggi sekarang adalah:
  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses
Mengapa 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 native-agent semakin memilih /v1/responses.
Catatan perencanaan:
  • /v1/models mengutamakan agent: endpoint ini mengembalikan openclaw, openclaw/default, dan openclaw/<agentId>.
  • openclaw/default adalah alias stabil yang selalu memetakan ke agent default yang dikonfigurasi.
  • Gunakan x-openclaw-model saat Anda menginginkan override provider/model backend; jika tidak, model normal dan penyiapan embedding agent 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. RPC HTTP admin (POST /api/v1/admin/rpc) adalah rute Plugin terpisah yang nonaktif secara default untuk tooling host yang tidak dapat menggunakan RPC WebSocket. Lihat RPC HTTP Admin.

​
Prioritas port dan bind

PengaturanUrutan resolusi
Port Gateway--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Mode bindCLI/override → gateway.bind → loopback
Layanan Gateway yang terinstal mencatat --port yang terselesaikan 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 mengisi origin Control UI lokal untuk bind non-loopback. Misalnya, --bind lan --port 3000 mengisi 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

gateway.reload.modePerilaku
offTidak ada muat ulang konfigurasi
hotTerapkan hanya perubahan yang aman-hot
restartMulai ulang pada perubahan yang memerlukan muat ulang
hybrid (default)Terapkan-hot saat aman, mulai ulang saat diperlukan

​
Kumpulan 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/unit sistem systemd/schtasks), bukan probe kesehatan RPC yang lebih dalam.

​
Beberapa Gateway (host yang sama)

Sebagian besar instalasi sebaiknya menjalankan satu Gateway per mesin. Satu Gateway dapat meng-host beberapa agent dan channel. Anda hanya memerlukan beberapa Gateway saat Anda sengaja menginginkan isolasi atau bot penyelamat. Pemeriksaan berguna: 
openclaw gateway status --deep
openclaw 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 lama masih ada.
  • gateway probe dapat memperingatkan tentang multiple reachable gateway identities saat Gateway yang berbeda menjawab, atau saat OpenClaw tidak dapat membuktikan target yang dapat dijangkau adalah Gateway yang sama. Tunnel SSH, URL proxy, atau URL jarak jauh yang dikonfigurasi ke Gateway yang sama adalah satu Gateway dengan beberapa transport, meskipun port transport berbeda.
  • Jika itu disengaja, isolasikan port, konfigurasi/state, dan root workspace per Gateway.
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
Penyiapan mendetail: /gateway/multiple-gateways.

​
Akses jarak jauh

Direkomendasikan: 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.
Tunnel SSH tidak melewati autentikasi Gateway. Untuk autentikasi shared-secret, 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. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
Gunakan openclaw gateway restart untuk mulai ulang. Jangan merangkai openclaw gateway stop dan openclaw gateway start sebagai pengganti mulai ulang.Di macOS, gateway stop menggunakan launchctl bootout secara default — ini menghapus LaunchAgent dari sesi boot saat ini tanpa mempertahankan penonaktifan, sehingga pemulihan otomatis KeepAlive tetap berfungsi setelah crash tak terduga dan gateway start mengaktifkan ulang dengan bersih. Untuk menekan auto-respawn secara permanen lintas reboot, berikan --disable: openclaw gateway stop --disable.Label LaunchAgent adalah ai.openclaw.gateway (default) atau ai.openclaw.<profile> (profil bernama). openclaw doctor mengaudit dan memperbaiki drift konfigurasi layanan.

​
Jalur cepat profil dev

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
Default mencakup state/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, limit/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.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, event siklus hidup pairing/approval, dan shutdown.
Run agent memiliki 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. Pada gap sequence, segarkan state (health, system-presence) sebelum melanjutkan.

​
Signature kegagalan umum

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

​
Jaminan keamanan

  • Klien protokol Gateway gagal cepat saat Gateway tidak tersedia (tidak ada fallback direct-channel implisit).
  • Frame pertama yang tidak valid/tidak terhubung ditolak dan ditutup.
  • Shutdown anggun memancarkan peristiwa shutdown sebelum socket ditutup.
Terkait:

​
Terkait