跳转至

网关日志

面向用户的总览(CLI + 控制界面 + 配置)请参阅 /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 上,它始终使用该 OS tmpdir 回退路径。
  • 活动日志文件在 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 日志导出。转录文本、音频负载、turn id、调用 id 和提供商 item id 绝不会被复制到日志记录中。

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

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

控制界面日志选项卡通过网关(logs.tail)跟踪此文件。CLI 也是如此:

openclaw logs --follow

如果尾部读取观察到活动文件已消失,控制界面会清除其先前记录并跟踪重新创建的文件。缺失文件仍返回空尾部。文件系统读取错误(包括指向目录的日志路径)仍然可见,同时控制界面会保留最后成功读取的记录作为陈旧数据。

Verbose 与日志级别

  • 文件日志完全由 logging.level 控制。
  • --verbose 仅影响控制台详细程度(以及 WS 日志样式)— 它不会提高文件日志级别。
  • 要在文件日志中捕获仅限 verbose 的详细信息,请将 logging.level 设置为 debug 或 trace。
  • 嵌入式运行的 continue_normal 决策记录在 debug 级别。重试、配置轮转、模型回退和错误决策保持警告。
  • Trace 日志还包含选定热路径的诊断计时摘要,例如插件工具工厂准备。请参阅 /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 时间。

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

慢速 cron 列表页面

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

这些是墙钟时间,而非 CPU 时间:等待包含调度延迟,回调时间包含被等待的工作,完成延迟涵盖回调结束后结算的时间。每个 source page 都会被单独测量。调用方可见性过滤在页面回调内部运行;投递预览仍在其外部。现有 trace context 在存在时会被保留。发送方身份标识的是记录进程/isolate,而不是回调所等待工作的拥有者。该诊断不会添加作业标识符、作业内容或请求参数。

慢速 cron 列表请求

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

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

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

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

慢速 Codex 目录页面

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

controlWaitersV1 是一个 JSON 编码的数组,将采样到的页面等待连接到物理客户端和 JSON-RPC 尝试。使用 JSON.parse 解码该字符串即可读取其元组。它保留最先两个和最近两个已完成的等待者摘要。controlWaitersOmitted 统计因上限而被排除的摘要数量。每个条目具有以下位置:

索引 含义
0 页面内控制请求序号
1 该控制请求内的过载尝试序号
2 物理客户端实例 UUID
3 JSON-RPC 请求 id
4 该 wire 尝试内的等待者序号
5 new 或 joined 尝试
6 尝试创建时间
7 首次可能写入时间;在任何写入尝试之前为 null
8 等待者挂接时间
9 等待者结算时间
10 等待者结果
11 等待者结算时观察到的 wire 结果
12 wire 结果观察时间;处于待处理状态时为 null

时间是以进程本地单调毫秒为单位取整,可在同一进程内比较。较晚的等待者会保留原始尝试时间和可能写入时间。等待者结果取值包括 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。

可能的写入并不证明原生端已接受。已加入的等待者并不表示另一个请求已发送,超时的等待者也可能使 wire 尝试保持待处理状态。页面观测关闭后,不保证后续的 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。后两者用于区分本次请求期间刷新的已选行与请求开始时已驻留的已选行。脏计数描述请求开始时待处理的所有者工作。

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

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

并发列表共享元数据准备和已选行物化。已选页面在有限的物化批次之间让出事件循环,包括存储事实已缓存的情况。较长的 materialize 等待本身并不表示事件循环停滞或为每个调用方重复工作。

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

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

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

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

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

chat.send 在授权、输入准入和确认至少花费一秒时,记录 slow chat send <N>ms stage=request。阶段耗时会出现在消息文本中,包括权限、运行准入、附件、持久化和响应。单独的 stage=startup ack=<N>ms 记录会将确认后的准备工作归因于工作区设置、回复初始化、技能准备和创作。worktree 涵盖待处理的工作区创建;普通沙箱就绪仍位于包含式 preparation 内。replyInitialization 包括路由、准入票据等待、工作区引导、媒体处理和会话初始化,直到 prepared-session 回调。初始会话行读取器等待包含在该区间内,而不是单独计时。snapshot 测量 agent run 转录开始读取器准备,嵌套在 preparation 内。启动测量在 agent run 开始时结束,或在 dispatch 退出而未启动时结束。这些记录不包含消息文本或会话标识符。嵌套阶段可能重叠;它们的总和不是请求耗时。启用诊断时,Prometheus 导出器 会为快速和慢速发送记录相同的固定阶段。

目录列表还通过现有诊断事件流和 Prometheus 导出器 暴露固定的请求阶段观察。这些包括初始/最终投影就绪、provider 或合并等待,以及同步规划/最终交付线程 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 查看它们)。

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw