提交 Bug 报告

目标

将模糊的用户反馈（例如“我的 agent 变慢了”“它停止响应了”或“它没以前聪明了”）转化为一份符合隐私保护要求的 GitHub Issue，便于维护者快速分诊（triage）。优先依据具体的运行时证据，而非主观推测。

建议向用户公开提供的交接提示文本如下：

请将以下指令交给你的 agent：使用 $file-bug-report 收集保守型 OpenClaw 诊断信息，搜索 openclaw/openclaw 仓库中相似的已开启 Issue，并草拟一份可直接分诊的 Bug 报告。切勿发布密钥、原始凭据、完整配置文件、私有 Prompt 或未经审查的日志。

适用场景

当遇到以下类型的报告时，请使用本技能：

• “我的 agent 变慢了”，或响应时间突然显著长于以往；
• “我的 agent 崩溃了”，或出现卡顿、超时、提前退出、始终无响应等现象；
• “它没以前聪明了”，或表现为工具丢失、上下文丢失、规划质量下降、模型/Provider 路由异常等；
• “工具缺失”，即 agent 无法调用本应可用的工具；
• “更新后它就停止响应了”，或在修改配置、认证信息、模型、插件、MCP 服务器、网关设置、workspace 指令后出现异常；
• “某个插件让问题更严重了”，即插件已安装但被禁用、验证失败，或改变了运行时行为；
• “仅在此 workspace / thread 中失败”，或仅通过特定入口点（如 CLI、桌面 UI、Telegram、浏览器）复现该问题。

用户可能提供给 agent 的典型交接提示示例：

使用 $file-bug-report。OpenClaw 在我昨天安装一个插件后明显变慢。请收集保守型诊断信息，搜索相似问题，并草拟一份 GitHub Issue 待我审核。

使用 $file-bug-report。我的 agent 在当前 workspace 中提示工具不可用，但在全新安装中这些工具是正常的。请捕获配置/插件差异，并草拟 Issue，但不要发布私有日志。

使用 $file-bug-report。自上次更新后，桌面 UI 启动了一次运行，但 agent 始终无响应。请收集维护者所需的最小化证据，并优先检查是否存在重复 Issue。

流程图

flowchart TD
  A["用户报告 agent 运行缓慢、异常、无响应或能力退化"] --> B["agent 提出结构化初步问询"]
  B --> C["运行保守型诊断信息采集器"]
  C --> D["汇总系统、OpenClaw、插件、配置元数据、命令失败记录及邻近日志"]
  D --> E["搜索 openclaw/openclaw 仓库中已开启和已关闭的 Issue"]
  E --> F{"疑似重复？"}
  F -->|是| G["为现有 Issue 草拟评论，附上经审查的新证据"]
  F -->|否| H["基于模板草拟新 Issue"]
  G --> I["展示最终公开文本及所选摘录片段"]
  H --> I
  I --> J{"用户是否批准发布？"}
  J -->|是| K["发布 Issue 或评论"]
  J -->|否| L["本地保留草稿；不上传诊断包"]

工作流

1. 在采集数据前，先明确记录现象。

   • 提出以下初步问询并记录回答，再执行诊断采集：
     • 具体是哪个 Prompt、哪条命令或哪个 UI 操作失败？
     • 你期望 agent 执行什么操作？
     • 实际发生了什么？包括延迟、卡顿、错误消息、缺失工具、推理能力减弱等；
     • 最后一次正常运行是什么时候？问题从何时开始出现？
     • 是否可在新 thread、新 workspace、重试、或禁用可疑插件后复现？
     • 当前选用的是哪个模型、Provider、认证配置文件（auth profile）、workspace 和入口点（entrypoint）？
     • 近期有哪些变更：OpenClaw 更新、配置编辑、插件安装、认证信息变更、操作系统更新、网络/代理变更？
     • 是否允许我采集一份保守型本地诊断包，并搜索公开 Issue？
   • 将现象归类为：延迟（latency）、无响应（no response）、推理能力减弱（weaker reasoning）、工具缺失（missing tools）、崩溃（crash）、认证失败（auth failure）、插件失败（plugin failure）、配置不匹配（config mismatch）或未知（unknown）。

2. 采集一份保守型诊断包。

   • 优先使用本技能目录下的打包脚本。若当前工作目录非该技能目录，请使用绝对路径运行：

bash /path/to/file-bug-report/scripts/collect-openclaw-diagnostics.sh --output ./openclaw-diagnostics

• 若脚本无法运行，请手动采集等效证据：OpenClaw 版本/状态、操作系统、Node/包管理器版本、当前生效配置、插件列表、近期日志、相关命令输出等。
• 默认输出设计为保守型：仅记录配置元数据（而非原始配置内容），跳过全局 /tmp 目录，并对 git/环境状态做摘要而非全量记录。
• 仅在向用户明确说明风险并获得其显式授权后，才可使用 --include-private-config、--include-tmp-logs 或 --include-git-details 参数。
• 在共享前，须人工检查所有生成的文件。脱敏（redaction）是一种纵深防御辅助手段，而非盲目发布的许可依据。

3. 将当前配置与基线配置进行比对。

   • 尽可能使用 OpenClaw 原生命令（如 status、config file、config validate，或任意支持的 config dump/list/diff 命令）。若某命令不存在，请在 Issue 中明确说明。
   • 显式声明基线契约（baseline contract）：
     • 所用基线：发布版默认值 / 当前 main 分支默认值 / 干净配置文件（clean profile） / 未知；
     • 证据来源：命令输出、文件元数据或代码仓库/版本来源；
     • 不可用原因：命令缺失、命令执行失败、安装版本过旧、未检出代码仓库、或其他未知原因。
   • 仅突出显示具有实际意义的非默认项：Provider/模型路由、认证配置文件、网关/传输设置、sandbox/审批模式、超时设置、MCP/工具配置、内存/上下文设置、插件启用状态、workspace 覆盖项、以及 AGENTS/SKILL 覆盖配置。
   • 当摘要差异足以说明风险时，切勿粘贴完整私有配置。

4. 列出插件与扩展。

   • 需包含：已安装插件、当前激活插件、版本号或源路径、验证错误、近期变更，以及禁用可疑插件后问题是否仍可复现。
   • 区分“已安装”、“已激活”、“成功加载”与“验证失败”等不同状态。

5. 采集事件发生时段附近的日志。

   • 优先截取用户发现异常前约 10 分钟至异常发生后约 10 分钟的时间窗口。
   • 涵盖：网关日志、UI/桌面端日志、Provider/API 错误、插件验证错误、会话运行错误、工具调用失败、超时或心跳消息等。
   • 引用紧凑、聚焦的摘录片段；不得包含无关对话、凭据、个人数据或海量原始日志。

6. 提交前先搜索相似 Issue。

   • 阅读 references/similar-issue-search.md。
   • 在 openclaw/openclaw 仓库中，使用症状关键词、精确报错、插件名、Provider/模型名、日志短语等组合进行搜索（覆盖已开启和已关闭的 Issue）。
   • 在 Issue 正文中记录所用精确查询、结果数量、排名靠前的候选 Issue，以及是否判定为重复的决策依据。
   • 若存在匹配项，应在对应 Issue 下草拟评论并附上新证据；或将其作为关联 Issue 引用。仅当本次故障在本质上明显不同，或现有 Issue 缺少必要证据时，才新建 Issue。

7. 草拟 Issue 并获取发布授权。

   • 使用 references/issue-template.md 模板。
   • 首先产出完整的 Issue 正文，包括经审查的摘录列表及明确标注的未知项（explicit unknowns）。
   • 切勿将整个诊断目录上传至 GitHub；仅粘贴经筛选、审查、脱敏后的必要摘录。
   • 若已配置 GitHub 访问权限，仅可在用户批准最终正文及附件/摘录列表后，使用 gh issue create -R openclaw/openclaw 或其他可用 GitHub 工具提交；否则，仅向用户提供完成的 Issue 正文供其手动发布。
   • 标题格式：[diagnostics] Agent <现象> on <平台/Provider/插件>。
   • 正文中需包含：相似 Issue 链接、诊断摘要、命令失败记录、明确标注的未知项。

隐私规则

• 严禁发布原始 API 密钥、OAuth Token、Cookie、Session Token、Bearer Header、私有 Prompt、私有对话内容，或未经审查的完整配置文件。
• 默认仅生成草稿级公开输出，待用户在诊断采集完成后批准最终 Issue 正文后再发布。
• 严禁将完整诊断包作为附件上传至公开 Issue；仅引用必要且已脱敏的摘录片段。
• 当用户名、邮箱、组织名、主机名、绝对家目录路径等信息对调试非必需时，必须予以脱敏。
• 除非用户明确授权，否则不得重启服务、禁用插件、编辑配置或删除状态。
• 将证据标记为“已观察到（observed）”，将假设标记为“疑似（suspected）”；不得仅凭现象报告过度断言根本原因。

资源

• scripts/collect-openclaw-diagnostics.sh：尽最大努力本地采集保守型系统、OpenClaw、插件、配置元数据及日志证据的脚本。依赖 bash 和 perl；openclaw、gh、node、npm、pnpm、git、systemctl 和 launchctl 为可选依赖。
• references/issue-template.md：Issue 正文模板。
• references/similar-issue-search.md：搜索查询示例与重复 Issue 关联指南。

最终草稿核对清单

在请求用户批准发布前，请确认草稿已具备：清晰的标题、影响描述、复现状态、基线来源、插件/配置摘要、经筛选与脱敏的日志摘录、命令失败记录、重复性搜索结论，以及明确的脱敏审查状态。