OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

环境与调试

调试

用于流式输出、Gateway 网关迭代和启动性能分析的调试辅助工具。

运行时调试覆盖

/debug 设置仅运行时配置覆盖（内存中，而非磁盘）。默认禁用；使用 commands.debug: true 启用。

text
/debug show/debug set messages.responsePrefix="[openclaw]"/debug unset messages.responsePrefix/debug reset

/debug reset 会清除所有覆盖，并恢复为磁盘上的配置。

会话追踪输出

/trace 会显示一个会话中由插件拥有的追踪/调试行，而不启用完整的详细模式。将它用于插件诊断，例如主动记忆调试摘要；普通状态/工具输出请使用 /verbose。

text
/trace/trace on/trace off

插件生命周期追踪

设置 OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1，可以按阶段拆解插件元数据、设备发现、注册表、运行时镜像、配置变更和刷新工作。输出写入 stderr，因此 JSON 命令输出仍可解析。

bash
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
text
[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"

在使用 CPU profiler 之前先使用此方法。从源码检出中，在 pnpm build 之后用 node dist/entry.js ... 测量构建后的运行时；pnpm openclaw ... 也会测量源码运行器开销。

CLI 启动和命令性能分析

已提交的启动基准：

bash
pnpm test:startup:bench:smokepnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu

如需通过普通源码运行器进行一次性性能分析，请设置 OPENCLAW_RUN_NODE_CPU_PROF_DIR：

bash
OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

源码运行器会添加 Node CPU profile 标志，并为该命令写入一个 .cpuprofile。在向命令代码添加临时插桩之前先使用此方法。

对于看起来像同步文件系统或模块加载器工作的启动卡顿，通过源码运行器添加 Node 的同步 I/O 追踪标志：

bash
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch 默认会为被监视的 Gateway 网关子进程禁用此标志；如果你也希望在 watch 模式中看到同步 I/O 追踪输出，请设置 OPENCLAW_TRACE_SYNC_IO=1。

Gateway 网关 watch 模式

bash
pnpm gateway:watch

默认情况下，这会启动或重启一个名为 openclaw-gateway-watch-<profile> 的 tmux 会话（例如 openclaw-gateway-watch-main）；只有当 OPENCLAW_GATEWAY_PORT 不同于默认端口 18789 时，才会添加类似 openclaw-gateway-watch-dev-19001 的端口后缀。它会从交互式终端自动附加；非交互式 shell、CI 和 agent exec 调用会保持分离，并改为打印附加说明：

bash
tmux attach -t openclaw-gateway-watch-main

tmux 窗格运行原始 watcher：

bash
node scripts/watch-node.mjs gateway --force

不使用 tmux 的前台模式：

bash
pnpm gateway:watch:raw# orOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

保留 tmux 管理但禁用自动附加：

bash
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

调试启动/运行时热点时，对被监视的 Gateway 网关 CPU 时间进行性能分析：

bash
pnpm gateway:watch --benchmark

watch 包装器会在调用 Gateway 网关之前消费 --benchmark，并在每个 Gateway 网关子进程退出时，在 .artifacts/gateway-watch-profiles/ 下写入一个 V8 .cpuprofile。停止或重启被监视的 Gateway 网关以刷新当前 profile，然后用 Chrome DevTools 或 Speedscope 打开：

bash
npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile
  • --benchmark-dir <path>：将 profiles 写到其他位置。
  • --benchmark-no-force：跳过默认的 --force 端口清理；如果 Gateway 网关端口已被占用，则快速失败。

benchmark 模式默认会抑制同步 I/O 追踪噪声。将 OPENCLAW_TRACE_SYNC_IO=1 与 --benchmark 一起设置，可以同时获取 CPU profiles 和同步 I/O 堆栈追踪；在 benchmark 模式下，这些追踪块会写入 benchmark 目录下的 gateway-watch-output.log（从终端窗格中过滤掉），而普通 Gateway 网关日志仍会保持可见。

tmux 包装器会把常见的非秘密运行时选择器带入窗格，包括 OPENCLAW_PROFILE、OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR、OPENCLAW_GATEWAY_PORT 和 OPENCLAW_SKIP_CHANNELS。将提供商凭证放在你的普通配置文件/配置中，或对一次性临时秘密使用原始前台模式。

如果被监视的 Gateway 网关在启动期间退出，watcher 会运行一次 openclaw doctor --fix --non-interactive，然后重启 Gateway 网关子进程。设置 OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 可查看原始启动失败，而不执行仅开发使用的修复流程。

托管的 tmux 窗格默认使用彩色 Gateway 网关日志；启动 pnpm gateway:watch 时设置 FORCE_COLOR=0 可禁用 ANSI 输出。

watcher 会在 src/ 下与构建相关的文件、扩展源码文件、扩展 package.json 和 openclaw.plugin.json 元数据、tsconfig.json、package.json 以及 tsdown.config.ts 发生变化时重启。扩展元数据变化会重启 Gateway 网关，而不会强制重新构建；源码和配置变化仍会先重新构建 dist。

在 gateway:watch 后添加 Gateway 网关 CLI 标志，它们会在每次重启时传递下去。重新运行相同的 watch 命令会重新生成具名 tmux 窗格；原始 watcher 会保留单一 watcher 锁，因此重复的 watcher 父进程会被替换，而不是不断堆积。

开发配置文件 + 开发 Gateway 网关（--dev）

有两个独立的 --dev 标志：

  • 全局 --dev（配置文件）： 将状态隔离在 ~/.openclaw-dev 下，并将 Gateway 网关端口默认设为 19001（派生端口会随之偏移）。
  • gateway --dev： 告诉 Gateway 网关在缺失时自动创建默认配置 + 工作区（并跳过 bootstrap）。

推荐流程（开发配置文件 + 开发 bootstrap）：

bash
pnpm gateway:devOPENCLAW_PROFILE=dev openclaw tui

如果没有全局安装，请通过 pnpm openclaw ... 运行 CLI。

这会执行以下操作：

  1. 配置文件隔离（全局 --dev）

    • OPENCLAW_PROFILE=dev
    • OPENCLAW_STATE_DIR=~/.openclaw-dev
    • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
    • OPENCLAW_GATEWAY_PORT=19001（浏览器/canvas 端口会相应偏移）

  2. 开发 bootstrap（gateway --dev）

    • 如果缺失，则写入最小配置（gateway.mode=local，绑定回环）。
    • 将 agents.defaults.workspace 设置为开发工作区，并设置 agents.defaults.skipBootstrap=true。
    • 如果缺失，则播种工作区文件：AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md。
    • 默认身份：C3-PO（协议机器人）。
    • pnpm gateway:dev 还会设置 OPENCLAW_SKIP_CHANNELS=1，以跳过渠道提供商。

重置流程（全新开始）：

bash
pnpm gateway:dev:reset

--reset 会清除配置、凭证、会话和开发工作区（移到废纸篓，而不是删除），然后重新创建默认开发设置。

原始流日志

OpenClaw 可以在任何过滤/格式化之前记录原始助手流。这是查看推理是否以纯文本 delta（或以单独的 thinking block）到达的最佳方式。

通过 CLI 启用：

bash
pnpm gateway:watch --raw-stream

可选路径覆盖：

bash
pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl

等效环境变量：

bash
OPENCLAW_RAW_STREAM=1OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl

默认文件：~/.openclaw/logs/raw-stream.jsonl

安全注意事项

  • 原始流日志可能包含完整提示、工具输出和用户数据。
  • 将日志保留在本地，并在调试后删除。
  • 如果你共享日志，请先清理秘密和 PII。

在 VSCode 中调试

需要 source maps，因为构建会对生成的文件名进行哈希处理。随附的 launch.json 面向 Gateway 网关服务：

  1. 重新构建并调试 Gateway 网关 - 删除 /dist，并在启动 Gateway 网关之前启用调试重新构建。
  2. 调试 Gateway 网关 - 在不触碰 /dist 的情况下调试现有构建。

设置

  1. 打开 运行和调试（活动栏，或 Ctrl+Shift+D）。
  2. 选择 重新构建并调试 Gateway 网关，然后按 开始调试。

如果改为手动管理构建/调试循环：

  1. 在终端中启用 source maps：
    • Linux/macOS：export OUTPUT_SOURCE_MAPS=1
    • Windows (PowerShell)：$env:OUTPUT_SOURCE_MAPS="1"
    • Windows (CMD)：set OUTPUT_SOURCE_MAPS=1
  2. 重新构建：pnpm clean:dist && pnpm build
  3. 选择 调试 Gateway 网关，然后按 开始调试。

在 src/ TypeScript 文件中设置断点；调试器会通过 source maps 将它们映射到已编译的 JavaScript。

说明

  • 重新构建并调试 Gateway 网关 会删除 /dist，并在每次启动时使用 source maps 运行完整的 pnpm build。
  • 调试 Gateway 网关 可以在不影响 /dist 的情况下启动/停止，但你需要在单独的终端中管理构建循环。
  • 编辑 launch.json args 以调试其他 CLI 子命令。
  • 如需将构建后的 CLI 用于其他任务（例如，如果你的调试会话生成了新的认证令牌，则运行 dashboard --no-open），请从另一个终端运行：node ./openclaw.mjs，或使用类似 alias openclaw-build="node $(pwd)/openclaw.mjs" 的别名。

相关

Was this useful?
On this page

On this page