​

Logging

• File logs (dạng JSON lines) được ghi bởi Gateway.
• Console output hiển thị trong terminal và Control UI.

​

Vị trí lưu trữ log

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

​

Cách đọc log

​

CLI: theo dõi trực tiếp (khuyến nghị)

openclaw logs --follow

• TTY sessions: log được định dạng đẹp, có màu sắc.
• Non-TTY sessions: văn bản đơn giản.
• --json: JSON phân cách theo dòng (mỗi sự kiện log một dòng).
• --plain: buộc hiển thị văn bản đơn giản trong TTY sessions.
• --no-color: tắt màu ANSI.

• meta: thông tin metadata của luồng (file, con trỏ, kích thước)
• log: mục log đã được phân tích
• notice: gợi ý về cắt ngắn/luân chuyển
• raw: dòng log chưa phân tích

openclaw doctor

​

Control UI (web)

​

Log chỉ dành cho kênh

openclaw channels logs --channel whatsapp

​

Định dạng log

​

File logs (JSONL)

​

Console output

• Tiền tố hệ thống con (ví dụ: gateway/channels/whatsapp)
• Màu sắc theo mức độ (info/warn/error)
• Chế độ compact hoặc JSON tùy chọn

​

Cấu hình logging

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

​

Mức độ log

• logging.level: mức độ cho file logs (JSONL).
• logging.consoleLevel: mức độ chi tiết cho console.

​

Kiểu console

• pretty: thân thiện với người dùng, có màu, kèm thời gian.
• compact: gọn gàng hơn (tốt cho các phiên dài).
• json: JSON mỗi dòng (dành cho bộ xử lý log).

​

Che giấu thông tin nhạy cảm

• logging.redactSensitive: off | tools (mặc định: tools)
• logging.redactPatterns: danh sách các chuỗi regex để ghi đè bộ mặc định

​

Chẩn đoán + OpenTelemetry

​

OpenTelemetry vs OTLP

• OpenTelemetry (OTel): mô hình dữ liệu + SDK cho dấu vết, chỉ số và log.
• OTLP: giao thức truyền tải dữ liệu OTel đến collector/backend.
• OpenClaw hiện xuất qua OTLP/HTTP (protobuf).

​

Tín hiệu được xuất

• Metrics: bộ đếm + biểu đồ (sử dụng token, luồng thông điệp, hàng đợi).
• Traces: spans cho việc sử dụng mô hình + xử lý webhook/thông điệp.
• Logs: xuất qua OTLP khi diagnostics.otel.logs được bật. Khối lượng log có thể cao; hãy chú ý đến logging.level và bộ lọc bộ xuất.

​

Danh mục sự kiện chẩn đoán

• model.usage: tokens, chi phí, thời gian, ngữ cảnh, nhà cung cấp/mô hình/kênh, ids phiên.

• webhook.received: webhook nhận vào mỗi kênh.
• webhook.processed: webhook đã xử lý + thời gian.
• webhook.error: lỗi xử lý webhook.
• message.queued: thông điệp được đưa vào hàng đợi để xử lý.
• message.processed: kết quả + thời gian + lỗi tùy chọn.

• queue.lane.enqueue: đưa vào hàng đợi lệnh + độ sâu.
• queue.lane.dequeue: lấy ra khỏi hàng đợi lệnh + thời gian chờ.
• session.state: chuyển đổi trạng thái phiên + lý do.
• session.stuck: cảnh báo phiên bị kẹt + tuổi.
• run.attempt: metadata thử lại/chạy.
• diagnostic.heartbeat: bộ đếm tổng hợp (webhooks/hàng đợi/phiên).

​

Bật chẩn đoán (không có bộ xuất)

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

​

Cờ chẩn đoán (log mục tiêu)

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

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

• Log cờ được ghi vào file log chuẩn (giống như logging.file).
• Output vẫn bị che giấu theo logging.redactSensitive.
• Hướng dẫn đầy đủ: /diagnostics/flags.

​

Xuất sang OpenTelemetry

{
  "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
    }
  }
}

• Bạn cũng có thể bật plugin với openclaw plugins enable diagnostics-otel.
• protocol hiện chỉ hỗ trợ http/protobuf. grpc bị bỏ qua.
• Metrics bao gồm sử dụng token, chi phí, kích thước ngữ cảnh, thời gian chạy, và các bộ đếm/biểu đồ luồng thông điệp (webhooks, hàng đợi, trạng thái phiên, độ sâu hàng đợi/thời gian chờ).
• Traces/metrics có thể được bật/tắt với traces / metrics (mặc định: bật). Traces bao gồm các spans sử dụng mô hình cộng với các spans xử lý webhook/thông điệp khi được bật.
• Đặt headers khi collector của bạn yêu cầu xác thực.
• Các biến môi trường được hỗ trợ: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_PROTOCOL.

​

Metrics được xuất (tên + loại)

• 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)

• 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)

• 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)

​

Spans được xuất (tên + thuộc tính 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

• Sampling dấu vết: diagnostics.otel.sampleRate (0.0–1.0, chỉ root spans).
• Khoảng thời gian xuất metrics: diagnostics.otel.flushIntervalMs (tối thiểu 1000ms).

​

Ghi chú về giao thức

• Các endpoint OTLP/HTTP có thể được đặt qua diagnostics.otel.endpoint hoặc OTEL_EXPORTER_OTLP_ENDPOINT.
• Nếu endpoint đã chứa /v1/traces hoặc /v1/metrics, nó sẽ được sử dụng như hiện tại.
• Nếu endpoint đã chứa /v1/logs, nó sẽ được sử dụng như hiện tại cho logs.
• diagnostics.otel.logs bật xuất log OTLP cho output logger chính.

​

Hành vi xuất log

• Log OTLP sử dụng cùng các bản ghi có cấu trúc được ghi vào logging.file.
• Tôn trọng logging.level (mức độ log file). Che giấu console không áp dụng cho log OTLP.
• Các cài đặt có khối lượng lớn nên ưu tiên sampling/bộ lọc collector OTLP.

​

Mẹo khắc phục sự cố

• Gateway không thể truy cập? 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.
• Cần thêm chi tiết? Đặt logging.level thành debug hoặc trace và thử lại.