Gateway 日志

有关面向用户的概述（CLI + Control UI + 配置），请参阅 /logging。

OpenClaw 有两个日志界面：

• 控制台输出 - 终端中显示的内容。
• 文件日志 - 网关记录器写入的 JSON 行。

启动时，网关会记录解析后的默认代理模型，以及影响新会话的模式默认值：

agent model: openai/gpt-6-astra (thinking=medium, fast=on)

thinking 来自默认代理、模型参数或全局代理默认值。未设置时显示 medium。fast 来自默认代理或模型的 fastMode 参数。

如果插件重新加载取代了启动时的插件加载，则模型行、已加载插件摘要和渠道警告将使用替换后的配置和插件元数据。

基于文件的日志记录¶

• 默认滚动日志文件位于 /tmp/openclaw/ 下（每天一个文件），按网关主机的本地时区标注日期。默认配置文件使用 openclaw-YYYY-MM-DD.log。命名配置文件使用 openclaw-<profile>-YYYY-MM-DD.log（例如 openclaw-dev-YYYY-MM-DD.log）。如果该目录不安全或不可写（所有者错误、全局可写、符号链接），OpenClaw 将回退到用户范围的 os.tmpdir()/openclaw-<uid> 路径。在 Windows 上，它始终使用该操作系统临时目录回退方案。
• 活动日志文件在达到 logging.maxFileBytes（默认：100 MB）时轮转。轮转最多保留五个编号归档文件（.1 到 .5），并继续写入新的活动文件。
• 通过 ~/.openclaw/openclaw.json 配置日志文件路径和级别：logging.file、logging.level。
• 文件格式为每行一个 JSON 对象。

启用配置热重载后，对 logging.level、logging.file 和 logging.maxFileBytes 的更改将应用于下一条日志记录，包括来自长期运行的渠道日志器的记录。排队中的记录会完成写入其原始文件。显式的日志器级别覆盖（例如 Baileys 详细程度）仍然有效。

子系统文件日志在 trace、debug、info 和 warn 记录（包括 raw() 行）中省略调用点元数据（_meta.path），以避免在每条常规消息上捕获和解析堆栈。error 和 fatal 记录保留该元数据。当诊断功能启用且内部日志记录消费者已订阅时，所有级别都保留调用点元数据，从而保留 OTLP 代码位置。从下一条记录开始，此行为遵循诊断启用和订阅状态，包括针对现有子系统日志器。调用方提供的日志消息、结构化字段和错误堆栈保持不变。

Talk、实时语音和托管房间代码路径使用共享文件日志器记录有界生命周期记录，用于运维调试和 OTLP 日志导出。转录文本、音频负载、轮次 ID、呼叫 ID 和提供者条目 ID 永远不会复制到日志记录中。

Discord 实时语音将会话生命周期转换保持在 info 级别；音频块和转录增量使用 debug 级别。模型获取开始和在一秒内成功的响应也使用 debug 级别。非 2xx 响应和耗时至少一秒的响应保持在 info 级别；传输失败仍为警告。现有的模型传输诊断标志在启用时会将传输详细信息提升到 info 级别。

密钥出口请求审计记录保持在 info 级别，包括成功转发的记录。其结构化字段记录代理结果，不包含请求负载或凭据；请参阅密钥出口代理。

Control UI 的“日志”选项卡通过网关（logs.tail）跟踪此文件。CLI 执行相同的操作：

openclaw logs --follow

如果跟踪读取发现活动文件已消失，Control UI 会清除之前的记录并跟踪重新创建的文件。缺失的文件仍返回空跟踪。文件系统读取错误（包括指向目录的日志路径）仍然可见，而 Control UI 会将最后成功读取的记录保留为陈旧数据。

详细模式与日志级别¶

• 文件日志完全由 logging.level 控制。
• --verbose 仅影响控制台详细程度（以及 WS 日志样式）——它不会提高文件日志级别。
• 要在文件日志中捕获仅限详细模式的细节，请将 logging.level 设置为 debug 或 trace。
• 嵌入式运行的 continue_normal 决策在 debug 级别记录。重试、配置文件轮转、模型回退和错误决策保持为警告。
• 跟踪日志还包括选定热路径的诊断计时摘要，例如插件工具工厂准备。请参阅 /tools/plugin#slow-plugin-tool-setup。

SQLite 会话写入¶

失败的 SQLite 会话写入在其结构化文件日志记录中包含一个有界且已脱敏的 error 摘要，并在可用时提供原因和错误代码详情。较长的摘要会被截断。记录保留其写入时序和存储字段。

SQLite 快照清理¶

临时只读 SQLite 快照的移除失败会由其清理所有者记录一次到结构化文件日志中，并包含所属路径、移除操作和可用的文件系统错误代码。这些诊断不会写入子进程的 stdout 或 stderr，因此成功的读取保留其结果，失败的更新保留其原始错误详情。现有的必需清理失败仍为错误。

缓慢的代理数据库打开¶

完成一次耗时至少一秒的物理代理数据库打开操作时，会发出 slow OpenClaw agent database open 记录。该记录保留总耗时以及 open、validation、configuration、schema 和 registration 各阶段。对于产生结果的完整性检查，它还包括 integrityGateMs 和 integrityGateOutcome（healthy 或 failed）。该门控包括检查以及任何驱动程序等待、调度和所有权重新验证。当准入使用单独的完整性 Worker 时，其生命周期也会被包含在内。这不单独区分原生检查时间或 CPU 时间。

当规范索引验证完成时，canonicalIndexMs 报告后续同步检查以及任何修复或重新检查，repairedIndexCount 统计该操作成功修复的索引数量。初始完整性检查健康时仍可能需要索引定义修复。失败的初始检查可以通过成功修复恢复。当相应阶段未运行时，字段会缺失，包括全新空数据库的 yielded-check 字段。这些详情涵盖 validation 的一部分，而不是需要额外加到其上的时间。摘要仅在注册时发出。较早的失败和实时缓存命中不会产生摘要。详情不会添加索引名称或数据库内容。

Slow cron list pages¶

耗时至少一秒的 cron 列表页面会通过其现有日志记录器发出 cron: slow list page，并受文件日志级别约束。结构化记录以 operation: "cron.listPage" 标识操作，并报告 elapsedMs、waitToCallbackMs、callbackMs 和 completionDelayMs，以及可用的 source、matched 和 returned 行数、结果，以及发出方的 pid、threadId 和 isMainThread。快速页面不会发出此类记录。

这些是墙钟时间，而不是 CPU 时间：等待包括调度延迟，回调时间包括所等待的工作，完成延迟涵盖回调结束后的结算。每个 source 页面单独测量。调用方可见性过滤在页面回调内运行；投递预览仍在其外部。存在时保留现有 trace 上下文。发出方标识识别的是日志记录进程/isolate，而不是回调所等待工作的所有者。该诊断不会添加作业标识符、作业内容或请求参数。

Slow cron list requests¶

在 diagnostics.enabled 启用时，耗时至少一秒的 cron.list 处理器会通过 Gateway 日志记录器发出 cron: slow list request。该记录使用现有请求 trace/span，并报告 elapsedMs 以及 setup、listing、projection、可选 previews、response 和 handlerExit 的固定 phaseDurationsMs。未进入的阶段会缺失。

sourcePageMs 和 sourcePageCount 汇总 source-page 调用，包括失败的调用。一旦选定页面，returnedCount 就会出现。对于直接列表，scopeAttemptCount 为零；对于 scoped 列表，为一。可见性过滤、排序、修订计算和分页共享一个加锁的 source 操作。对于 scoped 列表，scopeProcessingMs 是列表时间减去 source-page 时间，涵盖该操作之外的工作。这些组成部分已包含在 listing 阶段中，不得再次加到该阶段上。

有界分支字段为 compact、previewsRequested 和 scopeApplied。previewsRequested 描述所选响应模式，而不是执行是否到达该阶段。handlerOutcome 为 returned 或 threw。对于处理器的响应回调，responseOutcome 为 none、ok、error 或 threw。其 response 阶段测量该同步回调，handlerExit 在处理器自身的清理边界结束。两者都不能证明套接字投递或客户端接收。外层 RPC 诊断保留这些独立结果。

所有持续时间都是墙钟时间，包括 await 和调度，而不是 CPU 时间。快速请求以及禁用诊断的请求不会发出摘要。该记录不会添加作业标识符、内容、查询字符串、目标或错误文本，也不会更改单个慢页面警告或响应负载。

Slow Codex catalog pages¶

在启用诊断和警告日志时，耗时至少一秒的 Codex 目录页面会发出 slow Codex catalog page producer。其现有阶段总计可区分客户端获取、请求等待和页面处理。diagnosticEpoch 和 operationId 标识页面观察；可用时，listOperationId 链接其来源逻辑列表。

controlWaitersV1 是一个 JSON 编码数组，将采样的页面等待关联到物理客户端和 JSON-RPC 尝试。使用 JSON.parse 解码该字符串以读取其元组。它保留前两个和最新两个已完成的 waiter 摘要。controlWaitersOmitted 统计被边界排除的摘要数量。每个条目具有以下位置：

时间为取整的进程本地单调毫秒，可在同一进程内比较。较晚的 waiter 保留原始尝试和可能写入时间。waiter 结果区分 resolved、native-error、timed-out、aborted、authority-rejected、local-failed 和 client-closed。wire 结果为 retained-pending、native-ok、native-error、ingress-rejected、correlation-closed 或 not-written。

可能写入不能证明原生接受。joined waiter 并不意味着发送了另一个请求，超时的 waiter 可能使 wire 尝试保持 pending。页面观察关闭后，不保证后续 wire 结算。这些记录不包含查询、游标、路径、标题、认证数据或原始错误。现有边界仍为 64 个活动观察、每分钟 60 条警告、28 个元数据键和 2,048 字节。缺失或省略的摘要是不可用证据，而不是零活动；持续时间不会归因于原生 CPU 或客户端接收。

控制台捕获¶

CLI 捕获 console.log/info/warn/error/debug/trace，将它们写入文件日志，并仍会打印到 stdout/stderr。

console.trace() 在所有控制台样式中都保留其已脱敏的堆栈，包括强制 stderr 输出。文件捕获会在 trace 级别记录一次，具体受配置的文件日志级别控制。

可独立调整控制台详细程度：

• logging.consoleLevel（默认 info）
• logging.consoleStyle（pretty | json）。未设置时，在 TTY 上输出为 pretty，否则为自动 compact 样式。compact 不再是可设置值。openclaw doctor --fix 会将已存储的值映射为 pretty。

脱敏¶

OpenClaw 会在日志或转录输出离开进程之前屏蔽敏感令牌。该脱敏策略适用于控制台、文件日志、OTLP 日志记录以及会话转录文本输出端。匹配的机密值会在 JSONL 行或消息写入磁盘之前被屏蔽。

OpenClaw 框架会在中间件之后屏蔽已确定的工具结果文本，使其在进入实时模型上下文之前完成处理，包括 exec 输出和工具错误。媒体字节和原始执行参数保持原样；后续重放会复用已屏蔽的结果。模型可见的工具结果文本会保留模糊的来源赋值，例如 token = timeObserverToken。已注册的机密以及显式凭据形式（包括结构化字段、授权头、URL 凭据和已知令牌格式）仍会被屏蔽。直接读取 .env 文件时，会在其内容成为工具结果之前应用更广泛的赋值屏蔽。其他配置和源码读取会保留不透明值。请注册实际机密，而不是依赖键名匹配。其他转录字段和诊断输出端保留广泛的赋值匹配。

• 敏感值脱敏始终启用。
• logging.redactPatterns：正则字符串数组（替代默认字符串列表）。针对表单主体、结构化授权头和裸 AWS 秘密访问密钥的内置结构保护始终生效。
• 使用原始正则字符串（自动 gi），或使用 /pattern/flags 指定自定义标志。
• 匹配项会被屏蔽，保留前 6 位和后 4 位（值长度 >= 18 个字符）。较短的值变为 ***。
• 默认值覆盖常见键赋值、CLI 标志、JSON 字段、bearer 头、PEM 块、流行供应商令牌前缀以及支付凭据字段名（卡号、CVC/CVV、共享支付令牌、支付凭据）。

文件和 JSON 控制台记录会在最终 JSON 编码之前完成屏蔽。规则按顺序作用于解码后的值，然后作用于序列化记录上下文，后续规则会看到先前规则产生的屏蔽。字符串匹配会保留其现有令牌提示，以便后续规则可以匹配这些提示。结构化凭据字段使用完整屏蔽；匹配到的数字、布尔值和 null 会变为 JSON 字符串 "***"。配置自定义模式时，文件记录仍会保留内置凭据模式。

诸如 Control UI 工具调用事件、sessions_history 输出、诊断导出、提供商错误、exec 审批显示以及 Gateway WebSocket 日志等安全边界始终会脱敏。logging.redactPatterns 会添加部署特定的模式。

网关 WebSocket 日志¶

网关以两种模式打印 WebSocket 协议日志：

• 普通模式（无 --verbose）：仅打印“有趣”的 RPC 结果 - 错误（ok=false）、慢调用（默认阈值：>= 50ms）和解析错误。
• 详细模式（--verbose）：打印所有 WS 请求/响应流量。

当 diagnostics.enabled: true 且启用警告日志时，耗时至少一秒的 sessions.list 处理程序和 sessions.subscribe 快照处理程序也会发出 slow session list。operation 字段标识产生该记录的是哪个请求。该记录包括进程/线程标识、请求跟踪以及行计数：selectedRowCount、dirtyRowCount、materializedRowCount 和 reusedRowCount。后两者用于区分本次请求期间刷新的已选行，与请求开始时已驻留的已选行。脏计数描述请求开始时待处理的 owner 工作。

耗时至少一秒的 sessions.messages.subscribe 请求会发出 slow session messages subscribe，并包含 operation、elapsedMs 和 phaseDurationsMs。计时从路由开始，早于处理程序，并将 projectionReadiness、accessFacts、handlerPreparation、retainedReadAdmission、replayPreparation 和 observerCommit 与响应及清理工作区分开来。普通订阅会准备已提交的访问事实，而无需等待显示行刷新；隐身读取保留其精确行准备。审批订阅在确认之前仍会准备并验证权威重放。记录不包含会话键或消息内容。

materialize 阶段衡量等待会话行投影就绪的时间。一旦目录已加载，进行中的目录续订不再阻塞列表或描述：读取使用当前目录，同时其替代项在后台加载，然后行使用新目录刷新。启动时仍会等待第一个目录。保留相同目录内容的续订不会使驻留行变脏。

配置文件和运行注册表发布会刷新其派生显示事实，而无需重新读取会话条目。工作器环境和放置发布仅在下次呈现时刷新所选行的工作器事实。存储的会话写入会发布精确键；广泛的列表通知不会安排全行排空。侧边栏偏好设置、talk.realtime.model 以及其他投影中立的配置提交会保留会话行。代理身份编辑会在呈现时刷新显示事实；存储准入会协调物理代际并保留未更改的行。会话策略、名册、共享以及已采用模型目录变更仍会在列表响应之前刷新受影响的实时行。已归档行在选中之前保持冷状态。

仅转录的行刷新对每个驻留会话使用一秒钟窗口：第一个通知会立即刷新，后续通知会合并为一次尾部刷新。这些待处理通知在该刷新到期之前不算脏行。因此，转录新鲜度最多可能滞后一个窗口；可选预览仍会等待空闲后台回填。元数据、生命周期、目录和拓扑发布仍会立即失效。转录通知不会使父级或子级失效：关系、继承的模型设置和子代理活动拥有自己的元数据或注册表发布。

记录报告阶段总计、同步选择/行时间，以及用于等待共享投影就绪的 yieldWaitMs/yieldCount。这些等待可能包含与其他调用者共享的合并工作。阶段总计包含其等待区间；请勿将详细计数器再次加到这些总计中。handlerElapsedMs 从参数验证之前开始，并排除处理器之前的准入。response 阶段包含同步响应回调。这些是经过时间，不是 CPU 时间或客户端接收证明。不包含查询文本或会话内容。

同一记录包含针对同步工作的当前线程 CPU 测量，精度为毫秒小数：prepareThreadCpuMs、rowThreadCpuMs 和 responseThreadCpuMs。准备阶段涵盖投影就绪后的常驻选择、过滤和排序。行 CPU 包括展示和最终列表构建。两个区间都在测量响应回调之前结束；响应 CPU 排除网络等待。测量在此诊断记录发布或记录之前完成。投影就绪等待、后台物化、穿插的微任务以及 worker CPU 均不包含在内。这些是选定的包含式 CPU 区间，包括同线程原生工作和垃圾回收，不是仅 SQL 的 CPU 或完整请求 CPU 总计。

未访问的测量会被省略。每个请求保留其自身的选择、展示和响应 CPU，而不继承共享后台工作。如果 CPU 计数器读取失败，则省略该请求的所有 CPU 字段；其结果和耗时诊断仍会保留。现有激活状态和一秒警告阈值保持不变，因此缺失的慢记录不会解释更快请求消耗的 CPU。

目录列表还通过现有诊断事件流和 Prometheus 导出器 暴露固定的请求阶段观察。这些包括初始/最终投影就绪、提供者或合并等待，以及同步规划/最终交付线程 CPU。与慢日志不同，当感兴趣的受信任消费者处于活动状态时，这些观察包括低于一秒的请求。它们不会更改警告阈值、启动阶段历史、请求行为或诊断收集设置。

WS 日志样式¶

openclaw gateway 支持按网关的样式开关：

• --ws-log auto（默认）：正常模式为优化模式。详细模式使用紧凑输出。
• --ws-log compact：详细模式下使用紧凑输出（成对的请求/响应）。
• --ws-log full：详细模式下使用完整的逐帧输出。
• --compact：--ws-log compact 的别名。

# optimized (only errors/slow)
openclaw gateway

# show all WS traffic (paired)
openclaw gateway --verbose --ws-log compact

# show all WS traffic (full meta)
openclaw gateway --verbose --ws-log full

控制台格式化（子系统日志）¶

控制台格式化器是 TTY 感知 的，并打印一致、带前缀的行。子系统日志记录器使输出保持分组且易于浏览：

• 子系统前缀 出现在每一行（例如 [gateway]、[canvas]、[tailscale]）。
• 子系统颜色（每个子系统稳定，由名称哈希得到）以及级别着色。
• 当输出是 TTY 时着色，或环境看起来像富终端（TERM/COLORTERM/TERM_PROGRAM）。遵循 NO_COLOR 和 FORCE_COLOR。
• 缩短的子系统前缀：丢弃开头的 gateway/、channels/ 或 providers/ 段，然后最多保留剩余的最后 2 段（例如 channels/turn/execution 显示为 turn/execution）。已知通道子系统（telegram、whatsapp、slack 等）始终折叠为仅通道名称。
• 按子系统的子日志记录器（自动前缀 + 结构化字段 { subsystem }）。
• logRaw() 用于 QR/UX 输出（无前缀、无格式化）。
• 控制台样式：pretty | json（compact 在非 TTY 时自动应用，且不是可设置值）。
• 控制台日志级别 与文件日志级别分开（当 logging.level 为 debug/trace 时，文件保留完整细节）。
• WhatsApp 消息正文 以 debug 级别记录（使用 --verbose 查看它们）。

这使文件日志保持稳定，同时让交互式输出易于浏览。

相关¶

• 日志
• OpenTelemetry 导出
• 诊断导出
• openclaw logs — 从 CLI 通过 RPC 跟踪 Gateway 日志