跳转至

调试

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

网关监视模式

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 调用会保持分离状态,并改为打印附加说明:

tmux attach -t openclaw-gateway-watch-main
# Read recent output without attaching
tmux capture-pane -ep -t openclaw-gateway-watch-main -S -200

该窗格使用 tmux 的 remain-on-exit,因此启动失败会保留下来,可供附加或捕获,而不是删除会话。重新运行 pnpm gateway:watch 会重新生成该窗格。

tmux 窗格运行原始监视器:

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

在监视配置/默认端口之前,tmux 包装器会停止当前活动配置的已安装网关服务。这样端口就会交给源码监视器,而不会由 launchd、systemd 或计划任务重新生成并替换它。服务仍保持已安装状态。监视会话结束后,使用以下命令恢复它:

pnpm openclaw gateway start

显式指定的 --port 或 OPENCLAW_GATEWAY_PORT 可能与已安装服务的有效端口不同。在这种情况下,包装器会让服务继续运行,因此两个网关可以并行运行。

不使用 tmux 的前台模式:

pnpm gateway:watch:raw
# or
OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

原始模式不会管理已安装的服务。如果它使用相同端口,请先运行 pnpm openclaw gateway stop。

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

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

在调试启动/运行时热点时,分析被监视网关的 CPU 时间:

pnpm gateway:watch --benchmark

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

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

基准测试模式默认会抑制同步 I/O 跟踪的刷屏输出。将 OPENCLAW_TRACE_SYNC_IO=1 与 --benchmark 一起设置,可同时获取 CPU profile 和同步 I/O 堆栈跟踪。在基准测试模式下,这些跟踪块会写入基准测试目录下的 gateway-watch-output.log(从终端窗格中过滤掉)。正常的网关日志仍然可见。

tmux 包装器会将常见的非机密运行时选择器带入窗格,包括 OPENCLAW_PROFILE、OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR、OPENCLAW_GATEWAY_PORT 和 OPENCLAW_SKIP_CHANNELS。请将提供商凭据放在常规配置/配置文件中,或使用原始前台模式处理一次性临时机密。

如果被监视的网关返回启动错误,监视器会运行一次 openclaw doctor --fix --non-interactive,然后重启网关子进程。设置 OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 可在不执行仅限开发的修复流程的情况下查看原始启动失败。

在 Unix 上,如果原生 runner 被信号终止,前台命令会保留该信号并停止,而不是运行 doctor 或重启。当请求的重启或关闭必须终止一个无响应的 runner 时,也适用此行为。其分离的 worker 可能仍需要清理。信号终止并不能证明它们已停止。普通返回错误、已确认的停止以及源码更改仍保持现有的恢复和重建行为。Windows 保留其现有的终止和重启行为,因为其信号模拟不会做出同样的区分。

UI 开发包装器只有在子进程正常返回且已捕获的子进程树停止后,才会确认请求的停止。被信号终止的子进程或强制清理会保留信号结果,而不是报告已确认的停止。

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

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

在 gateway:watch 后添加网关 CLI 标志,它们会在每次重启时透传。重新运行相同的监视命令会重新生成指定的 tmux 窗格。原始监视器会保持单一监视器锁,因此重复的监视器父进程会被替换,而不是不断堆积。

开发配置 + 开发网关(--dev)

当你从 checkout 运行 pnpm openclaw、pnpm dev 或网关开发 runner 时,runner 会优先选择该 checkout 的插件,而不是具有相同 id 的受跟踪全局副本。当可用时,已构建的插件输出仍优先,包括单独发布的 checkout 插件、Doctor 契约以及 Doctor 的提供商/工具检查。仅源码插件仍从 checkout 加载。使用已构建输出时,重新构建以获取源码更改。有意选择的源码入口和挂载的源码覆盖层会继续使用源码,而不是其编译后的对应项。

此选择独立于 --dev 配置。它不会向任意本地链接、npm-pack: 安装或名称看似官方的插件授予受信任的插件能力。显式的 plugins.load.paths 覆盖仍然优先。同一独立发现的捆绑条目的别名会保留其捆绑来源。不同的本地副本仍不受信任。

除非你显式设置,否则 runner 会提供现有的 OPENCLAW_DEV_SOURCE_ROOT 选择器。直接启动 node dist/entry.js 进行调试时,将其设置为正在运行的 checkout 根目录,以获得相同的重复选择行为。它不会将无关的 checkout 添加到受信任的捆绑发现中。使用 pnpm openclaw plugins inspect <id> --json 检查所选源码和来源。

两个独立的 --dev 标志:

  • 全局 --dev(配置档): 将状态隔离在 ~/.openclaw-dev 下,并将 Gateway 端口默认为 19001(派生端口也随之偏移)。
  • gateway --dev: 指示 Gateway 在缺少默认配置 + 工作区时自动创建(并跳过 bootstrap)。

推荐流程(dev 配置档 + dev 引导):

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

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

其作用如下:

  1. 配置档隔离(全局 --dev)
  2. OPENCLAW_PROFILE=dev
  3. OPENCLAW_STATE_DIR=~/.openclaw-dev
  4. OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
  5. OPENCLAW_GATEWAY_PORT=19001(浏览器/画布端口随之偏移)

  6. Dev 引导(gateway --dev)

  7. 如果缺少配置,则写入一份最小配置(gateway.mode=local,绑定 loopback)。
  8. 将 agents.defaults.workspace 设置为 dev 工作区,并将 agents.defaults.skipBootstrap=true。
  9. 如果缺少工作区文件,则生成这些文件:AGENTS.md、SOUL.md、IDENTITY.md、USER.md。
  10. 默认身份:C3-PO(礼仪机器人)。
  11. pnpm gateway:dev 还会设置 OPENCLAW_SKIP_CHANNELS=1 以跳过频道提供者。

默认情况下,所有 Gateway 都会忽略环境中的频道自动配置触发器。因此,从启动 shell 继承的凭据不会在没有明确意图的情况下连接到频道服务。channels.<id> 配置块仍然会启用该频道,并且可以使用环境变量作为其凭据。传入 --ambient-channels 可为该次运行恢复环境频道自动配置。--dev-ambient-channels 标志保留为已弃用的别名。

重置流程(全新开始):

pnpm gateway:dev:reset

Note

--dev 是一个全局配置档标志,某些 runner 会吞掉它。如果需要显式指定,可以使用环境变量形式:

OPENCLAW_PROFILE=dev openclaw gateway --dev --reset

--reset 会清除配置、凭据、会话和 dev 工作区(工作区移入回收站,而非删除),然后重新创建默认的 dev 设置。

Tip

如果已有非 dev Gateway 正在运行(launchd 或 systemd),请先停止它:

openclaw gateway stop

原始流日志

OpenClaw 可以在任何过滤/格式化之前记录原始助手流。这是查看推理内容是以纯文本增量(还是单独的思维块)到达的最佳方式。

通过 CLI 启用:

pnpm gateway:watch --raw-stream

可选路径覆盖:

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

等效的环境变量:

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

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

安全注意事项

  • 原始流日志可能包含完整提示词、工具输出和用户数据。
  • 请将日志保留在本地,并在调试后删除。
  • 如果共享日志,请先清除机密信息和个人身份信息(PII)。

CLI 启动与命令性能分析

已签入的启动基准测试:

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

要通过常规源代码运行器进行一次性性能分析,请设置 OPENCLAW_RUN_NODE_CPU_PROF_DIR:

OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

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

某些启动卡顿看起来像是同步文件系统或模块加载器的工作。针对这些卡顿,可通过源代码运行器添加 Node 的同步 I/O 跟踪标志:

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch 默认会为被监视的 Gateway 子进程禁用此标志。如果你希望在 watch 模式下也获得同步 I/O 跟踪输出,请设置 OPENCLAW_TRACE_SYNC_IO=1。

插件生命周期跟踪

设置 OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 可获取插件元数据、发现、注册表、运行时镜像、配置变更和刷新工作的逐阶段分解信息。输出写入 stderr,因此 JSON 命令输出仍可解析。

启用此跟踪后,插件加载失败还会包含其堆栈跟踪。

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
[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 ... 命令还会测量源代码运行器的开销。

对于同步模块加载耗时,请使用共享的诊断界面,而不是单独的仅插件环境开关:

OPENCLAW_DIAGNOSTICS=plugin.load-profile openclaw plugins list

Node 和 tsx 启动错误

如果某个源代码运行的命令失败并显示 TypeError: __name is not a function,请收集 node --version、pnpm list tsx --depth 0、确切的命令和完整堆栈。并检查 Node 是否为受支持的版本。

在受信任的源代码检出中,请先运行 pnpm build,再通过 pnpm openclaw <command> 与构建后运行时进行失败对比。仓库的 typecheck 不会生成构建输出。请将失败的命令和版本证据保留在 bug 报告中,而不要套用旧调查中的临时解决方案。

在 VSCode 中调试

由于构建会对生成的文件名进行哈希处理,因此需要源代码映射。随附的 launch.json 以 Gateway 服务为目标:

  1. Rebuild and Debug Gateway - 删除 /dist,并在启动 Gateway 前以启用调试的方式重新构建。
  2. Debug Gateway - 在不修改 /dist 的情况下调试现有构建。

设置

  1. 打开 运行和调试(活动栏,或 Ctrl+Shift+D)。
  2. 选择 Rebuild and Debug Gateway,然后按 开始调试。

若要手动管理构建/调试周期,请执行以下操作:

  1. 在终端中启用源映射:
  2. Linux/macOS:export OUTPUT_SOURCE_MAPS=1
  3. Windows (PowerShell):$env:OUTPUT_SOURCE_MAPS="1"
  4. Windows (CMD):set OUTPUT_SOURCE_MAPS=1
  5. 重新构建:pnpm clean:dist && pnpm build
  6. 选择 Debug Gateway,然后按 开始调试。

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

备注

  • Rebuild and Debug Gateway 会在每次启动时删除 /dist 并运行一次带源映射的完整 pnpm build。
  • Debug Gateway 可以在不影响 /dist 的情况下启动/停止,但需要你在单独的终端中管理构建周期。
  • 编辑 launch.json 中的 args 以调试其他 CLI 子命令。
  • 你可以使用构建后的 CLI 执行其他任务。例如,如果调试会话生成了新的认证令牌,可以使用 dashboard --no-open。在另一个终端中运行 node ./openclaw.mjs,或使用类似 alias openclaw-build="node $(pwd)/openclaw.mjs" 的别名。

运行时调试覆盖

/debug 设置仅运行时的配置覆盖(内存中,而非磁盘上)。默认情况下此功能处于禁用状态。使用 commands.debug: true 启用它。

/debug show
/debug set channels.whatsapp.responsePrefix="[openclaw]"
/debug unset channels.whatsapp.responsePrefix
/debug reset

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

会话跟踪输出

/trace 显示单个会话中插件拥有的跟踪/调试行,而无需启用完整详细模式。可将其用于插件诊断,例如 Active Memory 调试摘要。对于常规状态/工具输出,请使用 /verbose。

/trace
/trace on
/trace off

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw