应立即启用调试日志并导出三类日志文件：①~/.stepclaw/logs/app.log；②~/.stepclaw/logs/llm-raw.log；③~/.stepclaw/logs/agent-trace.json，再配合录屏或#DEBUG复现，按规范提交GitHub Issue。

☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

阶跃AI在执行任务时突然报“未知错误”，界面只显示一行红色文字、没有堆栈、无法复现、重试有时成功有时失败——这种情况下，靠截图或口头描述根本无法让开发团队定位问题。

确认日志开关是否已启用

StepClaw默认不开启详细日志记录，必须手动激活。打开设置 → 高级选项 → 勾选【启用调试日志】，该选项位于“开发者模式”二级菜单内，未开启时所有异常均被静默吞掉。

这一步不做，后续收集的任何信息都无效——因为根本没有日志可查。

定位并导出三类核心日志文件

日志分散在三个路径，缺一不可：

① 主应用日志：~/.stepclaw/logs/app.log（含UI交互、Agent调度、Skill调用链）

② AI模型通信日志：~/.stepclaw/logs/llm-raw.log（含完整request_id、原始HTTP请求与响应体，含code/message/type字段）

③ 多智能体协作日志：~/.stepclaw/logs/agent-trace.json（含Who&When格式的失败归因上下文，含每个Agent的输入/输出/决策依据）

注意：app.log和llm-raw.log是文本格式，agent-trace.json是结构化JSON，必须全部打包提交；仅提供截图或复制片段会导致关键上下文丢失。

复现时同步捕获关键上下文

方法一：使用内置录屏工具

按快捷键 【Ctrl+Shift+R】 启动录制，操作全程保持窗口焦点在StepClaw上，录屏自动包含鼠标轨迹、时间戳、窗口标题栏——这是唯一能还原“偶发性错误”的方式。

方法二：手动构造最小复现用例

若错误稳定复现，关闭所有无关Skill，新建空白画布，只运行触发错误的单一指令（例如：“生成世界杯比分预测表”），并在命令前加前缀#DEBUG，系统会强制将本次执行全量上下文写入agent-trace.json。

不要跳过这步：未加#DEBUG标记的常规执行，agent-trace.json只会保留采样片段，不足以支撑失败归因。

提交GitHub Issue前的必填项校验

访问 https://link.gitcode.com/i/732025d14efb9199feca73a09c586c5d → New issue → 选择“Bug report”模板：

填写标题格式为：[BUG] StepClaw v2.5.3 macOS 14.6：执行#DEBUG指令后agent-trace.json缺失decision_reason字段

在“复现步骤”中必须包含：操作系统+版本、StepClaw版本号（设置→关于中查看）、复现发生的具体时间（精确到分钟）、是否为首次出现（是/否/不确定）。

附件必须打包上传：app.log + llm-raw.log + agent-trace.json + 录屏文件（MP4，≤50MB）——少一个文件，Issue将被自动标记为“信息不全”并搁置处理。