openclaw/docs

Fork 0

openclaw-docs-i18n[bot] e359695116 chore(i18n): refresh id translations

2026-04-24 09:35:31 +00:00

13 KiB

Raw Blame History

read_when

summary

title

x-i18n

Anda memerlukan ikhtisar logging yang ramah bagi pemula

Anda ingin mengonfigurasi level atau format log

Anda sedang memecahkan masalah dan perlu menemukan log dengan cepat

Ikhtisar logging: log file, output konsol, tailing CLI, dan UI Control

Ikhtisar logging

generated_at	model	provider	source_hash	source_path	workflow
2026-04-24T09:15:14Z	gpt-5.4	openai	9b6f274600bcb9f5597c91aa6c30512871105a3e0de446773394abbe27276058	logging.md	15

Logging

OpenClaw memiliki dua permukaan log utama:

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

Tab Logs di UI Control melakukan tail pada log file gateway. Halaman ini menjelaskan di mana log berada, cara membacanya, dan cara mengonfigurasi level serta format log.

Lokasi log

Secara default, Gateway menulis file log rolling di:

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

Tanggal menggunakan zona waktu lokal host gateway.

Anda dapat meng-override ini di ~/.openclaw/openclaw.json:

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

Cara membaca log

CLI: tail live (disarankan)

Gunakan CLI untuk melakukan tail pada 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 final RPC berbasis agen (diterima di sini melalui lapisan klien bersama)

Mode output:

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

Saat Anda memberikan --url eksplisit, CLI tidak otomatis menerapkan kredensial config atau environment; sertakan --token sendiri jika Gateway target memerlukan auth.

Dalam mode JSON, CLI mengeluarkan objek bertag type:

meta: metadata stream (file, cursor, size)
log: entri log yang telah di-parse
notice: petunjuk truncation / rotation
raw: baris log yang tidak di-parse

Jika Gateway loopback lokal meminta pairing, openclaw logs otomatis fallback ke file log lokal yang dikonfigurasi. Target --url eksplisit tidak menggunakan fallback ini.

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

openclaw doctor

UI Control (web)

Tab Logs di UI Control melakukan tail pada file yang sama menggunakan logs.tail. Lihat /web/control-ui untuk cara membukanya.

Log khusus saluran

Untuk memfilter aktivitas saluran (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 Control mem-parse entri ini untuk merender output terstruktur (waktu, level, subsistem, pesan).

Output konsol

Log konsol bersifat sadar TTY dan diformat agar mudah dibaca:

Prefiks subsistem (misalnya gateway/channels/whatsapp)
Pewarnaan level (info/warn/error)
Mode compact atau JSON opsional

Format konsol dikendalikan oleh logging.consoleStyle.

Log WebSocket Gateway

openclaw gateway juga memiliki logging protokol WebSocket untuk lalu lintas RPC:

mode normal: hanya hasil yang menarik (error, parse error, panggilan lambat)
--verbose: semua lalu lintas request/response
--ws-log auto|compact|full: pilih gaya rendering verbose
--compact: alias untuk --ws-log compact

Contoh:

openclaw gateway
openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full

Mengonfigurasi logging

Semua konfigurasi logging berada di bawah logging di ~/.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 meng-override keduanya melalui variabel environment OPENCLAW_LOG_LEVEL (misalnya OPENCLAW_LOG_LEVEL=debug). Variabel env ini lebih diutamakan daripada file config, jadi Anda dapat meningkatkan verbositas untuk satu kali eksekusi tanpa mengedit openclaw.json. Anda juga dapat memberikan opsi CLI global --log-level <level> (misalnya, openclaw --log-level debug gateway run), yang meng-override variabel environment untuk perintah tersebut.

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

Gaya konsol

logging.consoleStyle:

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

Redaksi

Ringkasan alat dapat menyamarkan token sensitif sebelum mencapai konsol:

logging.redactSensitive: off | tools (default: tools)
logging.redactPatterns: daftar string regex untuk meng-override set default

Redaksi hanya memengaruhi output konsol dan tidak mengubah log file.

Diagnostik + OpenTelemetry

Diagnostik adalah peristiwa terstruktur yang dapat dibaca mesin untuk eksekusi model dan telemetri alur pesan (Webhook, antrean, status sesi). Diagnostik tidak menggantikan log; diagnostik ada untuk memasok metrik, trace, dan exporter lainnya.

Peristiwa diagnostik dipancarkan di dalam proses, tetapi exporter hanya terpasang saat diagnostik + plugin exporter diaktifkan.

OpenTelemetry vs OTLP

OpenTelemetry (OTel): model data + SDK untuk trace, metrik, dan log.
OTLP: protokol wire yang digunakan untuk mengekspor data OTel ke collector/backend.
OpenClaw saat ini mengekspor melalui OTLP/HTTP (protobuf).

Sinyal yang diekspor

Metrik: counter + histogram (penggunaan token, alur pesan, antrean).
Trace: span untuk penggunaan model + pemrosesan Webhook/pesan.
Log: diekspor melalui OTLP saat diagnostics.otel.logs diaktifkan. Volume log bisa tinggi; pertimbangkan logging.level dan filter exporter.

Katalog peristiwa diagnostik

Penggunaan model:

model.usage: token, biaya, durasi, konteks, provider/model/channel, id sesi.

Alur pesan:

webhook.received: ingress Webhook per saluran.
webhook.processed: Webhook ditangani + durasi.
webhook.error: error handler Webhook.
message.queued: pesan dimasukkan ke antrean untuk diproses.
message.processed: hasil + durasi + error opsional.

Antrean + sesi:

queue.lane.enqueue: enqueue jalur antrean perintah + kedalaman.
queue.lane.dequeue: dequeue jalur antrean perintah + waktu tunggu.
session.state: transisi status sesi + alasan.
session.stuck: peringatan sesi macet + usia.
run.attempt: metadata retry/percobaan eksekusi.
diagnostic.heartbeat: counter agregat (Webhook/antrean/sesi).

Aktifkan diagnostik (tanpa exporter)

Gunakan ini jika Anda ingin peristiwa diagnostik tersedia untuk plugin atau sink kustom:

{
  "diagnostics": {
    "enabled": true
  }
}

Flag diagnostik (log terarah)

Gunakan flag untuk mengaktifkan log debug tambahan yang terarah tanpa menaikkan logging.level. Flag tidak peka huruf besar-kecil dan mendukung wildcard (misalnya telegram.* atau *).

{
  "diagnostics": {
    "flags": ["telegram.http"]
  }
}

Override env (sekali pakai):

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Catatan:

Log flag masuk ke file log standar (sama seperti logging.file).
Output tetap disamarkan sesuai logging.redactSensitive.
Panduan lengkap: /diagnostics/flags.

Ekspor ke OpenTelemetry

Diagnostik dapat diekspor melalui plugin diagnostics-otel (OTLP/HTTP). Ini bekerja dengan collector/backend OpenTelemetry apa pun yang menerima OTLP/HTTP.

{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://otel-collector:4318",
      "protocol": "http/protobuf",
      "serviceName": "openclaw-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000
    }
  }
}