ClawTraces 数据采集#

本 Skill 帮助用户从本地 OpenClaw 日志中采集符合要求的 session 数据，转换为 Anthropic 标准 trajectory 格式，并提交到数据收集服务器。

工作流程#

按以下顺序执行，每一步完成后再进行下一步。

---

步骤 1：环境准备（认证 + 环境检查）#

认证和环境检查作为一个整体自动完成，中间不需要额外提示。

1.1 认证检查

bash

python3 /{{baseDir}}/scripts/lib/auth.py

脚本输出 JSON，包含 authenticated 字段。

• 已认证：直接进入 1.2。

• 未认证：

  1. 必须先向用户询问手机号，等用户回复后才能继续。 直接问："请提供你的手机号（11 位数字）"，然后 停下来等待用户回复。绝对不要自己编造或使用任何默认手机号。

  2. 用户回复手机号后，发送验证码： bash

     python3 -c "
     import sys; sys.path.insert(0, '/{{baseDir}}/scripts')
     from lib.auth import send_code, get_server_url
     result = send_code(get_server_url(), '<用户回复的手机号>')
     import json; print(json.dumps(result, indent=2))
     "
     
     

     其中 <用户回复的手机号> 替换为用户实际提供的号码。

  3. 告诉用户"验证码已发送，请查看短信并回复验证码"，然后 再次停下来等待用户回复验证码。

  4. 用户回复验证码后，验证： bash

     python3 -c "
     import sys; sys.path.insert(0, '/{{baseDir}}/scripts')
     from lib.auth import verify_code, save_key, get_server_url
     result = verify_code(get_server_url(), '<手机号>', '<用户回复的验证码>')
     import json; print(json.dumps(result, indent=2))
     if result.get('key'):
         save_key(result['key'])
     "
     
     

  5. 失败则提示错误并允许重试

1.2 环境检查

bash

python3 /{{baseDir}}/scripts/env_check.py

脚本会自动检查并修复三项配置：

• cache-trace：开启诊断日志（enabled + includeSystem），记录真实 system prompt
• thinking level：确保全局和所有 agent 的 thinkingDefault 至少为 high，提升推理质量
• model reasoning：确保自定义 provider 中白名单模型的 reasoning 为 true，启用推理能力

处理结果：

• 配置已正确：无需额外操作。

• 配置被自动修改：

  1. 将脚本输出的修改明细（ fixes 字段） 完整展示给用户，让用户知道对 openclaw.json 做了哪些改动

  2. 自动重启 OpenClaw： bash

     openclaw gateway restart
     
     

  3. 说明 cache-trace 仅记录重启后的新对话，之前的对话无法补充 system prompt 数据。如果当前没有重启后产生的新 session，本次扫描可能无结果，建议用户正常使用一段时间后再来采集。

1.3 完成提示

• 如果 1.2 配置被修改（ changed: true）：本次流程到此结束，不继续后续步骤。输出：

  ✅ 环境已就绪！cache-trace 已开启并已重启 OpenClaw。 由于 cache-trace 只记录重启后的新对话，当前没有可采集的数据。 请正常使用 OpenClaw 一段时间后，再运行 /clawtraces 采集数据。

• 如果 1.2 配置已正确（ changed: false）：输出以下提示， 然后停下来等待用户指令：

  ✅ 环境已就绪。你可以：

  • 📋 采集数据 — 列出可采集的对话，选择后提交
  • 📊 查看进度 — 已提交多少条、查看提交记录
  • 📦 提交 Harness — 提交你的 SOUL.md、USER.md 等配置文件

  必须原样输出上面的提示，不要自行增减内容，然后停下来等待用户回复。 用户回复后根据语义判断进入步骤 2（采集）、步骤 5（查看进度）或步骤 5.5（提交 Harness）。

---

步骤 2：采集数据#

触发：用户表达了想要采集、提交、查看对话清单的意图。常见表达包括"看看有哪些"、"采集"、"全部"、"最近 N 条"、"帮我处理"等。

2.1 列出对话清单

bash

python3 /{{baseDir}}/scripts/scan_adapter.py --adapter openclaw --list-only

脚本输出 JSON 对象（分页），包含以下字段：

• items：当前页的对话列表（默认每页 10 条），每项包含 index（序号）、 session_id、 model、 started_at、 ended_at、 file_size_kb、 topic、 status
• total：对话总数
• page：当前页码
• page_size：每页条数
• has_more：是否有下一页

status 字段说明：

status 值含义能否处理null正常，可直接处理提交✅"active"当前活跃对话（尚未 /new 或 /reset）✅ 需通过 --sessions 显式指定"rejected"之前的扫描中被硬过滤（如轮次不足、模型不合格）❌"model_mismatch"使用的模型不在采集白名单中❌

将 items 以表格形式展示给用户。status 映射为中文标记：

• null → 不显示
• "active" → ⚡活跃中
• "rejected" → ❌不合格
• "model_mismatch" → ⚠️模型不符

示例：

找到 85 个对话记录，显示第 1-10 条：

#开始时间结束时间模型摘要状态104-04 14:0004-04 15:30claude-opus-4-6帮我调试一下这个内存泄漏...⚡活跃中204-04 10:3004-04 12:15claude-opus-4-6帮我把这个 React 组件重构一下......1004-01 11:0004-01 12:00claude-sonnet-4-6分析用户留存数据...

其中 {N} 个可直接处理（无状态标记的）。还有 75 条，回复「更多」查看下一页。 提示：标记为「⚡活跃中」的对话尚未结束。如果确认已完成，可以选择它来处理；但提交后若继续在该对话中聊天，新增内容将无法补充到已提交的记录中。建议在对话完全结束后再提交。

你想处理哪些？回复"全部"、"前 3 个"、"第 1、3、5 个"等即可。

分页：当 has_more 为 true 时，展示"还有 {total - page*page_size} 条，回复「更多」查看下一页"。用户说"更多"时执行：

bash

python3 /{{baseDir}}/scripts/scan_adapter.py --adapter openclaw --list-only --page 2

继续展示下一页内容，累加到之前的列表上下文中。页码递增直到 has_more 为 false。

如果列表为空（ total 为 0）：输出无可用数据的提示，流程结束。

2.2 按用户选择处理

用户可能说：

• "全部" → 不传 --sessions，走默认全量处理（只处理 status: null 的对话）
• "前 N 个" / "最近 N 条" → 从清单中取前 N 个 status: null 的 session_id（跳过有状态标记的）
• "第 1、3、5 个" → 从清单取对应序号的 session_id。如果用户选择了 status: "active" 的对话，通过 --sessions 显式指定（可以处理）。如果用户选择了 "rejected" 或 "model_mismatch" 的对话，告知无法处理并说明原因
• 直接给 session_id → 直接使用

确定要处理的 session_id 列表后，执行：

bash

python3 /{{baseDir}}/scripts/scan_adapter.py --adapter openclaw --sessions <id1> <id2> <id3>

快捷方式：指定数量

如果用户在一开始就说了"最近 3 条"、"处理 5 个"等指定数量的表达，可以跳过列表直接使用 --limit 参数：

bash

python3 /{{baseDir}}/scripts/scan_adapter.py --adapter openclaw --limit <N>

快捷方式：按日期范围

如果用户说"最近一周的"、"只要 4 月的"、"从 3 月 20 号开始"等指定日期范围的表达：

将用户的日期表达转换为 YYYY-MM-DD 格式，使用 --since 参数：

bash

python3 /{{baseDir}}/scripts/scan_adapter.py --adapter openclaw --since <YYYY-MM-DD>

--since 可与 --limit 组合使用。例如"最近一周的前 5 条"：

bash

python3 /{{baseDir}}/scripts/scan_adapter.py --adapter openclaw --since 2026-03-29 --limit 5

处理结果（所有模式共用）

脚本会自动：

• 按硬性规则过滤（模型、轮次 > 5）
• 按数字指标过滤（用户消息平均长度、长消息数）
• 从 cache-trace 提取真实 system prompt（自动模式下无数据则跳过； --sessions 显式指定时使用重建 prompt）
• 为每个通过的 session 自动生成启发式 domain（基于工具使用模式）和 title（基于第一条用户消息）
• 生成 .trajectory.json 文件和 .stats.json 文件

脚本 stdout 输出 JSON 对象，包含两个字段：

• candidates：通过所有过滤的候选列表（session_id、turns、domain、model 等摘要字段）
• filter_report：过滤报告，包含 total_found（发现总数）、 total_scanned（实际处理数）、 pre_filter（前置过滤计数）、 passed（通过数）、 filtered_count（被过滤数）、 filtered（每个被过滤 session 的 session_id、topic、reason、detail）

展示过滤报告：当 filter_report.filtered_count > 0 时，向用户展示过滤摘要。按 reason 分组，默认展示每条的 detail 和 session_id，例如：

扫描了 15 个 session，8 个通过，7 个被过滤：

• 3 个轮次不足： · 3 turns (min 6): session_id_1 · 4 turns (min 6): session_id_2 · 2 turns (min 6): session_id_3
• 2 个无 cache-trace 数据： · no system prompt available: session_id_4 · no system prompt available: session_id_5
• 1 个质量检查未通过： · long user messages (0) < 1: session_id_6
• 1 个转换错误： · tool_error_abort: session_id_7

如果候选数量为 0：本次流程结束，不继续后续步骤。基于 filter_report 展示具体原因：

本次扫描处理了 {total_scanned} 个 session，但全部被过滤：

• {reason 分组}: {count} 个

如需了解具体哪些 session 被过滤及原因，可以查看详情。

如果 total_found 为 0，说明没有使用支持模型的对话，单独说明。

如果有候选：展示扫描结果（候选数量、每个 session 的模型、轮次和启发式 domain），然后继续步骤 3。启发式 domain（由工具使用模式推断）和启发式 title（第一条用户消息截断）直接作为最终值使用；数据的语义质检下沉到服务端打分 + 人工终审阶段。

---

步骤 3：Harness 门槛检查（进入提交前）#

在展示待提交列表之前，先检查是否需要强制提交 Harness：

bash

python3 -c "
import sys; sys.path.insert(0, '/{{baseDir}}/scripts')
from submit import query_count
from lib.auth import get_server_url, get_stored_key
import json
result = query_count(get_server_url(), get_stored_key())
print(json.dumps(result, indent=2))
"

检查返回的 workspace_force_required、 workspace_threshold、 workspace_submitted、 count 字段：

• 如果 workspace_force_required == true 且 count >= workspace_threshold 且 workspace_submitted == false：

  • 告知用户：「你已提交 {count} 条数据（达到 {threshold} 条阈值），需要先提交 Harness 才能继续采集。」
  • 自动进入步骤 5.5（提交 Harness）
  • Harness 提交成功后继续步骤 4；用户拒绝则流程结束

• 否则：直接进入步骤 4

---

步骤 4：提交#

展示最终待提交列表，格式如下：

text

找到 N 条可提交的日志：

  1. 为 React 项目添加用户认证模块  | 软件开发 | 8 轮
  2. 分析 Q1 销售数据并生成报告    | 数据分析 | 12 轮

是否确认提交这 N 条记录？

每条展示标题、领域名称和轮次，不再展示 session_id。

必须等待用户明确确认后才能提交。

用户确认后运行：

bash

python3 /{{baseDir}}/scripts/submit.py

提交完成后展示：本次提交数量 + 你累计已提交的数量（注意：这是当前用户个人的提交总数，不是全平台的）。并提示用户可以说「查看提交记录」来查看历史提交。

workspace_required 错误处理：如果提交过程中某条记录返回 workspace_required 错误（服务端 403），说明用户需要先提交 Harness。告知用户原因，自动进入步骤 5.5。Harness 提交成功后，可重新运行提交。

提交脚本的输出中包含 workspace_threshold、 workspace_submitted、 workspace_force_required 字段，用于判断是否触发步骤 4.5。

---

步骤 4.5：Harness 采集（条件触发）#

触发条件：步骤 4 提交完成后，如果满足以下两个条件则触发：

1. 用户累计提交数量 ≥ workspace_threshold（阈值由服务端控制）
2. workspace_submitted 为 false（尚未提交过 Harness）

如果不满足条件，静默跳过此步骤。

注意：此步骤是 推荐性 提示，无论 workspace_force_required 是否启用都会触发。用户可以拒绝。强制拦截由步骤 3 和服务端 403 保证。

触发后：

4.5.1 征询同意

告知用户：

你已提交 {count} 条数据（达到 {threshold} 条阈值）。为提升数据质量，我们希望采集你的 Harness（SOUL.md、USER.md 等配置文件）。这是一次性采集，所有文件会在本地自动脱敏后再提交。是否同意？

等待用户确认。 用户拒绝则跳过此步骤。

4.5.2 本地打包 + 脱敏

用户同意后，先执行打包（不上传）：

bash

python3 /{{baseDir}}/scripts/workspace_bundle.py --bundle-only

脚本输出 JSON，包含每个 workspace 的打包结果和脱敏报告：

• workspaces[].zip_file — 生成的 zip 文件名
• workspaces[].zip_size — 文件大小
• workspaces[].scrub_report.total_redactions — 脱敏替换总数
• workspaces[].scrub_report.by_category — 按类别统计（如 {"手机号": 2, "邮箱": 1}）
• workspaces[].scrub_report.files_scrubbed — 被脱敏的文件列表及各自的替换详情

4.5.3 展示脱敏信息，确认提交

必须将脱敏信息展示给用户，让用户了解隐私处理情况：

• 如果有脱敏操作（ total_redactions > 0）：

  打包完成。以下文件中检测到敏感信息并已自动脱敏：

  文件脱敏项SOUL.md手机号 ×2, 邮箱 ×1memory/user_profile.mdAPI Key ×1

  共 {total} 处敏感信息已替换为占位符（如 [PHONE]、 [EMAIL]），原始内容不会上传。 是否确认提交？

• 如果没有脱敏操作（ total_redactions == 0）：

  打包完成，未检测到需要脱敏的敏感信息。是否确认提交？

等待用户确认。

4.5.4 上传

用户确认后执行上传：

bash

python3 /{{baseDir}}/scripts/workspace_bundle.py --upload-only

展示上传结果（成功/失败的 workspace 数量）。

---

步骤 5：查询（可选）#

触发：用户说「查看提交记录」「提交了多少条」「查看进度」等。

bash

python3 /{{baseDir}}/scripts/query.py [--page N] [--page-size N]

展示已提交的 session 列表，每条包含标题、领域、模型、轮次、提交时间。默认每页 20 条，支持分页。

以表格形式展示：

提交记录（共 {total} 条）

#标题领域模型轮次提交时间1为 React 项目添加认证软件开发claude-opus-4-682026-04-08 14:30...

用户说「更多」或「下一页」时加载下一页。

---

步骤 5.5：独立 Harness 提交#

触发：用户说「提交 Harness」「提交 Workspace」「提交工作区配置」「workspace」等。

5.5.1 查询已提交状态

bash

python3 -c "
import sys; sys.path.insert(0, '/{{baseDir}}/scripts')
from submit import query_count
from lib.auth import get_server_url, get_stored_key
import json
print(json.dumps(query_count(get_server_url(), get_stored_key()), indent=2))
"

读取返回的 workspace_submitted 字段。

5.5.2 已提交过的提醒（workspace_submitted == true）

如果用户之前已经提交过 Harness， 不要拒绝，而是原样输出以下提示并 停下来等待用户回复：

你之前已经提交过 Harness。如果你本地的配置文件有了更新（比如 SOUL.md、USER.md、memory/ 下的内容有新变化），可以再提交一份最新版本，后端会保留所有历史版本作为参考。

是否需要提交一份新版本？

• 用户确认（"好"、"提交"、"更新"等）→ 进入 5.5.3
• 用户拒绝（"不用"、"算了"等）→ 流程结束

如果 workspace_submitted == false（首次提交），直接进入 5.5.3，不需要展示上面的提醒。

5.5.3 本地打包 + 脱敏

bash

python3 /{{baseDir}}/scripts/workspace_bundle.py --bundle-only

5.5.4 展示脱敏报告，征询用户确认

展示格式与步骤 4.5.3 一致（按文件列出脱敏项，或说明未检测到敏感信息），然后等待用户确认。

5.5.5 上传

bash

python3 /{{baseDir}}/scripts/workspace_bundle.py --upload-only

展示上传结果。

---

步骤 6：重新提交（独立操作）#

当用户明确要求"重新提交"某条记录时使用。 必须提供 session_id，不提供则要求用户补充。

此操作会重新转换该 session 并强制覆盖服务端已有记录（trajectory 文件、metadata、stats 全部覆盖）。

流程

1. 确认认证状态（同步骤 1.1）
2. 用户提供的 session_id 对应的 trajectory 文件必须已存在于 output/ 目录。如果不存在，需要先重新运行扫描转换（步骤 2）生成该文件，再继续。
3. 运行重新提交：

bash

python3 /{{baseDir}}/scripts/submit.py --resubmit {session_id}

1. 展示结果（是否覆盖成功、累计提交数）。

注意：此步骤仅在用户明确说"重新提交 xxx"时触发，正常的批量提交流程（步骤 2-4）不会使用 force 参数。

---

401 处理#

在任何步骤中，如果 API 返回 401（unauthorized），说明 key 已失效：

1. 通知用户 key 已失效
2. 自动清除本地 key（脚本已自动完成）
3. 重新进入步骤 1.1 的认证流程（跳过 1.2 环境检查，因为环境配置不受 key 失效影响）
4. 认证成功后，从发生 401 的步骤继续执行

数据目录#

数据文件存放在 workspace 根目录的 .clawtraces/ 下（与 .clawhub/ 同级），独立于 skill 安装目录，不受升级影响：

text

{workspace}/.clawtraces/
├── .env                             # API key + server URL
└── output/
    ├── {session_id}.trajectory.json # 转换后的 Anthropic trajectory 文件
    ├── {session_id}.stats.json      # session 元数据
    └── manifest.json                # 提交记录 + 拒绝记录（已处理 session 跟踪）

注意事项#

• 认证完成后必须原样输出提示文案并等待用户指令，不要自动开始采集，不要自行增减提示内容
• --list-only 是轻量操作（只读索引和文件元数据），不消耗大量资源
• --limit N 只处理最近 N 个对话
• --since YYYY-MM-DD 只处理该日期之后的对话，可与 --limit 组合使用
• --sessions 指定的对话会跳过"活跃"和"已提交"的自动过滤，因为用户明确选择了它们
• --list-only 列出除已提交外的所有对话（包括活跃、已拒绝、模型不符的），用 status 字段区分
• 默认处理（不带 --sessions）仍然严格过滤：只处理白名单模型、非活跃、非已拒绝的对话
• 用户消息中的隐私信息（Sender 身份、时间戳）会在转换时自动清除
• System prompt 从 cache-trace 提取。自动模式下，无 cache-trace 数据的对话会被跳过（历史对话）；通过 --sessions 显式指定的对话会使用重建的 system prompt 作为回退
• 提交需要用户确认，确保数据授权合规
• 已提交和已拒绝的对话不会重复处理（manifest.json 跟踪）
• 面向用户的文案中统一使用"对话"而非"session"，session_id 等技术字段仅在内部处理时使用