ocdt

openclaw-debug-toolkit 命令行工具。通过 REST 调用 @ocdb/plugin 暴露的 Debug Service（默认 :7887），提供 Agent 调试的全套命令。

安装

npm install -g @ocdb/cli

或作为项目依赖：

npm install --save-dev @ocdb/cli

前提

运行任何 ocdt 命令前，需确保 OpenClaw gateway 正在运行且已加载 @ocdb/plugin：

openclaw gateway start   # 启动 gateway（含 debug service）
curl http://localhost:7887/health  # 验证连通性

命令参考

ocdb runs

列出最近的 Agent runs，按时间降序排列。

ocdb runs [选项]

选项：
  --filter <status>   按状态过滤：running | completed | failed | cancelled
  --limit <n>         最多显示条数（默认 20）
  --json              输出原始 JSON 数组
  -h, --help

输出示例：

runId                                status       mode     duration
----------------------------------------------------------------------
run-a3f2b8c1...                      failed       live     12.3s
run-b8c1d2e3...                      completed    live     8.1s
fork-c9d3e4f5...                     completed    fork     3.2s

示例：

# 只看失败的
ocdb runs --filter failed

# 最近 5 条，JSON 格式导出
ocdb runs --limit 5 --json > runs.json

ocdb inspect <run-id>

查看某次 run 的完整快照，包括所有 checkpoints 列表。

ocdb inspect <run-id> [选项]

参数：
  <run-id>            Run ID（支持前缀匹配即将支持）

选项：
  --checkpoint <id>   查看特定 checkpoint 的完整内容（含 messages）
  --json              输出原始 JSON（run 元数据 + 所有 checkpoints）
  -h, --help

输出示例：

Run: run-a3f2b8c1...
  Status : failed
  Mode   : live
  Agent  : my-chart-agent
  Started: 2026-06-04T09:15:32.000Z
  Ended  : 2026-06-04T09:15:44.323Z
  Error  : {"message":"render validation failed"}

Checkpoints (8):
  [ 0] before_prompt_build      ckp-run-a3f2-prompt-xxx
  [ 0] before_model_call        ckp-run-a3f2-llm-in-xxx
  [ 0] after_model_call         ckp-run-a3f2-llm-out-xxx
  [ 0] before_tool_call         ckp-run-a3f2-tool-before-tc1
  [ 0] after_tool_call          ckp-run-a3f2-tool-after-tc1
  [ 1] before_model_call        ckp-run-a3f2-llm-in-xxx2
  [ 1] after_model_call         ckp-run-a3f2-llm-out-xxx2
  [-1] agent_end                ckp-run-a3f2-end-xxx

示例：

# 查看某个 checkpoint 的 messages 和 model 配置
ocdb inspect run-a3f2... --checkpoint ckp-run-a3f2-llm-in-xxx

# 导出全量数据用于离线分析
ocdb inspect run-a3f2... --json > run-detail.json

ocdb replay <run-id>

从指定 checkpoint fork，重跑后续步骤。这是调试工具的核心命令。

ocdb replay <run-id> --from <checkpoint-id> [选项]

参数：
  <run-id>                  源 run ID

必填选项：
  --from <checkpoint-id>    从哪个 checkpoint 开始 fork

模型控制（三选一，不填则使用源 run 的模型）：
  --captured                使用历史 LLM 输出（确定性重放，不消耗 token）
  --model <model-id>        换一个真实模型重跑
  --provider <provider>     配合 --model 指定 provider

上下文替换：
  --prompt-version <v>      覆盖 prompt 版本
  --context '<json>'        JSON patch，局部替换 runtimeContext
                            例：'{"project":{"reportId":"new-id"}}'

工具策略：
  --tool-policy <policy>              全局工具策略（适用所有工具）
  --tool-policy <tool>=<policy>       对指定工具单独设置策略
                                      可多次使用，具名优先于全局

  策略值：reuse_result | re_execute | mock_result | forbid_replay

其他：
  --json        输出 fork run 的原始 JSON
  -h, --help

常用场景：

# 场景 1：定位上下文问题（固定模型输出，只看上下文影响）
ocdb replay run-xxx --from ckp-prompt-yyy --captured

# 场景 2：换模型对比（工具全部复用历史结果，只换 LLM）
ocdb replay run-xxx --from ckp-prompt-yyy \
  --model claude-opus-4-8 \
  --tool-policy reuse_result

# 场景 3：换 prompt 版本（所有工具复用历史，只换 prompt）
ocdb replay run-xxx --from ckp-prompt-yyy \
  --prompt-version v2 \
  --tool-policy reuse_result

# 场景 4：替换某个项目上下文字段
ocdb replay run-xxx --from ckp-prompt-yyy \
  --context '{"project":{"reportId":"debug-report-001"}}'

# 场景 5：精细化策略（SQL 复用，报表写入禁止）
ocdb replay run-xxx --from ckp-after-tc1 \
  --tool-policy execute_sql=reuse_result \
  --tool-policy save_report=forbid_replay

执行后跟踪进度：

# replay 命令立即返回 fork run ID
ocdb replay run-xxx --from ckp-yyy
# → Fork created: fork-b7d3...
#   ...
#   ocdb inspect fork-b7d3...

# 跟踪 fork run 状态
ocdb inspect fork-b7d3...

# 对比结果
ocdb diff run-xxx fork-b7d3...

ocdb diff <run-a> <run-b>

对比两次 run 的差异。通常用于对比源 run 和 fork run。

ocdb diff <run-a> <run-b> [选项]

参数：
  <run-a>    第一个 run ID（通常是源 run）
  <run-b>    第二个 run ID（通常是 fork run）

选项：
  --json     输出完整 diff JSON（含每个字段的 changed/a/b）
  -h, --help

输出示例：

Diff: run-a3f2... vs fork-b7d3...
  1 difference type(s) detected
  Status      : failed → completed
  Checkpoints : 8 → 9 (changed)
  Tool calls  : 2 → 2

  Tool call differences:
    [1] generate_chart_option: result differs

示例：

# 文本对比
ocdb diff run-a3f2... fork-b7d3...

# JSON 格式，便于程序处理
ocdb diff run-a3f2... fork-b7d3... --json | jq '.diff.toolCallDiffs'

# 对比同一 run 的两次 fork（A/B 测试不同 prompt）
ocdb diff fork-b7d3... fork-c8e4...

ocdb import <file>

从 OpenClaw trajectory bundle 或 session JSONL 文件导入历史 run。

ocdb import <file>

参数：
  <file>    JSONL 文件路径（每行一个事件）

选项：
  -h, --help

示例：

ocdb import ./trajectory-2026-06-04.jsonl
# → Imported 42 events from ./trajectory-2026-06-04.jsonl (note: full trajectory parsing coming in a future release)

当前限制：v0.1 版本只统计事件数量，完整 trajectory 解析（将历史 run 写入 checkpoint store）在后续版本支持。

OcdtClient — 编程式调用

如果需要在 Node.js 代码中调用 Debug Service，可以直接使用 OcdtClient：

import { OcdtClient } from 'ocdt/client'  // 或从源码 packages/cli/src/client.ts 导入

const client = new OcdtClient({ port: 7887, host: 'localhost' })

// 健康检查
const { status } = await client.health()

// 列出 runs
const { runs } = await client.listRuns({ status: 'failed' }, 10)

// 获取单个 run
const result = await client.getRun('run-abc123')
// → { run: DebugRun } | null

// 获取 checkpoints
const { checkpoints } = await client.getCheckpoints('run-abc123')

// 发起 fork
const { forkRun } = await client.fork({
  sourceRunId: 'run-abc123',
  sourceCheckpointId: 'ckp-xxx',
  modelOverride: { mode: 'captured' },
  toolPolicyMap: { execute_sql: 'reuse_result' },
})

// 对比 runs
const { diff } = await client.getDiff('run-abc123', 'fork-def456')

// 导入 trajectory
const { imported } = await client.importTrajectory(jsonlString)

全局选项

所有命令默认连接 http://localhost:7887。如需修改：

# 环境变量（即将支持）
OCDT_PORT=8080 ocdb runs

# 或通过 ocdb config（即将支持）
ocdb config --port 8080

退出码

| 码 | 含义 | |---|---| | 0 | 成功 | | 1 | 错误（连接失败、run 不存在、参数错误等） |