诊断导出
OpenClaw 可以构建用于问题报告的本地诊断 .zip:已脱敏的 Gateway 状态、健康状态、日志、配置结构,以及最近的无 payload 稳定性事件。
在审阅之前,请将诊断包视为机密。Payload 和凭据在设计上会被遮蔽,但该包仍会汇总本地 Gateway 日志和主机级运行时状态。
快速开始¶
打印已写入的 zip 路径。选择输出路径:
用于自动化:
聊天命令¶
所有者可以在任何对话中运行 /diagnostics [note],请求一次本地 Gateway 导出,作为一份可复制粘贴的支持报告:
- 发送
/diagnostics,可附带简短备注(/diagnostics bad tool choice)。 - OpenClaw 会发送前言,并请求一次明确的 exec 审批,该审批会运行
openclaw gateway diagnostics export --json。不要通过全允许规则批准诊断。 - 批准后,OpenClaw 会回复本地包路径、manifest 摘要、隐私说明和相关会话 id。
在群聊中,所有者仍可以运行 /diagnostics,但 OpenClaw 会将导出结果、审批提示以及 Codex 会话/线程明细私下发送给所有者。群组只会看到简短状态通知:审批待处理、私密投递已确认、投递待处理或投递已抑制。待处理投递不会触发另一次私密发送。如果不存在私有的所有者路由,该命令会要求所有者从私信中运行。
当活动会话使用原生 OpenAI Codex harness 时,同一 exec 审批也涵盖 OpenClaw 所知道的 Codex 线程的 OpenAI 反馈上传。该上传独立于本地 Gateway zip,并且仅发生在 Codex harness 会话中。审批提示会说明批准也会发送 Codex 反馈,而不会列出 Codex 会话或线程 id。批准后,回复会列出已发送到 OpenAI 的线程的频道、OpenClaw 会话 id、Codex 线程 id 以及本地恢复命令。拒绝或忽略审批会跳过导出、Codex 反馈上传和 Codex id 列表。
这让 Codex 调试循环更短:在频道中注意到异常行为,运行 /diagnostics,批准一次,分享报告,然后如果你想自行检查线程,就在本地运行打印出的 codex resume <thread-id> 命令。参见 Codex harness。
导出内容¶
summary.md:供支持使用的人类可读概览。diagnostics.json:配置、日志、状态、健康状态和稳定性数据的机器可读摘要。manifest.json:导出元数据和文件列表。- 已脱敏的配置结构和非机密配置详情。
- 已脱敏的日志摘要和最近的已遮蔽日志行。
- 尽力而为的 Gateway 状态和健康状态快照。
stability/latest.json:最新已持久化的稳定性包(如果可用)。
即使 Gateway 不健康,导出仍然有用:如果状态/健康请求失败,本地日志、配置结构和最新稳定性包仍会在可用时被收集。
隐私模型¶
保留:子系统名称、插件 id、提供商 id、频道 id、已配置模式、状态码、持续时间、字节数、队列状态、内存读数、已脱敏日志元数据、已遮蔽操作消息、配置结构以及非机密功能设置。
省略或遮蔽:聊天文本、提示、指令、webhook 主体、工具输出、凭据、API 密钥、令牌、cookie、机密值、原始请求/响应主体、账户 id、消息 id、原始会话 id、主机名和本地用户名。
当日志消息看起来像用户、聊天、提示或工具 payload 文本时,导出仅保留一条消息被省略及其字节数。
WebSocket 断开日志¶
已连接的 webchat 和已认证用户断开连接会在默认 info 级别文件日志中包含 durationMs(以毫秒为单位的连接生命周期)。cause 字段包含 Gateway 记录的关闭原因(如果已知);否则省略。heartbeat-timeout 记录 Gateway 的未收到 pong 判定。它不能证明 ping 到达了远程对端,也不能证明对端导致了传输故障。
心跳超时记录还会在终止前捕获这些事实:
pingWriteState:未观察到写回调时为pending,本地写完成后为completed,写错误后为failed。Pending 不能证明 ping 未发送;completed 不能证明对端已接收。lastPongAgeMs:自上次观察到 pong 以来的单调递增毫秒数,未观察到 pong 时省略。bufferedBytes:超时决策时的本地 WebSocket 聚合缓冲,而不是单个 ping 的投递状态。
命令通道诊断¶
当排队任务在等待至少其警告阈值(通常为 2 秒)后启动时,会发出 [diagnostic] lane wait exceeded。waitedMs 测量该等待时间;queueAhead 和 activeAhead 描述入队时的竞争情况,而 activeNow 和 queueBehind 描述任务启动时的通道状态。
该警告和 lane task error 都会在调用方提供时包含入队时的 taskKind、sessionKey、runId 和 requesterSessionKey。这些是结构化日志字段,并出现在同一控制台行中,因此无需单独的注册表查找即可归因子代理队列竞争。嵌入式运行会提供 spawn、turn 或 cron 作为任务类型;其会话键标识等待或失败的会话,其请求者键在存在时是生成父级。排队的计划 cron 运行会提供其已接受的运行 ID。未知字段会被省略。身份是诊断溯源,而非权限,并且不会改变准入、排序或警告阈值。
稳定性记录器¶
当诊断启用时,Gateway 默认会记录一个有界的、无 payload 的稳定性流。它捕获操作事实,而不是内容。
Gateway RPC 诊断会保留精确的核心方法和已注册插件方法名称,
包括 node.invoke.result 和 workboard.cards.list;未注册的请求
名称会归入 other(专用 worker ingress 使用 unknown)。方法
标签集合由已注册目录加上这些回退标签限定,而
不是由调用方提供的名称限定。Prometheus exporter 在计数器、gauge 和直方图之间保留共享的 2,048 个样本
上限;一个被完整观察的方法最多使用
五个样本。监控 openclaw_prometheus_series_dropped_total 以发现不完整
覆盖。有关计时语义,请参阅 Prometheus 指标。
现有的诊断心跳 debug 日志包含 nextWakeAtMs,即 Gateway 调度器中最早的
待处理唤醒时间,以毫秒为单位的 Unix 时间戳
(如果没有待处理唤醒,则为 none)。逾期的诊断心跳在睡眠后只运行一次;
调度器不会重放错过的 tick。
同一心跳还会在事件循环或 CPU 看起来饱和时采样存活状态,
发出带有事件循环延迟、
事件循环利用率、CPU 核心比率、活动/等待/排队会话数、
当前启动/运行时阶段(如果已知)、近期阶段跨度以及
有界工作标签的 diagnostic.liveness.warning 事件。当
工作处于等待或排队状态、活动工作与持续的事件循环
延迟重叠,或 Gateway 报告至少 60 秒的持续性能下降时,
这些事件会成为 Gateway warn 级别日志行;
否则它们以 debug 级别记录。即使
没有活动的工作被跟踪,Gateway 的持续性能下降也可能发出警告。其他空闲存活状态采样仍保持为诊断事件,
不会升级为警告。
启动阶段会发出带有实际经过时间和
整个进程 CPU 计时的 diagnostic.phase.completed 事件,包括 worker 和原生线程。阶段 CPU 可能
包含该阶段之外的并发工作;它不是独占归因。
阶段和存活状态事件中的 cpuCoreRatio 以核心当量
衡量,并且可以超过 1。请参阅
CPU 压力与事件循环延迟。
持续时间至少一秒的 sessions.patch 和 sessions.patchMany 调用会添加
一条 info 级别的 slow session patch 记录,即使诊断已禁用。
消息包含总经过毫秒数、方法以及固定阶段
持续时间,例如 slow session patch 1176ms method=sessions.patch catalog=1100ms response=20ms。
替换快照使用元数据读取器进行有界的精确键选择,
并使用维护读取器进行更大或标签所有者选择,独立于
transcript-history 读取器。快照时间包括 worker 准备和读取。
阶段区分生命周期准入、快照读取、目录准备、
投影、提交、运行时确认、效果和响应工作。将
计时信息保留在消息中可使其在省略结构化
字段的传输中可见。记录在可用时继承请求的诊断跟踪,并且不包含
任何 patch 值或会话键。重复的阶段访问会累加到每个阶段的总计中。
并行和嵌套阶段可能重叠,因此它们的总计既不是请求时间的独占
分解,也不是 CPU 测量。
会话协作读取会向感兴趣的诊断监听器发出排队的 diagnostic.phase.completed 事件。session.members.list 和
session.members.listEvidence 区分 profiles、evidence 和 projection
等待;session.discussion.info 和 session.discussion.open 报告 provider
时间,包括远程 provider 请求。阶段名称使用方法作为其
前缀,并且不包含会话键或响应数据。成员资格证据使用
现有的 projection worker lane,因此完整 transcript 读取不会阻塞它。
成员资格 projection 阶段会准备创建者选择元数据,而无需
等待无关的会话显示行或 worker-placement 详情。
evidence 阶段在一个快照中读取成员资格和当前管理元数据。
在启用诊断和警告日志时,持续时间至少一秒的 sessions.create 调用会发出 slow session create。其 elapsedMs 和
phaseDurationsMs 区分请求准备、准入、目标发现、
worktree 准备、行快照和投影、transcript 初始化、
writer 准入、提交、发布、初始轮次分发以及响应工作。
这些是经过时间,包括等待,具有固定阶段名称,并且不包含会话
键或请求值。worktree 准备仅测量响应之前所需的工作;已经延迟到初始轮次的配置保留在该
轮次的生命周期中。
托管 worktree 准备在返回或失败时发出一条 info 级别的 managed worktree preparation
记录。kind=managed 涵盖 checkout 创建;
kind=sandbox 涵盖通过后端就绪的托管 guest 投影,
包括 workspace/skill 布局和容器配置。durationMs 测量
整个操作。phaseDurationsMs 归因于分配准入、checkout、
setup 执行、模板准备和应用、快照捕获、每个
方向的同步、workspace 布局以及容器启动。阶段包括嵌套工作
和异步等待,因此不要将它们加到总计中。未进入的阶段
不存在。对于现有投影,template 为 warm、cold、unavailable 或 reused;记录不包含仓库路径、会话键或 setup 输出。
启用诊断时,同一观察结果会馈送到
worktree 准备直方图。
两条相关的 info 级别记录有助于归因慢速 worktree 清理:
slow managed worktree removal 区分分配准入、回调工作
和最终结算,回调内部包含准备、快照、checkout 移除以及主体
最终化的计时;slow Git ref mutation 区分目录解析、
队列等待和排队工作。两者都需要诊断和 info 级别日志,
仅在持续时间至少一秒的操作结算后发出,并且具有
每个运行时 isolate 每分钟 60 条记录的独立固定预算,带有
omittedObservations 计数。它们保留固定标量字段和现有跟踪,
不添加私有路径或新身份。它们的经过时间间隔可以嵌套
在 worktreeCleanup 内部,并且包括异步等待;它们不是 CPU 或
单个子命令计时。有关字段和缺失记录限制,请参阅 慢速 worktree 清理。
SQLite 会话写入警告还会分别记录 queueWaitMs、writerExecutionMs 和 completionDelayMs。它们分别测量写入器启动前的时间、在写入器通道内工作和等待的时间,以及执行后其调用方恢复前的时间。写入器执行时间不是 SQLite 事务锁持有时间;原生事务锁等待和持有警告仍然分开。在进入写入器之前被拒绝的写入会省略这三个字段。此分解位于文件日志中,而不是聚合的 Gateway RPC Prometheus 直方图。
这些警告包含写入器的 pid、Node threadId 和 isMainThread。回收回调还会记录其 reclamationKind,并且在创建 Worker 时,记录其捕获的 workerThreadId。在同一进程生命周期内,将警告的 pid 和 workerThreadId 与 agent-database-open 警告的 pid 和 threadId 匹配,以识别所等待的 Worker。这建立了关联关系,而不是 CPU 归因或 Worker 生命周期的分解。缺少 Worker ID 并不能证明工作运行在主线程上。
停滞的嵌入式运行诊断会在最后一次桥接进度看起来是终态(例如原始响应项或响应完成事件)但 Gateway 仍认为嵌入式运行处于活动状态时,标记 terminalProgressStale=true。
检查实时记录器:
openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --json
在致命退出、关闭超时或重启启动失败后,检查最新的持久化包:
从最新的持久化包创建诊断 zip:
当事件存在时,持久化包位于 ~/.openclaw/logs/stability/ 下。
CPU 性能分析¶
具有 operator.admin 权限的操作员可以请求 Gateway 主 JavaScript 隔离区的一次内存内性能分析:
该 RPC 支持 Node 和 OpenClaw 的 Bun 运行时。它请求以 10 ms 间隔进行五秒采样,不打开调试器端口,也不发送进程信号。调用方断开连接或 Gateway 关闭会取消捕获并运行性能分析器清理。重叠请求会失败,而不是排队。性能分析不会写入磁盘,也不会包含在诊断导出中。
结果包含 V8 CPU 性能分析格式的 profile、requestedDurationMs、actualDurationMs、startBlockedMs、samplingIntervalMicros、redactedNodeCount,以及 sampleLossCount: null,因为原生性能分析器不暴露显式的丢失样本计数。Node 采样 V8;Bun 采样 JavaScriptCore,并返回相同的性能分析格式。完整结果限制为 1 MiB;更大的性能分析会失败,而不会截断节点或样本。OpenClaw 包内的代码位置使用 openclaw: 路径;Node 内置位置使用 node: 路径。外部路径、eval 标签和其他无法识别的名称会被脱敏。在已识别位置处的有界代码符号名称会被保留;其语法并不能证明计算出的名称是公开的。共享性能分析之前请先审查它。图边、原生带符号脚本 ID 和样本顺序保持完整。V8 可能按时间戳乱序发出样本,因此保留带符号的时间差,以便性能分析查看器重建时间戳并对样本排序。
当事件循环被阻塞时,采样可能持续超过请求的间隔。响应限制不会限制该延迟期间运行时的内部分配。性能分析样本描述的是该隔离区,而不是所有进程线程,也不是精确的按函数 CPU 核算。
在 Node 上,同步启动 CPU 性能分析会扫描 V8 堆以构建其代码映射。在大型 Gateway 上,每次捕获都可能在常规采样开始前阻塞主事件循环数秒(在 3 GB 堆上已观察到约 3.5 秒)。保持检查器域启用或从 Worker 发送请求都无法避免该主隔离区工作。startBlockedMs 使用单调时钟测量同步启动调用,排除 Promise 等待、设置、采样时间和停止/清理。在分析单个捕获时,用它来归因捕获导致的停滞;不能从聚合事件循环最大值或百分位数中减去。该测量报告成本;它不会阻止或中断原生停滞。
该 RPC 会拒绝已知的活动检查器监听器、性能分析标志、覆盖率收集或任何活动的 Node 跟踪,包括非 CPU 类别。在请求性能分析之前停止跟踪,并在捕获期间不要启用它:V8 可能在此 RPC 清理结果之前将原始性能分析块发送到现有的跟踪写入器。在 Bun 上,该 RPC 还会拒绝非空的 BUN_INSPECT 或 BUN_INSPECT_CONNECT_TO 设置,这些设置可能会激活调试,而不会出现在 inspector.url() 中。该 RPC 无法发现任意的第三方进程内检查器会话;不要将其与另一个调试器、性能分析器、跟踪器或覆盖率所有者一起运行。不可用响应会指明原因以及清理是否失败。如果清理状态仍不确定,则拒绝进一步捕获;该 RPC 永远不会自动重启 Gateway。
完整堆快照¶
具有 operator.admin 权限的操作员可以显式捕获 Gateway 的主 JavaScript 隔离区,包括请求之前分配的对象:
openclaw gateway call diagnostics.heapSnapshot --params '{"reason":"retention baseline"}' --timeout 180000 --json
该 RPC 支持 Node 和 OpenClaw 的 Bun 运行时,并写入 V8 兼容的快照 JSON。它只接受可选的 reason(最多 256 个字符),并在捕获前的警告中记录。无需配置开关。它以仅所有者可访问的文件权限写入 <state>/diagnostics/heap-<timestamp>.heapsnapshot,并返回 path、sizeBytes、heapUsedBefore、heapUsedAfter(字节)和 elapsedMs(原生捕获墙钟时间)。快照内容永远不会通过 WebSocket 传输,也不会进入诊断导出。Worker 隔离区被排除。
在安静窗口内获取快照。 3 GB 堆快照可能阻塞主
线程数十秒。V8 在捕获期间可能需要大约两倍于堆的内存;
足够的内存和磁盘空间仍由操作员负责。
该 RPC 拒绝超过 6 GiB 的堆、重叠的 CPU/堆捕获,以及原生尝试结束后
60 秒内的另一个快照。它还共享剖析 RPC 对已知调试器、
剖析标志、覆盖率和活动 Node 跟踪的拒绝。这些准入保护不会施加
硬性时长、输出大小或内存限制:同步 writeHeapSnapshot()
一旦开始,就不能被超时、断开连接或关闭中断。
客户端超时并不意味着捕获已停止;重试前请检查主机目录。
捕获后,诊断所有者会禁用堆分析器并
断开其检查器会话,释放运行时保留的快照元数据。
在 Node 中,这还会释放 V8 的对象 ID 映射和对象移动跟踪,因此后续垃圾
回收不会继续支付快照跟踪成本。
失败的捕获会在可能时删除部分文件;cleanupFailed
报告分析器清理或文件删除是否失败。
快照是未脱敏的,可能包含凭据、提示词和私密 消息。将其保留在主机上,单独审查任何传输,并在 分析后手动删除。成功快照会保留直到被删除;没有 自动快照收集或保留任务。
RPC 快照在每次捕获后重置对象 ID。使用独立对象 ID 空间比较独立 RPC 快照:
此模式按构造函数/类比较保留字节,并分别报告每个快照中最大的
保留对象及其路径。对象 ID 属于
单个快照:相等的 ID 不能证明某个对象在两次
捕获之间存活。使用 --json 时,before 和 after 各自包含自己的 dominators
和 retainers;classes 包含跨快照总计。
对于来自同一持续附加调试器、位于隔离
分析进程中的两次捕获,省略 --independent-ids。这会保留对象 ID 匹配并
报告各个支配者的变化。支配者是所有
强根路径都经过的对象。此比较要求同一 isolate 的对象 ID
映射在两次捕获之间保持活动。
该工具流式读取输入,并需要与对象图成比例的内存;请在 内存充足的分析主机上运行大型比较。弱边和捷径边 被排除。类总计将同一类的嵌套实例只计一次;不同 类之间的总计可能重叠。使用 Chrome DevTools 查看交互式 保留路径以及 V8 特定的弱引用/ephemeron 语义;该脚本是 强边图摘要。将输出视为敏感信息:它包含未脱敏的 堆名称。
使用 --top 40 --max-depth 60 调整报告的对象数量和路径
深度。--node <id> 在任一模式下选择后续快照中的特定
对象。最短根路径显示可达性;单独的支配者链
识别该图中的独占保留。
从已构建的源代码检出中,隔离的合成工作负载可以在不连接现有 Gateway 的情况下收集一对 独立 RPC 快照:
node --import ./scripts/tsx.mjs scripts/gateway-heap-rig.mjs \
--root ../heap-rig/baseline --minutes 180 --snapshot-minutes 60,180 \
--rpc-interval-ms 440 --turn-interval-ms 5000
在内存足以容纳快照的专用主机上运行此命令。它会启动
dist Gateway 和本地模拟模型服务器,使用回环端口 19548–19550,
在两个代理中播种 2,000 个具有 32 KiB 历史的会话,并驱动十个
重连的 Control UI WebSocket 客户端。工作负载轮询会话、历史、
模型和 cron API,并发送带有 8 KiB 回复的模拟 chat.send 回合、Code
Mode 调用、子代理、已上传工件预览以及手动触发的 cron
任务。终端回执、持久化回复、工件预览和 cron 历史
必须与合成测试数据匹配。合成目录插件用于验证 Gateway
投影和发布所有权;它不会模拟原生提供方的
缓存或远程节点传输。
八个文本会话保留对话历史。工具会话在 32 个槽位中轮换,归档队列最多保留 64 个变更会话。生命周期 变更使用观察到的会话 ID。证据记录这些群体 和回合数,以便将有意历史增长与泄漏 状态区分开。快照会等待已接受的回合和 RPC 稳定,并在两次 捕获中保持相同客户端连接。
根目录必须是新的。每个合成工作区都有自己的空 Git 仓库, 使 Git 基线发现远离 rig 的活动 SQLite 文件。状态、 日志、十秒样本、十分钟堆最小值和快照都保留在 根目录下。rig 记录成功 RPC 数量,并在完成、 中断或工作负载检查失败时停止其子进程。证据保留以供分析。
使用另一个 Node 二进制文件和相同脚本及设置作为运行时对照;
每次运行选择另一个根目录和三个端口块。原始样本包含
分配变更;比较快照的 heapUsedAfter 锚点以查看 GC 后增长。
分析 rig 的 RPC 快照对时使用 --independent-ids。
采样堆配置¶
具有 operator.admin 权限的操作员可以在 Gateway 的主
JavaScript isolate 中采样分配,而无需获取整个堆快照:
openclaw gateway call diagnostics.heapProfile --params '{}' --timeout 30000 --json
openclaw gateway call diagnostics.heapProfile --params '{"durationMs":10000,"samplingIntervalBytes":32768}' --timeout 45000 --json
openclaw gateway call diagnostics.heapProfile --params '{"includeObjectsCollectedByMajorGC":true,"includeObjectsCollectedByMinorGC":true}' --timeout 30000 --json
该 RPC 支持 Node 和 OpenClaw 的 Bun 运行时。默认值为五秒和平均采样间隔
32 KiB。durationMs 和 samplingIntervalBytes 必须是正整数。当
两个收集标志都为 false 时,时长上限为 15 分钟(900,000 毫秒)。
启用任一收集标志会将时长上限保持为 30 秒;
低于 4 KiB 的间隔会被限制为 4 KiB。更小的间隔
会以更高的 CPU 和内存成本收集更多样本。选择比请求捕获更长的
CLI 超时。关键内存警告指向此 RPC;
压力永远不会自动启动捕获。
可选布尔值 includeObjectsCollectedByMajorGC 和
includeObjectsCollectedByMinorGC 均默认为 false。同时启用两者以保留
窗口期间被回收对象的样本,并归因瞬时分配抖动。保留已回收样本可能会增加分析器的内存使用。
对于保留归因,请保持两个收集标志为 false(默认值),并使用更长的窗口和更粗的采样间隔:
openclaw gateway call diagnostics.heapProfile --json --timeout 930000 --params '{"durationMs":900000,"samplingIntervalBytes":262144}'
将 profile.head 中每个节点的 selfSize 读取为在窗口期间分配且在停止时仍然存活的估算字节数。这些是分配位置,而不是保留路径或捕获前分配的对象。930,000 毫秒的 CLI 超时在请求窗口之外额外提供 30 秒用于设置和清理;事件循环停顿可能需要更多时间。断开连接、权限撤销或 Gateway 关闭会取消采样,并在清理后丢弃部分剖析结果。
结果包含实际经过的 durationMs、samplingIntervalBytes、
includeObjectsCollectedByMajorGC、includeObjectsCollectedByMinorGC、
heapUsedBefore、heapUsedAfter、rssBefore、rssAfter(所有内存值均以字节为单位)、redactedNodeCount、unattributedSampleCount、unattributedSampleBytes
以及 truncated。如果存在,profile 包含经过脱敏的 V8 格式采样树和样本。每个节点的 selfSize 是该调用位置的估算分配字节数;对其后代求和可得到包含式字节数。样本通过 nodeId 链接到节点。
heapSpacesBefore 和 heapSpacesAfter 包含主 isolate 的 node:v8 堆空间统计信息,其边界与内存读数相同:space_name、
space_used_size、space_size、space_available_size 和 physical_space_size
(大小以字节为单位)。按名称比较条目,以定位 Node 上 old、large-object、code 或其他空间的增长。Bun 将其 JavaScriptCore 堆报告为 old_space;
其他以 V8 命名的空间为零,而不是单独的 JavaScriptCore 区域。
在 Node 上,Prometheus exporter
还会从现有的 30 秒诊断内存心跳中暴露 openclaw_heap_space_bytes{space="<space_name>",stat="used|size|available|physical"},
具有相同的空闲样本抑制,且从不按每次抓取执行。名称来自 V8 的有限空间集合,
包括未来 V8 版本添加的空间;每个空间在 exporter 现有系列上限下贡献四个 gauge。
堆和 CPU 配置文件将依赖帧标记为 [dep:<pkg>],URL 为
node_modules/<pkg>,包括作用域包和 pnpm 布局;符号、
版本、文件名和绝对路径保持隐藏。带有查询或片段标记的 URL 仍会被脱敏。脚本 ID 为 0、
URL 为空且行号为负数的帧使用 [native],但已知的 V8 引擎标签除外,例如 (root)。此桶标识缺失的 JavaScript 源归因,而不是特定的原生分配器或外部 Buffer 字节。其他
无法识别的帧仍标记为 [redacted];redactedNodeCount 不包括依赖和原生标签(具有隐藏去优化原因的 CPU 节点仍会计入)。
V8 可能会采样在构建其自身剖析结果时发生的分配,此时调用位置已被转换到返回的树中。没有匹配树节点的样本会被省略,并报告在 unattributedSampleCount 和
unattributedSampleBytes 中;原生树大小保持不变。当省略此类引用,或由大小受限的摘要替换树时,truncated 为 true。
完整结果上限为 1 MiB。当树和样本超过该上限时,
truncated 为 true,并且 summary 替换 profile。摘要条目合并相同的调用栈,按叶优先顺序保留最多八帧,并包含
selfBytes、包含式 totalBytes 以及 count(这些位置的采样分配数量,而不是精确的对象数量)。条目按 totalBytes 排序,然后按 selfBytes 排序;排名较低的条目会被省略以符合上限。包含式总计在不同调用者之间重叠,因此不要将它们相加。从较大的 selfBytes 开始,并检查调用栈以识别分配代码。
采样比整个堆快照开销更低,但仍然只是近似值。默认采样模式会排除在捕获结束前被回收的对象;启用两个收集标志以包含这些样本。两种模式都不是对每个分配的精确清单,也不包括捕获前分配的对象。 原生分配、外部缓冲区、其他 isolate 和其他进程线程不会被归因,因此采样字节数不一定能解释完整的 RSS 变化。
堆和 CPU 捕获共享一个 inspector 所有者:重叠的调用会失败,而不是排队。两者都使用上述相同的脱敏、运行时冲突检查、取消和清理规则。不会打开监听器,也不会写入文件。 事件循环停顿可能会延长捕获持续时间,并且响应上限不会限制运行时内部采样内存。共享前请审查保留的代码符号名称。
有用的选项¶
openclaw gateway diagnostics export \
--output openclaw-diagnostics.zip \
--log-lines 5000 \
--log-bytes 1000000
| 标志 | 默认值 | 描述 |
|---|---|---|
--output <path> |
$OPENCLAW_STATE_DIR/logs/support/openclaw-diagnostics-<timestamp>-<pid>.zip |
写入特定的 zip 路径(或目录)。 |
--log-lines <count> |
5000 |
要包含的最大脱敏日志行数。 |
--log-bytes <bytes> |
1000000 |
要检查的最大日志字节数。 |
| 标志 | 默认值 | 描述 |
|---|---|---|
--url <url> |
- | 用于状态/健康快照的 Gateway WebSocket URL。 |
--token <token> |
- | 用于状态/健康快照的 Gateway token。 |
--password <password> |
- | 用于状态/健康快照的 Gateway 密码。 |
--timeout <ms> |
3000 |
状态/健康快照超时。 |
--no-stability-bundle |
off | 跳过持久化稳定性 bundle 查找。 |
--json |
off | 打印机器可读的导出元数据。 |
禁用诊断¶
诊断默认启用。要禁用稳定性记录器和诊断事件收集:
禁用诊断会减少 bug 报告详情;它不影响正常的 Gateway 日志记录。
内存压力警告从已测量限制的 80% 开始;严重压力从 90% 开始。主线程的 V8 heap_size_limit 是主要信号(heap_threshold)。每个新的 worker 样本都会与该 worker 自身的 V8 限制(worker_heap_threshold)进行比较,包括进程范围的堆标志覆盖。RSS 包含所有 worker 和原生分配,因此 rss_threshold 使用物理 RAM 与进程/cgroup 内存约束中的较小值,独立于 V8 堆限制。未知限制会被省略;Bun 的兼容性堆元数据不被视为 V8 限制。仅 RSS 增长并不表示存在压力。
警告和严重日志行以及诊断事件会保留测量得到的 usedBytes、limitBytes 和 thresholdBytes;worker 压力还会标识 workerThreadId。检测器不会执行文件系统扫描、强制主线程 GC 或 OOM 前快照。openclaw_memory_bytes 保持不变。
持久数据库 worker 会在已完成操作后,当其已用堆自上次空闲收集以来增长 32 MiB 时进行垃圾回收。这使用运行时的本地检查器收集支持;报告该方法不可用的运行时将跳过空闲收集。在 Node 上,SQLite、history、transcript 和 reclamation worker 会请求 512 MiB 的 V8 旧生代限制;显式的进程范围 --max-old-space-size 会覆盖 Node 的 worker 资源限制。这些限制不涵盖原生分配或已传输缓冲区。内存诊断按脚本和线程 ID 报告每个被采样的直接 worker,包括其堆、测量得到的堆限制和外部内存。Task worker 还会从其 isolate 内部发布 ArrayBuffer 字节数;ArrayBuffer 已经包含在外部内存中,因此不要将这些值相加。其他直接 worker 使用原生堆统计信息,并使 ArrayBuffer 字节数不可用。嵌套 worker 不在父注册表的覆盖范围内。
workerHeapSampledCount 和 workerArrayBuffersSampledCount 显示相对于 workerCount 的覆盖情况。对于直接 worker,workerMemoryCoverage 为 complete、partial 或 unavailable。在首次采样之前或样本过期之后,缺失的字节数会被省略,而不是报告为零;workerMemoryMissing 会标识等待中、过期或不可用的 worker。样本在 60 秒后过期。采样从不等待繁忙的 worker,并且每个传输最多保持一个未决请求。如果 worker 无法处理 port 消息,原生 V8 中断仍会刷新其堆和外部计数器;ArrayBuffer 覆盖情况在 worker 响应之前保持不可用。内存压力警告包含这些计数器以及外部内存限制注意事项;Node 不会为外部/原生分配提供 worker 限制。
严重内存压力会通过其现有清理所有者回收空闲 worker,即使诊断事件收集被禁用也是如此。警告不会回收 worker。回收请求是异步的,会跳过活动工作,并保持原生 close/checkpoint 操作不在主线程上。活动操作保留其保管权,并且通常在 30 分钟的数据库保留窗口在使用后恢复。存储数据、数据库架构或更新过程均不发生变化。
当任务池在五分钟内重新创建已因空闲而回收的 Worker 时,它会保持一个替换 Worker 处于热状态,持续五分钟无活动。其他槽位保留其正常空闲超时。Node Code Mode 同样最多保留一个已完成 Worker 五分钟,仅当其运行时入口和堆限制匹配时才会复用。热任务 worker 仍会就地收集已释放的负载;严重压力、取消、轮换和关闭保留其现有清理路径。无需任何配置设置。
RPC 响应大小和堆变化¶
Prometheus exporter 会为每个被 WebSocket 发送方接受的编码 JSON 响应帧记录 openclaw_gateway_rpc_response_bytes(UTF-8 字节,不包括传输帧/压缩),并使用从 1 KiB 到 64 MiB 的 2 的幂次桶。慢响应日志行包含同一帧的 bytes=;它始终表示编码后的响应字节,绝不表示堆分配或独占窗口样本。
对于 sessions.list,响应日志行和 slow session list 记录还包括 source、rowMode(compact 或 full)、limit、offset 和 filterKind。调用方来源是有界的 Control UI 标签或 unspecified;过滤类型包含参数名称,绝不包含搜索文本、身份或路径。优化的 WebSocket 日志还会记录至少 200 KiB 的快速 sessions.list 响应。指标标签保持不变。
openclaw_gateway_rpc_handler_heap_delta_bytes 会在处理器执行前后立即采样主线程的
process.memoryUsage().heapUsed。只有当该处理器在其整个生命周期内(包括 await)都是唯一处于活动状态的 RPC 处理器时,才会发出一个样本。任何重叠都会丢弃整个样本,即使另一个处理器先结束。普通、专用 worker-connection 以及进程内 RPC 处理器共享这一边界。准入、排队、被拒绝的请求以及 worker 线程堆均被排除。
openclaw_gateway_rpc_handler_heap_delta_exclusive_total{method} 统计被采样的处理器数量。将其增量与同一方法的 openclaw_gateway_rpc_handler_seconds_count 进行比较,以查看覆盖率。重叠的处理器不会贡献堆样本,也不是零;持续并发可能导致某个方法没有任何样本。被采样的子集更偏向较短的处理器和较安静的时段。
这些是有符号的堆变化量,而不是每个处理器的分配总量。后台工作、响应编码和 GC 仍会影响独占窗口。GC 通知是异步的,因此样本不会经过 GC 过滤,并且可能为负值。请使用桶计数或分位数;有符号的 _sum 可能会减小,因此对该总和使用 rate() 无效。不要跨方法求和来估算分配吞吐量。两个直方图都使用已注册的方法标签和现有导出器上限,无需新增配置;已禁用或未关注该指标的诊断会跳过堆采样。
相关¶
- 健康检查
- Gateway CLI
- Gateway 协议
- 日志记录
- OpenTelemetry 导出 - 用于将流式诊断发送到收集器的独立流程
- Codex harness 运行时 - Codex harness 的运行时边界、权限和诊断
- 诊断标志 - 用于为单个子系统开启额外日志的命名标志,而不会全局提高
logging.level
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw