Logging

OpenClaw ghi log ở hai nơi:

  • File log (JSON lines) được Gateway ghi ra.
  • Console output hiển thị trong terminal và Control UI.

Trang này sẽ giải thích log được lưu ở đâu, cách đọc log, và cách cấu hình log level cũng như format.

Log được lưu ở đâu

Mặc định, Gateway ghi file log luân phiên (rolling log) tại:

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

Ngày tháng sử dụng timezone local của máy chủ gateway.

Các bạn có thể thay đổi đường dẫn trong ~/.openclaw/openclaw.json:

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

Cách đọc log

CLI: live tail (khuyên dùng)

Dùng CLI để tail file log của gateway qua RPC:

openclaw logs --follow

Các chế độ output:

  • TTY sessions: log đẹp, có màu, có cấu trúc.
  • Non-TTY sessions: plain text.
  • --json: JSON phân cách theo dòng (mỗi dòng là một log event).
  • --plain: bắt buộc dùng plain text trong TTY session.
  • --no-color: tắt màu ANSI.

Ở chế độ JSON, CLI sẽ xuất ra các object có tag type:

  • meta: metadata của stream (file, cursor, size)
  • log: log entry đã parse
  • notice: gợi ý về truncation / rotation
  • raw: dòng log chưa parse

Nếu Gateway không kết nối được, CLI sẽ hiển thị gợi ý chạy:

openclaw doctor

Control UI (web)

Tab Logs của Control UI cũng tail cùng file này bằng logs.tail. Xem /web/control-ui để biết cách mở Control UI.

Log chỉ theo Channel

Để lọc hoạt động của channel (WhatsApp/Telegram/etc), dùng:

openclaw channels logs --channel whatsapp

Định dạng log

File log (JSONL)

Mỗi dòng trong file log là một JSON object. CLI và Control UI sẽ parse các entry này để hiển thị output có cấu trúc (thời gian, level, subsystem, message).

Console output

Console log có TTY-aware và được format để dễ đọc:

  • Prefix của subsystem (ví dụ: gateway/channels/whatsapp)
  • Màu theo level (info/warn/error)
  • Chế độ compact hoặc JSON tùy chọn

Format của console được điều khiển bởi logging.consoleStyle.

Cấu hình logging

Tất cả cấu hình logging nằm trong phần logging của ~/.openclaw/openclaw.json.

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

Log level

  • logging.level: level của file log (JSONL).
  • logging.consoleLevel: level chi tiết của console.

Flag --verbose chỉ ảnh hưởng đến console output; nó không thay đổi file log level.

Console style

logging.consoleStyle:

  • pretty: thân thiện với người dùng, có màu, có timestamp.
  • compact: output gọn hơn (tốt cho session dài).
  • json: JSON mỗi dòng (cho log processor).

Redaction

Tool summary có thể che (redact) các token nhạy cảm trước khi hiển thị ra console:

  • logging.redactSensitive: off | tools (mặc định: tools)
  • logging.redactPatterns: danh sách regex string để override bộ mặc định

Redaction chỉ ảnh hưởng đến console output và không thay đổi file log.

Diagnostics + OpenTelemetry

Diagnostics là các event có cấu trúc, máy đọc được, dành cho model run và telemetry của message-flow (webhook, queueing, session state). Chúng không thay thế log; chúng tồn tại để cung cấp metrics, trace và các exporter khác.

Diagnostics event được emit trong process, nhưng exporter chỉ attach khi diagnostics + exporter plugin được bật.

OpenTelemetry vs OTLP

  • OpenTelemetry (OTel): data model + SDK cho trace, metric và log.
  • OTLP: wire protocol dùng để export dữ liệu OTel đến collector/backend.
  • OpenClaw export qua OTLP/HTTP (protobuf) hiện tại.

Signal được export

  • Metrics: counter + histogram (token usage, message flow, queueing).
  • Traces: span cho model usage + webhook/message processing.
  • Logs: export qua OTLP khi diagnostics.otel.logs được bật. Log volume có thể cao; lưu ý logging.level và exporter filter.

Catalog của Diagnostic event

Model usage:

  • model.usage: token, cost, duration, context, provider/model/channel, session id.

Message flow:

  • webhook.received: webhook ingress theo channel.
  • webhook.processed: webhook đã xử lý + duration.
  • webhook.error: lỗi webhook handler.
  • message.queued: message được đưa vào queue để xử lý.
  • message.processed: kết quả + duration + lỗi (nếu có).

Queue + session:

  • queue.lane.enqueue: enqueue vào command queue lane + depth.
  • queue.lane.dequeue: dequeue từ command queue lane + thời gian chờ.
  • session.state: chuyển trạng thái session + lý do.
  • session.stuck: cảnh báo session bị stuck + tuổi.
  • run.attempt: metadata về retry/attempt của run.
  • diagnostic.heartbeat: counter tổng hợp (webhook/queue/session).

Bật diagnostics (không có exporter)

Dùng cái này nếu các bạn muốn diagnostics event có sẵn cho plugin hoặc custom sink:

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

Diagnostics flag (targeted log)

Dùng flag để bật thêm debug log có mục tiêu cụ thể mà không cần tăng logging.level. Flag không phân biệt chữ hoa/thường và hỗ trợ wildcard (ví dụ: telegram.* hoặc *).

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

Override bằng biến môi trường (dùng một lần):

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Lưu ý:

  • Flag log được ghi vào file log chuẩn (giống logging.file).
  • Output vẫn được redact theo logging.redactSensitive.
  • Hướng dẫn đầy đủ: /diagnostics/flags.

Export sang OpenTelemetry

Diagnostics có thể export qua plugin diagnostics-otel (OTLP/HTTP). Cái này hoạt động với bất kỳ OpenTelemetry collector/backend nào chấp nhận 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
    }
  }
}

Lưu ý:

  • Các bạn cũng có thể bật plugin bằng openclaw plugins enable diagnostics-otel.
  • protocol hiện chỉ hỗ trợ http/protobuf. grpc bị bỏ qua.
  • Metric bao gồm token usage, cost, context size, run duration và message-flow counter/histogram (webhook, queueing, session state, queue depth/wait).
  • Trace/metric có thể bật/tắt bằng traces / metrics (mặc định: bật). Trace bao gồm model usage span cộng với webhook/message processing span khi được bật.
  • Set headers khi collector của các bạn yêu cầu auth.
  • Biến môi trường được hỗ trợ: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_PROTOCOL.

Metric được export (tên + kiểu)

Model usage:

  • openclaw.tokens (counter, attrs: openclaw.token, openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.cost.usd (counter, attrs: openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.run.duration_ms (histogram, attrs: openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.context.tokens (histogram, attrs: openclaw.context, openclaw.channel, openclaw.provider, openclaw.model)

Message flow:

  • openclaw.webhook.received (counter, attrs: openclaw.channel, openclaw.webhook)
  • openclaw.webhook.error (counter, attrs: openclaw.channel, openclaw.webhook)
  • openclaw.webhook.duration_ms (histogram, attrs: openclaw.channel, openclaw.webhook)
  • openclaw.message.queued (counter, attrs: openclaw.channel, openclaw.source)
  • openclaw.message.processed (counter, attrs: openclaw.channel, openclaw.outcome)
  • openclaw.message.duration_ms (histogram, attrs: openclaw.channel, openclaw.outcome)

Queue + session:

  • openclaw.queue.lane.enqueue (counter, attrs: openclaw.lane)
  • openclaw.queue.lane.dequeue (counter, attrs: openclaw.lane)
  • openclaw.queue.depth (histogram, attrs: openclaw.lane hoặc openclaw.channel=heartbeat)
  • openclaw.queue.wait_ms (histogram, attrs: openclaw.lane)
  • openclaw.session.state (counter, attrs: openclaw.state, openclaw.reason)
  • openclaw.session.stuck (counter, attrs: openclaw.state)
  • openclaw.session.stuck_age_ms (histogram, attrs: openclaw.state)
  • openclaw.run.attempt (counter, attrs: openclaw.attempt)

Span được export (tên + attribute chính)

  • openclaw.model.usage
    • openclaw.channel, openclaw.provider, openclaw.model
    • openclaw.sessionKey, openclaw.sessionId
    • openclaw.tokens.* (input/output/cache_read/cache_write/total)
  • openclaw.webhook.processed
    • openclaw.channel, openclaw.webhook, openclaw.chatId
  • openclaw.webhook.error
    • openclaw.channel, openclaw.webhook, openclaw.chatId, openclaw.error
  • openclaw.message.processed
    • openclaw.channel, openclaw.outcome, openclaw.chatId, openclaw.messageId, openclaw.sessionKey, openclaw.sessionId, openclaw.reason
  • openclaw.session.stuck
    • openclaw.state, openclaw.ageMs, openclaw.queueDepth, openclaw.sessionKey, openclaw.sessionId

Sampling + flushing

  • Trace sampling: diagnostics.otel.sampleRate (0.0–1.0, chỉ root span).
  • Metric export interval: diagnostics.otel.flushIntervalMs (tối thiểu 1000ms).

Lưu ý về protocol

  • OTLP/HTTP endpoint có thể set qua diagnostics.otel.endpoint hoặc OTEL_EXPORTER_OTLP_ENDPOINT.
  • Nếu endpoint đã chứa /v1/traces hoặc /v1/metrics, nó được dùng nguyên vẹn.
  • Nếu endpoint đã chứa /v1/logs, nó được dùng nguyên vẹn cho log.
  • diagnostics.otel.logs bật OTLP log export cho main logger output.

Hành vi của log export

  • OTLP log dùng cùng structured record được ghi vào logging.file.
  • Tuân theo logging.level (file log level). Console redaction không áp dụng cho OTLP log.
  • Các cài đặt có volume cao nên dùng OTLP collector sampling/filtering.

Mẹo troubleshooting

  • Gateway không kết nối được? Chạy openclaw doctor trước.
  • Log trống? Kiểm tra xem Gateway có đang chạy và ghi vào đường dẫn file trong logging.file không.
  • Cần chi tiết hơn? Set logging.level thành debug hoặc trace rồi thử lại.