古法编程

Appearance

如果你需要给 OpenClaw Gateway 提交 bug 报告，可以使用 openclaw gateway diagnostics export 命令生成一份本地诊断 zip 包。它包含消毒后的 Gateway 状态、健康检查、日志摘要、配置结构以及最近的稳定性事件，但不会包含聊天文本、API 密钥或凭证。你可以在终端运行该命令，也可以在聊天中发送 /diagnostics 让 Gateway 自动执行导出（需要明确授权）。诊断包默认包含稳定性记录，但内存压力快照默认关闭，须手动开启。

OpenClaw 诊断报告怎么生成？导出 zip 包步骤 ​

OpenClaw 可以将消毒后的 Gateway 状态、健康检查、日志、配置结构以及近期稳定性事件打包成一个本地诊断 zip 文件，用于 bug 报告。请将生成的诊断包视为敏感文件，在审查之前不要公开分享。虽然它设计为省略或涂抹掉有效载荷和凭证，但仍会汇总本地的 Gateway 日志和宿主机的运行时状态。

快速开始 ​

直接在终端运行：

bash
openclaw gateway diagnostics export

命令会输出生成的 zip 文件路径。如果你想指定输出位置：

bash
openclaw gateway diagnostics export --output openclaw-diagnostics.zip

用于自动化时，可以加 --json 参数：

bash
openclaw gateway diagnostics export --json

在聊天中请求诊断（/diagnostics） ​

当 bug 发生在真实对话中时，你可以直接在聊天窗口中使用 /diagnostics [备注] 指令，让 Gateway 生成一份可粘贴的报告。操作流程如下：

  1. 发送命令：在出现问题的那条会话中，发送 /diagnostics。如果需要，可以加一句简短备注，例如 /diagnostics 工具选择错误。
  2. 授权执行：OpenClaw 会返回一个诊断摘要，并请求一次明确的执行授权。这次授权会执行 openclaw gateway diagnostics export --json 命令。不要通过允许所有规则来批准诊断授权。
  3. 获取报告：授权通过后，OpenClaw 会回复一份可粘贴的报告，其中包含本地诊断包路径、清单摘要、隐私说明和相关会话 ID。

在群聊中，只有群主可以运行 /diagnostics。不过 OpenClaw 不会把诊断详情发回公共聊天。它会通过私密的授权通道向群主发送摘要、授权提示、Gateway 导出结果以及 Codex 会话/线程清单。群聊里只会收到一条简短提示，告知诊断流程已通过私密方式发送。如果 OpenClaw 找不到群主的私密通道，命令会失败并提示群主从私聊中运行。

当当前 OpenClaw 会话使用的是原生 OpenAI Codex harness 时，执行授权还包括向 OpenAI 上传 Codex 运行时线程的反馈。这个上传与本地 Gateway zip 是分开的，仅出现在 Codex harness 会话中。授权前，提示会说明批准诊断也会发送 Codex 反馈，但不会列出具体的 Codex 线程 ID。授权后，聊天回复会列出被发送到 OpenAI 服务器的渠道、OpenClaw 会话 ID、Codex 线程 ID 以及本地恢复命令。如果你拒绝或忽略授权，OpenClaw 不会执行导出、不会发送 Codex 反馈、也不会打印 Codex ID。

这样一来，常见的 Codex 调试流程就很短了：在 Telegram、Discord 或其他渠道发现异常 → 发送 /diagnostics → 授权一次 → 把报告分享给支持团队 → 如果想自己检查原生 Codex 线程，可以在本地运行终端打印出的 codex resume <thread-id> 命令。详细检查方法见 Codex harness 本地检查。

诊断包包含什么 ​

生成的 zip 包含以下文件：

  • summary.md：面向支持人员的概览说明。
  • diagnostics.json：配置、日志、状态、健康和稳定性数据的机器可读摘要。
  • manifest.json：导出元数据和文件列表。
  • 消毒后的配置结构和非机密配置详情。
  • 消毒后的日志摘要以及最近涂改后的日志行。
  • 尽力获取的 Gateway 状态和健康快照。
  • stability/latest.json：最新的持久化稳定性事件包（如果有）。

即使 Gateway 处于不健康状态，导出也仍然有用。如果 Gateway 无法响应状态或健康请求，本地的日志、配置结构和最新稳定性事件包仍然会被收集（如果可用）。

隐私模型 ​

诊断包设计为可分享的。导出会保留有助于调试的运营数据，例如：

  • 子系统名称、插件 ID、Provider ID、渠道 ID 和配置模式
  • 状态码、耗时、字节数、队列状态和内存读数
  • 消毒后的日志元数据和涂改过的运营消息
  • 配置结构和非机密功能设置

导出会省略或涂改以下内容：

  • 聊天文本、提示、指令、Webhook 主体和工具输出
  • 凭证、API 密钥、令牌、Cookie 和机密值
  • 原始请求或响应主体
  • 账户 ID、消息 ID、原始会话 ID、主机名和本地用户名

如果某条日志消息看起来包含用户、聊天、提示或工具有效载荷文本，导出只会保留一条“消息已省略”的记录以及其字节数。

稳定性记录器 ​

当诊断功能启用时（默认启用），Gateway 会默认记录一个有限大小、不含有效载荷的稳定性数据流。它只记录运营事实，不记录内容。

同一个诊断心跳还会在 Gateway 持续运行但 Node.js 事件循环或 CPU 看起来饱和时记录存活样本。这些 diagnostic.liveness.warning 事件包含事件循环延迟、事件循环利用率、CPU 核心比率、活跃/等待/排队会话数、当前启动/运行时阶段（如果已知）、最近的阶段耗时以及有限数量的活跃/排队工作标签。空闲样本维持在 info 级别的遥测中。只有在有工作正在等待或排队，或者活跃工作与持续的事件循环延迟重叠时，存活样本才会成为 Gateway 的警告。在健康后台工作中出现的瞬时最大延迟峰值会留在 debug 日志中，不会因此重启 Gateway。

启动阶段还会发出 diagnostic.phase.completed 事件，包含墙上时钟和 CPU 耗时。对于卡住的嵌入式运行诊断，如果最后一条桥接进度看起来已经终结（例如原始响应项或响应完成事件），但 Gateway 仍认为该嵌入式运行是活跃的，则会标记 terminalProgressStale=true。

检查实时记录器：

bash
openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --json

查看在致命退出、关闭超时或重启启动失败后最新的持久化稳定性事件包：

bash
openclaw gateway stability --bundle latest

从最新的持久化事件包生成诊断 zip：

bash
openclaw gateway stability --bundle latest --export

持久化的事件包存放在 ~/.openclaw/logs/stability/ 目录下（如果存在事件记录）。

常用选项 ​

bash
openclaw gateway diagnostics export \
  --output openclaw-diagnostics.zip \
  --log-lines 5000 \
  --log-bytes 1000000
  • --output <path>：指定 zip 文件的输出路径。
  • --log-lines <count>：最多包含的消毒后日志行数。
  • --log-bytes <bytes>：最多检查的日志字节数。
  • --url <url>：Gateway WebSocket URL，用于获取状态和健康快照。
  • --token <token>：Gateway 令牌，用于获取状态和健康快照。
  • --password <password>：Gateway 密码，用于获取状态和健康快照。
  • --timeout <ms>：状态和健康快照的超时时间。
  • --no-stability-bundle：跳过查找持久化的稳定性事件包。
  • --json：输出机器可读的导出元数据。

关闭诊断 ​

诊断功能默认是启用的。要关闭稳定性记录器和诊断事件采集：

json5
{
  diagnostics: {
    enabled: false,
  },
}

关闭诊断会减少 bug 报告的细节。它不会影响正常的 Gateway 日志。

关键内存压力快照默认是关闭的。如果你希望保留诊断事件并同时捕获内存溢出前的稳定性快照：

json5
{
  diagnostics: {
    memoryPressureSnapshot: true,
  },
}

仅在宿主机能承受关键内存压力下的额外文件系统扫描和快照写入时，才使用这个选项。 即使快照关闭，正常的内存压力事件仍然会记录 RSS、堆内存、阈值和增长事实。

相关文档 ​

常见问题 ​

诊断包包含我的聊天记录吗？ ​

不会。诊断包设计为可分享的，会主动省略或涂抹掉聊天文本、提示、指令、Webhook 主体、工具输出、凭证、API 密钥、消息 ID 等个人和机密数据。如果日志行看起来包含用户输入，导出只会记录一条"消息已省略"以及其字节数。

怎么用 /diagnostics 命令在聊天里请求诊断？ ​

在你想报告问题的会话中发送 /diagnostics，可以加一句备注。Gateway 会返回摘要并请求一次执行授权。授权后，它会回复一份包含本地诊断包路径、清单和隐私说明的可粘贴报告。注意，在群聊中只有群主可以运行这个命令，详情会通过私密通道发送。

怎么查看或持久化稳定性记录？ ​

终端运行 openclaw gateway stability 可以查看实时记录。要查看最近的持久化稳定性事件包，运行 openclaw gateway stability --bundle latest。持久化的事件包存放在 ~/.openclaw/logs/stability/ 目录下。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策