Pencatatan log

OpenClaw memiliki dua permukaan log utama:

• Log file (baris JSON) yang ditulis oleh Gateway.
• Keluaran konsol yang ditampilkan di terminal dan UI Debug Gateway.

Tab Log UI Kontrol mengikuti log file gateway. Halaman ini menjelaskan lokasi log, cara membacanya, dan cara mengonfigurasi level serta format log.

Lokasi log

Secara default, Gateway menulis file log bergulir di bawah:

/tmp/openclaw/openclaw-YYYY-MM-DD.log

Tanggal menggunakan zona waktu lokal host gateway.

Setiap file dirotasi saat mencapai logging.maxFileBytes (default: 100 MB). OpenClaw menyimpan hingga lima arsip bernomor di samping file aktif, seperti openclaw-YYYY-MM-DD.1.log, dan terus menulis ke log aktif baru alih-alih menekan diagnostik.

Anda dapat menimpanya di ~/.openclaw/openclaw.json:

{  "logging": {    "file": "/path/to/openclaw.log"  }}

Cara membaca log

CLI: ikuti langsung (direkomendasikan)

Gunakan CLI untuk mengikuti file log gateway melalui RPC:

openclaw logs --follow

Opsi saat ini yang berguna:

• --local-time: render stempel waktu dalam zona waktu lokal Anda
• --url <url> / --token <token> / --timeout <ms>: flag RPC Gateway standar
• --expect-final: flag tunggu respons akhir berbasis agen (diterima di sini melalui lapisan klien bersama)

Mode keluaran:

• Sesi TTY: baris log terstruktur yang rapi dan berwarna.
• Sesi non-TTY: teks biasa.
• --json: JSON yang dibatasi baris (satu peristiwa log per baris).
• --plain: paksa teks biasa dalam sesi TTY.
• --no-color: nonaktifkan warna ANSI.

Saat Anda meneruskan --url eksplisit, CLI tidak otomatis menerapkan konfigurasi atau kredensial lingkungan; sertakan sendiri --token jika Gateway target memerlukan auth.

Dalam mode JSON, CLI menghasilkan objek bertanda type:

• meta: metadata stream (file, cursor, ukuran)
• log: entri log yang diurai
• notice: petunjuk pemotongan / rotasi
• raw: baris log yang tidak diurai

Jika Gateway local loopback implisit meminta pemasangan, menutup saat koneksi, atau waktu habis sebelum logs.tail menjawab, openclaw logs otomatis kembali ke log file Gateway yang dikonfigurasi. Target --url eksplisit tidak menggunakan fallback ini.

Jika Gateway tidak dapat dijangkau, CLI mencetak petunjuk singkat untuk menjalankan:

openclaw doctor

UI Kontrol (web)

Tab Log UI Kontrol mengikuti file yang sama menggunakan logs.tail. Lihat UI Kontrol untuk cara membukanya.

Log khusus channel

Untuk memfilter aktivitas channel (WhatsApp/Telegram/dll.), gunakan:

openclaw channels logs --channel whatsapp

Format log

Log file (JSONL)

Setiap baris dalam file log adalah objek JSON. CLI dan UI Kontrol mengurai entri ini untuk merender keluaran terstruktur (waktu, level, subsistem, pesan).

Catatan JSONL log file juga menyertakan bidang tingkat atas yang dapat difilter mesin saat tersedia:

• hostname: nama host gateway.
• message: teks pesan log yang diratakan untuk pencarian teks penuh.
• agent_id: id agen aktif saat panggilan log membawa konteks agen.
• session_id: id/kunci sesi aktif saat panggilan log membawa konteks sesi.
• channel: channel aktif saat panggilan log membawa konteks channel.

OpenClaw mempertahankan argumen log terstruktur asli di samping bidang-bidang ini sehingga parser yang ada yang membaca kunci argumen tslog bernomor tetap berfungsi.

Aktivitas bicara, suara realtime, dan ruang terkelola memancarkan catatan log siklus hidup terbatas melalui pipeline log file yang sama ini. Catatan ini menyertakan jenis peristiwa, mode, transport, provider, serta pengukuran ukuran/waktu saat tersedia, tetapi menghilangkan teks transkrip, payload audio, id giliran, id panggilan, dan id item provider.

Keluaran konsol

Log konsol sadar TTY dan diformat agar mudah dibaca:

• Prefiks subsistem (mis. gateway/channels/whatsapp)
• Pewarnaan level (info/warn/error)
• Mode ringkas atau JSON opsional

Pemformatan konsol dikendalikan oleh logging.consoleStyle.

Log WebSocket Gateway

openclaw gateway juga memiliki pencatatan protokol WebSocket untuk trafik RPC:

• mode normal: hanya hasil yang menarik (error, error penguraian, panggilan lambat)
• --verbose: semua trafik permintaan/respons
• --ws-log auto|compact|full: pilih gaya render verbose
• --compact: alias untuk --ws-log compact

Contoh:

openclaw gatewayopenclaw gateway --verbose --ws-log compactopenclaw gateway --verbose --ws-log full

Mengonfigurasi pencatatan log

Semua konfigurasi pencatatan log berada di bawah logging dalam ~/.openclaw/openclaw.json.

{  "logging": {    "level": "info",    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",    "consoleLevel": "info",    "consoleStyle": "pretty",    "redactSensitive": "tools",    "redactPatterns": ["sk-.*"]  }}

Level log

• logging.level: level log file (JSONL).
• logging.consoleLevel: level verbositas konsol.

Anda dapat menimpa keduanya melalui variabel lingkungan OPENCLAW_LOG_LEVEL (mis. OPENCLAW_LOG_LEVEL=debug). Variabel lingkungan lebih diutamakan daripada file konfigurasi, sehingga Anda dapat menaikkan verbositas untuk satu kali proses tanpa mengedit openclaw.json. Anda juga dapat meneruskan opsi CLI global --log-level <level> (misalnya, openclaw --log-level debug gateway run), yang menimpa variabel lingkungan untuk perintah tersebut.

--verbose hanya memengaruhi keluaran konsol dan verbositas log WS; ini tidak mengubah level log file.

Diagnostik transport model tertarget

Saat men-debug panggilan provider, gunakan flag lingkungan tertarget alih-alih menaikkan semua log ke debug:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gatewayOPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway

Flag yang tersedia:

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1: pancarkan awal permintaan, respons fetch, header SDK, peristiwa streaming pertama, penyelesaian stream, dan error transport pada level info.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: sertakan ringkasan payload permintaan terbatas dalam log permintaan model.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: sertakan semua nama tool yang menghadap model dalam ringkasan payload.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: sertakan snapshot payload JSON yang disunting dan dibatasi. Gunakan hanya saat debugging; rahasia disunting tetapi prompt dan teks pesan mungkin masih ada.
• OPENCLAW_DEBUG_SSE=events: pancarkan waktu peristiwa pertama dan penyelesaian stream.
• OPENCLAW_DEBUG_SSE=peek: juga pancarkan lima payload peristiwa SSE pertama yang disunting, dibatasi per peristiwa.
• OPENCLAW_DEBUG_CODE_MODE=1: pancarkan diagnostik permukaan model mode kode, termasuk saat tool provider native disembunyikan karena mode kode memiliki permukaan tool.

Flag ini mencatat melalui pencatatan log OpenClaw normal, sehingga openclaw logs --follow dan tab Log UI Kontrol menampilkannya. Tanpa flag tersebut, diagnostik yang sama tetap tersedia pada level debug.

Korelasi trace

Log file adalah JSONL. Saat panggilan log membawa konteks trace diagnostik yang valid, OpenClaw menulis bidang trace sebagai kunci JSON tingkat atas (traceId, spanId, parentSpanId, traceFlags) sehingga pemroses log eksternal dapat mengorelasikan baris dengan span OTEL dan propagasi traceparent provider.

Permintaan HTTP Gateway dan frame WebSocket Gateway membentuk cakupan trace permintaan internal. Log dan peristiwa diagnostik yang dipancarkan di dalam cakupan async tersebut mewarisi trace permintaan saat tidak meneruskan konteks trace eksplisit. Trace run agen dan panggilan model menjadi anak dari trace permintaan aktif, sehingga log lokal, snapshot diagnostik, span OTEL, dan header traceparent provider tepercaya dapat digabungkan dengan traceId tanpa mencatat permintaan mentah atau konten model.

Catatan log siklus hidup bicara juga mengalir ke log OTLP saat ekspor log OpenTelemetry diaktifkan, menggunakan atribut terbatas yang sama dengan log file.

Ukuran dan waktu panggilan model

Diagnostik panggilan model mencatat pengukuran permintaan/respons terbatas tanpa menangkap konten prompt atau respons mentah:

• requestPayloadBytes: ukuran byte UTF-8 dari payload permintaan model akhir
• responseStreamBytes: ukuran byte UTF-8 dari peristiwa respons model yang di-stream
• timeToFirstByteMs: waktu berlalu sebelum peristiwa respons streaming pertama
• durationMs: total durasi panggilan model

Bidang ini tersedia untuk snapshot diagnostik, hook Plugin panggilan model, dan span/metrik panggilan model OTEL saat ekspor diagnostik diaktifkan.

Gaya konsol

logging.consoleStyle:

• pretty: ramah manusia, berwarna, dengan stempel waktu.
• compact: keluaran lebih rapat (terbaik untuk sesi panjang).
• json: JSON per baris (untuk pemroses log).

Redaksi

OpenClaw dapat menyunting token sensitif sebelum masuk ke keluaran konsol, log file, catatan log OTLP, teks transkrip sesi yang dipertahankan, atau payload peristiwa tool UI Kontrol (argumen awal tool, payload hasil parsial/akhir, keluaran exec turunan, dan ringkasan patch):

• logging.redactSensitive: off | tools (default: tools)
• logging.redactPatterns: daftar string regex untuk menimpa set default. Pola kustom diterapkan di atas default bawaan untuk payload tool UI Kontrol, sehingga menambahkan pola tidak pernah melemahkan redaksi nilai yang sudah tertangkap oleh default.

Log file dan transkrip sesi tetap JSONL, tetapi nilai rahasia yang cocok disamarkan sebelum baris atau pesan ditulis ke disk. Redaksi bersifat upaya terbaik: ini diterapkan pada konten pesan yang berisi teks dan string log, bukan setiap identifier atau bidang payload biner.

Default bawaan mencakup kredensial API umum dan nama bidang kredensial pembayaran seperti nomor kartu, CVC/CVV, token pembayaran bersama, dan kredensial pembayaran saat muncul sebagai bidang JSON, parameter URL, flag CLI, atau assignment.

logging.redactSensitive: "off" hanya menonaktifkan kebijakan log/transkrip umum ini. OpenClaw tetap menyunting payload batas keselamatan yang dapat ditampilkan kepada klien UI, bundle dukungan, pengamat diagnostik, prompt persetujuan, atau tool agen. Contohnya mencakup peristiwa panggilan tool UI Kontrol, keluaran sessions_history, ekspor dukungan diagnostik, observasi error provider, tampilan perintah persetujuan exec, dan log protokol WebSocket Gateway. logging.redactPatterns kustom masih dapat menambahkan pola khusus proyek pada permukaan tersebut.

Diagnostik dan OpenTelemetry

Diagnostik adalah peristiwa terstruktur yang dapat dibaca mesin untuk run model dan telemetri alur pesan (Webhook, antrean, status sesi). Diagnostik tidak menggantikan log — diagnostik memasok metrik, trace, dan exporter. Peristiwa dipancarkan dalam proses baik Anda mengekspornya maupun tidak.

Dua permukaan bersebelahan:

• Ekspor OpenTelemetry — kirim metrik, trace, dan log melalui OTLP/HTTP ke collector atau backend yang kompatibel dengan OpenTelemetry apa pun (Grafana, Datadog, Honeycomb, New Relic, Tempo, dll.). Konfigurasi lengkap, katalog sinyal, nama metrik/span, variabel lingkungan, dan model privasi ada di halaman khusus: Ekspor OpenTelemetry.
• Flag diagnostik — flag log debug tertarget yang mengarahkan log tambahan ke logging.file tanpa menaikkan logging.level. Flag tidak peka huruf besar/kecil dan mendukung wildcard (telegram.*, *). Konfigurasikan di bawah diagnostics.flags atau melalui override lingkungan OPENCLAW_DIAGNOSTICS=.... Panduan lengkap: Flag diagnostik.

Untuk mengaktifkan peristiwa diagnostik bagi Plugin atau sink kustom tanpa ekspor OTLP:

{  diagnostics: { enabled: true },}

Untuk ekspor OTLP ke collector, lihat Ekspor OpenTelemetry.

Tips pemecahan masalah

• Gateway tidak dapat dijangkau? Jalankan openclaw doctor terlebih dahulu.
• Log kosong? Periksa bahwa Gateway sedang berjalan dan menulis ke path file di logging.file.
• Perlu detail lebih banyak? Setel logging.level ke debug atau trace dan coba lagi.

Terkait

• Ekspor OpenTelemetry — ekspor OTLP/HTTP, katalog metrik/span, model privasi
• Flag diagnostik — flag log debug tertarget
• Internal pencatatan log Gateway — gaya log WS, prefiks subsistem, dan penangkapan konsol
• Referensi konfigurasi — referensi lengkap bidang diagnostics.*