​

UI Kontrol (browser)

• default: http://<host>:18789/
• prefix opsional: tetapkan gateway.controlUi.basePath (misalnya /openclaw)

​

Buka cepat (lokal)

• http://127.0.0.1:18789/ (atau http://localhost:18789/)

• connect.params.auth.token
• connect.params.auth.password
• header identitas Tailscale Serve saat gateway.auth.allowTailscale: true
• header identitas trusted-proxy saat gateway.auth.mode: "trusted-proxy"

​

Pairing perangkat (koneksi pertama)

# Daftar permintaan yang tertunda
openclaw devices list

# Setujui berdasarkan ID permintaan
openclaw devices approve <requestId>

• Koneksi browser loopback lokal langsung (127.0.0.1 / localhost) akan disetujui otomatis.
• Koneksi browser Tailnet dan LAN tetap memerlukan persetujuan eksplisit, bahkan saat berasal dari mesin yang sama.
• Setiap profil browser menghasilkan ID perangkat unik, jadi berpindah browser atau menghapus data browser akan memerlukan pairing ulang.

​

Dukungan bahasa

• Lokal yang didukung: en, zh-CN, zh-TW, pt-BR, de, es
• Terjemahan non-Inggris dimuat secara lazy di browser.
• Lokal yang dipilih disimpan di storage browser dan digunakan kembali pada kunjungan mendatang.
• Key terjemahan yang hilang akan fallback ke bahasa Inggris.

​

Yang dapat dilakukan (saat ini)

• Chat dengan model melalui Gateway WS (chat.history, chat.send, chat.abort, chat.inject)
• Stream panggilan tool + kartu output tool langsung di Chat (peristiwa agen)
• Channel: status channel bawaan plus channel plugin bawaan/eksternal, login QR, dan konfigurasi per channel (channels.status, web.login.*, config.patch)
• Instance: daftar presence + refresh (system-presence)
• Sesi: daftar + override model/thinking/fast/verbose/reasoning per sesi (sessions.list, sessions.patch)
• Pekerjaan cron: daftar/tambah/edit/jalankan/aktifkan/nonaktifkan + riwayat run (cron.*)
• Skills: status, aktifkan/nonaktifkan, instal, pembaruan API key (skills.*)
• Node: daftar + kapabilitas (node.list)
• Persetujuan exec: edit allowlist gateway atau node + kebijakan ask untuk exec host=gateway/node (exec.approvals.*)
• Konfigurasi: lihat/edit ~/.openclaw/openclaw.json (config.get, config.set)
• Konfigurasi: terapkan + mulai ulang dengan validasi (config.apply) dan bangunkan sesi aktif terakhir
• Penulisan konfigurasi menyertakan penjaga base-hash untuk mencegah penimpaan edit yang bersamaan
• Penulisan konfigurasi (config.set/config.apply/config.patch) juga melakukan preflight resolusi SecretRef aktif untuk referensi dalam payload konfigurasi yang dikirim; referensi aktif yang tidak terurai dalam payload yang dikirim ditolak sebelum penulisan
• Skema konfigurasi + perenderan formulir (config.schema / config.schema.lookup, termasuk field title / description, petunjuk UI yang cocok, ringkasan anak langsung, metadata dokumen pada node objek/wildcard/array/composition bertingkat, plus skema plugin + channel saat tersedia); editor JSON Raw hanya tersedia saat snapshot memiliki round-trip raw yang aman
• Jika snapshot tidak dapat melakukan round-trip teks mentah dengan aman, UI Kontrol memaksa mode Form dan menonaktifkan mode Raw untuk snapshot tersebut
• Nilai objek SecretRef terstruktur dirender hanya-baca di input teks formulir untuk mencegah kerusakan tidak sengaja dari objek menjadi string
• Debug: snapshot status/health/models + log peristiwa + panggilan RPC manual (status, health, models.list)
• Log: tail langsung log file gateway dengan filter/ekspor (logs.tail)
• Update: jalankan update package/git + restart (update.run) dengan laporan restart

• Untuk pekerjaan terisolasi, pengiriman default adalah mengumumkan ringkasan. Anda dapat mengubahnya ke none jika ingin run internal saja.
• Field channel/target muncul saat announce dipilih.
• Mode webhook menggunakan delivery.mode = "webhook" dengan delivery.to diatur ke URL webhook HTTP(S) yang valid.
• Untuk pekerjaan sesi utama, mode pengiriman webhook dan none tersedia.
• Kontrol edit lanjutan mencakup delete-after-run, hapus override agen, opsi cron exact/stagger, override model/thinking agen, dan toggle pengiriman best-effort.
• Validasi formulir bersifat inline dengan kesalahan per field; nilai yang tidak valid menonaktifkan tombol simpan sampai diperbaiki.
• Tetapkan cron.webhookToken untuk mengirim token bearer khusus, jika dihilangkan webhook dikirim tanpa header auth.
• Fallback deprecated: pekerjaan lama yang tersimpan dengan notify: true masih dapat menggunakan cron.webhook sampai dimigrasikan.

​

Perilaku chat

• chat.send non-blocking: langsung mengakui dengan { runId, status: "started" } dan respons di-stream melalui peristiwa chat.
• Mengirim ulang dengan idempotencyKey yang sama mengembalikan { status: "in_flight" } saat masih berjalan, dan { status: "ok" } setelah selesai.
• Respons chat.history dibatasi ukurannya demi keamanan UI. Saat entri transkrip terlalu besar, Gateway dapat memotong field teks panjang, menghilangkan blok metadata berat, dan mengganti pesan yang terlalu besar dengan placeholder ([chat.history omitted: message too large]).
• chat.history juga menghapus tag direktif inline khusus tampilan dari teks asisten yang terlihat (misalnya [[reply_to_*]] dan [[audio_as_voice]]), payload XML panggilan tool dalam teks biasa (termasuk <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls>, dan blok panggilan tool yang terpotong), serta menghilangkan token kontrol model ASCII/full-width yang bocor, dan mengabaikan entri asisten yang seluruh teks terlihatnya hanya token senyap persis NO_REPLY / no_reply.
• chat.inject menambahkan catatan asisten ke transkrip sesi dan menyiarkan peristiwa chat untuk pembaruan khusus UI (tanpa run agen, tanpa pengiriman channel).
• Pemilih model dan thinking di header chat langsung mem-patch sesi aktif melalui sessions.patch; ini adalah override sesi yang persisten, bukan opsi pengiriman sekali putaran.
• Stop:
  • Klik Stop (memanggil chat.abort)
  • Ketik /stop (atau frasa abort mandiri seperti stop, stop action, stop run, stop openclaw, please stop) untuk abort di luar band
  • chat.abort mendukung { sessionKey } (tanpa runId) untuk membatalkan semua run aktif untuk sesi tersebut
• Retensi parsial saat abort:
  • Saat run dibatalkan, teks asisten parsial masih dapat ditampilkan di UI
  • Gateway mempersistenkan teks asisten parsial yang dibatalkan ke riwayat transkrip saat output yang dibuffer ada
  • Entri yang dipersistenkan menyertakan metadata abort sehingga konsumen transkrip dapat membedakan parsial abort dari output penyelesaian normal

​

Akses Tailnet (direkomendasikan)

​

Tailscale Serve terintegrasi (disarankan)

openclaw gateway --tailscale serve

• https://<magicdns>/ (atau gateway.controlUi.basePath yang Anda konfigurasi)

​

Bind ke tailnet + token

openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"

• http://<tailscale-ip>:18789/ (atau gateway.controlUi.basePath yang Anda konfigurasi)

​

HTTP tidak aman

• kompatibilitas HTTP tidak aman khusus localhost dengan gateway.controlUi.allowInsecureAuth=true
• autentikasi UI Kontrol operator yang berhasil melalui gateway.auth.mode: "trusted-proxy"
• break-glass gateway.controlUi.dangerouslyDisableDeviceAuth=true

• https://<magicdns>/ (Serve)
• http://127.0.0.1:18789/ (di host gateway)

{
  gateway: {
    controlUi: { allowInsecureAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

• Ini memungkinkan sesi UI Kontrol localhost berlanjut tanpa identitas perangkat dalam konteks HTTP non-aman.
• Ini tidak melewati pemeriksaan pairing.
• Ini tidak melonggarkan persyaratan identitas perangkat jarak jauh (non-localhost).

{
  gateway: {
    controlUi: { dangerouslyDisableDeviceAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

• autentikasi trusted-proxy yang berhasil dapat mengizinkan sesi UI Kontrol operator tanpa identitas perangkat
• ini tidak berlaku untuk sesi UI Kontrol role node
• reverse proxy loopback host yang sama tetap tidak memenuhi autentikasi trusted-proxy; lihat Trusted Proxy Auth

​

Membangun UI

pnpm ui:build # otomatis menginstal dependensi UI saat pertama kali dijalankan

OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

pnpm ui:dev # otomatis menginstal dependensi UI saat pertama kali dijalankan

​

Debugging/testing: server dev + Gateway jarak jauh

1. Jalankan server dev UI: pnpm ui:dev
2. Buka URL seperti:

http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789

http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-token>

• gatewayUrl disimpan di localStorage setelah dimuat dan dihapus dari URL.
• token sebaiknya diteruskan melalui fragmen URL (#token=...) bila memungkinkan. Fragmen tidak dikirim ke server, sehingga menghindari kebocoran log permintaan dan Referer. Parameter query lama ?token= masih diimpor sekali demi kompatibilitas, tetapi hanya sebagai fallback, dan langsung dihapus setelah bootstrap.
• password hanya disimpan di memori.
• Saat gatewayUrl ditetapkan, UI tidak fallback ke konfigurasi atau kredensial lingkungan. Berikan token (atau password) secara eksplisit. Kredensial eksplisit yang tidak ada adalah kesalahan.
• Gunakan wss:// saat Gateway berada di belakang TLS (Tailscale Serve, proxy HTTPS, dll.).
• gatewayUrl hanya diterima di jendela tingkat atas (bukan tertanam) untuk mencegah clickjacking.
• Deployment UI Kontrol non-loopback harus menetapkan gateway.controlUi.allowedOrigins secara eksplisit (origin lengkap). Ini termasuk penyiapan dev jarak jauh.
• Jangan gunakan gateway.controlUi.allowedOrigins: ["*"] kecuali untuk pengujian lokal yang sangat terkontrol. Artinya mengizinkan origin browser apa pun, bukan “cocokkan host apa pun yang sedang saya gunakan.”
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true mengaktifkan mode fallback origin Host-header, tetapi ini adalah mode keamanan yang berbahaya.

{
  gateway: {
    controlUi: {
      allowedOrigins: ["http://localhost:5173"],
    },
  },
}

​

Terkait

• Dashboard — dasbor gateway
• WebChat — antarmuka chat berbasis browser
• TUI — antarmuka pengguna terminal
• Health Checks — pemantauan kesehatan gateway