文档
日志记录

日志记录

适用范围

在以下情况使用此页面：

  • 你需要适合初学者的日志记录概述
  • 你想配置日志级别或格式
  • 你正在故障排除并需要快速找到日志

Clawdbot 在两个地方记录日志：

  • 文件日志（JSON 行）由网关写入。
  • 控制台输出显示在终端和控制 UI 中。

本页面解释日志的存放位置、如何读取它们以及如何配置日志级别和格式。

日志的存放位置

默认情况下，网关在以下位置写入滚动日志文件：

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

日期使用网关主机的本地时区。

你可以在 ~/.clawdbot/clawdbot.json 中覆盖它：

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

如何读取日志

CLI：实时尾随（推荐）

使用 CLI 通过 RPC 尾随网关日志文件：

clawdbot logs --follow

输出模式：

  • TTY 会话：漂亮、彩色、结构化的日志行。
  • 非 TTY 会话：纯文本。
  • --json：行分隔的 JSON（每行一个日志事件）。
  • --plain：在 TTY 会话中强制纯文本。
  • --no-color：禁用 ANSI 颜色。

在 JSON 模式下，CLI 发出 type 标记的对象：

  • meta：流元数据（文件、光标、大小）
  • log：解析的日志条目
  • notice：截断/轮换提示
  • raw：未解析的日志行

如果网关无法访问，CLI 会打印一个简短的提示来运行：

clawdbot doctor

控制 UI（Web）

控制 UI 的日志选项卡使用 logs.tail 尾随同一文件。 有关如何打开它，请参阅 /web/control-ui。

仅频道日志

要过滤频道活动（WhatsApp/Telegram/等），请使用：

clawdbot channels logs --channel whatsapp

日志格式

文件日志（JSONL）

日志文件中的每一行都是一个 JSON 对象。CLI 和控制 UI 解析这些条目以呈现结构化输出（时间、级别、子系统、消息）。

控制台输出

控制台日志是 TTY 感知的，并为可读性格式化：

  • 子系统前缀（例如 gateway/channels/whatsapp）
  • 级别着色（info/warn/error）
  • 可选的紧凑或 JSON 模式

控制台格式由 logging.consoleStyle 控制。

配置日志记录

所有日志记录配置都位于 ~/.clawdbot/clawdbot.json 中的 logging 下。

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

日志级别

  • logging.level：文件日志（JSONL）级别。
  • logging.consoleLevel：控制台详细级别。

--verbose 仅影响控制台输出；它不会改变文件日志级别。

控制台样式

logging.consoleStyle：

  • pretty：人类友好、彩色、带时间戳。
  • compact：更紧凑的输出（最适合长会话）。
  • json：每行 JSON（用于日志处理器）。

编辑

工具摘要可以在触及控制台之前编辑敏感令牌：

  • logging.redactSensitive：off | tools（默认：tools）
  • logging.redactPatterns：用于覆盖默认集的正则表达式字符串列表

编辑仅影响控制台输出，不会改变文件日志。

诊断 + OpenTelemetry

诊断是用于模型运行和消息流遥测（Webhook、队列、会话状态）的结构化、机器可读事件。它们不替代日志；它们的存在是为了提供指标、跟踪和其他导出器。

诊断事件在进程中发出，但只有在启用诊断 + 导出器插件时才会附加导出器。

OpenTelemetry vs OTLP

  • OpenTelemetry（OTel）：用于跟踪、指标和日志的数据模型 + SDK。
  • OTLP：用于将 OTel 数据导出到收集器/后端的线路协议。
  • Clawdbot 今天通过 **OTLP/HTTP（protobuf）**导出。

导出的信号

  • 指标：计数器 + 直方图（令牌使用、消息流、队列）。
  • 跟踪：模型使用 + Webhook/消息处理的跨度。
  • 日志：当启用 diagnostics.otel.logs 时通过 OTLP 导出。日志量可能很高；请记住 logging.level 和导出器过滤器。

诊断事件目录

模型使用：

  • model.usage：令牌、成本、持续时间、上下文、提供商/模型/频道、会话 ID。

消息流：

  • webhook.received：每个频道的 Webhook 入站。
  • webhook.processed：Webhook 已处理 + 持续时间。
  • webhook.error：Webhook 处理程序错误。
  • message.queued：消息已排队以进行处理。
  • message.processed：结果 + 持续时间 + 可选错误。

队列 + 会话：

  • queue.lane.enqueue：命令队列车道入队 + 深度。
  • queue.lane.dequeue：命令队列车道出队 + 等待时间。
  • session.state：会话状态转换 + 原因。
  • session.stuck：会话卡住警告 + 年龄。
  • run.attempt：运行重试/尝试元数据。
  • diagnostic.heartbeat：聚合计数器（Webhook/队列/会话）。

启用诊断（无导出器）

如果你希望诊断事件可用于插件或自定义接收器，请使用此选项：

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

诊断标志（定向日志）

使用标志打开额外的、定向的调试日志，而无需提高 logging.level。标志不区分大小写，支持通配符（例如 telegram.* 或 *）。

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

Env 覆盖（一次性）：

CLAWDBOT_DIAGNOSTICS=telegram.http,telegram.payload

注意事项：

  • 标志日志进入标准日志文件（与 logging.file 相同）。
  • 输出仍然根据 logging.redactSensitive 进行编辑。
  • 完整指南：/diagnostics/flags。

导出到 OpenTelemetry

诊断可以通过 diagnostics-otel 插件（OTLP/HTTP）导出。这适用于任何接受 OTLP/HTTP 的 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": "clawdbot-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000
    }
  }
}

注意事项：

  • 你还可以使用 clawdbot plugins enable diagnostics-otel 启用插件。
  • protocol 目前仅支持 http/protobuf。grpc 被忽略。
  • 指标包括令牌使用、成本、上下文大小、运行持续时间以及消息流计数器/直方图（Webhook、队列、会话状态、队列深度/等待）。
  • 可以使用 traces / metrics 切换跟踪/指标（默认：开启）。启用后，跟踪包括模型使用跨度以及 Webhook/消息处理跨度。
  • 当收集器需要身份验证时，设置 headers。
  • 支持环境变量：OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_SERVICE_NAME、OTEL_EXPORTER_OTLP_PROTOCOL。

导出的指标（名称 + 类型）

模型使用：

  • clawdbot.tokens（计数器，attrs：clawdbot.token、clawdbot.channel、clawdbot.provider、clawdbot.model）
  • clawdbot.cost.usd（计数器，attrs：clawdbot.channel、clawdbot.provider、clawdbot.model）
  • clawdbot.run.duration_ms（直方图，attrs：clawdbot.channel、clawdbot.provider、clawdbot.model）
  • clawdbot.context.tokens（直方图，attrs：clawdbot.context、clawdbot.channel、clawdbot.provider、clawdbot.model）

消息流：

  • clawdbot.webhook.received（计数器，attrs：clawdbot.channel、clawdbot.webhook）
  • clawdbot.webhook.error（计数器，attrs：clawdbot.channel、clawdbot.webhook）
  • clawdbot.webhook.duration_ms（直方图，attrs：clawdbot.channel、clawdbot.webhook）
  • clawdbot.message.queued（计数器，attrs：clawdbot.channel、clawdbot.source）
  • clawdbot.message.processed（计数器，attrs：clawdbot.channel、clawdbot.outcome）
  • clawdbot.message.duration_ms（直方图，attrs：clawdbot.channel、clawdbot.outcome）

队列 + 会话：

  • clawdbot.queue.lane.enqueue（计数器，attrs：clawdbot.lane）
  • clawdbot.queue.lane.dequeue（计数器，attrs：clawdbot.lane）
  • clawdbot.queue.depth（直方图，attrs：clawdbot.lane 或 clawdbot.channel=heartbeat）
  • clawdbot.queue.wait_ms（直方图，attrs：clawdbot.lane）
  • clawdbot.session.state（计数器，attrs：clawdbot.state、clawdbot.reason）
  • clawdbot.session.stuck（计数器，attrs：clawdbot.state）
  • clawdbot.session.stuck_age_ms（直方图，attrs：clawdbot.state）
  • clawdbot.run.attempt（计数器，attrs：clawdbot.attempt）

导出的跨度（名称 + 关键属性）

  • clawdbot.model.usage
    • clawdbot.channel、clawdbot.provider、clawdbot.model
    • clawdbot.sessionKey、clawdbot.sessionId
    • clawdbot.tokens.*（input/output/cache_read/cache_write/total）
  • clawdbot.webhook.processed
    • clawdbot.channel、clawdbot.webhook、clawdbot.chatId
  • clawdbot.webhook.error
    • clawdbot.channel、clawdbot.webhook、clawdbot.chatId、clawdbot.error
  • clawdbot.message.processed
    • clawdbot.channel、clawdbot.outcome、clawdbot.chatId、clawdbot.messageId、clawdbot.sessionKey、clawdbot.sessionId、clawdbot.reason
  • clawdbot.session.stuck
    • clawdbot.state、clawdbot.ageMs、clawdbot.queueDepth、clawdbot.sessionKey、clawdbot.sessionId

采样 + 刷新

  • 跟踪采样：diagnostics.otel.sampleRate（0.0–1.0，仅根跨度）。
  • 指标导出间隔：diagnostics.otel.flushIntervalMs（最小 1000ms）。

协议说明

  • OTLP/HTTP 端点可以通过 diagnostics.otel.endpoint 或 OTEL_EXPORTER_OTLP_ENDPOINT 设置。
  • 如果端点已包含 /v1/traces 或 /v1/metrics，则按原样使用。
  • 如果端点已包含 /v1/logs，则按原样用于日志。
  • diagnostics.otel.logs 启用主日志记录器输出的 OTLP 日志导出。

日志导出行为

  • OTLP 日志使用写入 logging.file 的相同结构化记录。
  • 尊重 logging.level（文件日志级别）。控制台编辑不适用于 OTLP 日志。
  • 大量安装应首选 OTLP 收集器采样/过滤。

故障排除提示

  • 网关无法访问？ 首先运行 clawdbot doctor。
  • 日志为空？ 检查网关是否正在运行并写入 logging.file 中的文件路径。
  • 需要更多详细信息？ 将 logging.level 设置为 debug 或 trace 并重试。
日期与时间入门 + 配置协议