调试

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

网关监视模式¶

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 包装器会停止当前活动配置文件已安装的 Gateway 服务。这样就把端口交给了源码监视器，而不会让 launchd、systemd 或 Scheduled Task 将其重新拉起并替换。该服务仍然保持已安装状态。监视会话结束后，用以下命令恢复它：

pnpm openclaw gateway start

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

不使用 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

在调试启动/运行时热点时，对受监视的 Gateway 进行 CPU 时间剖析：

pnpm gateway:watch --benchmark

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

npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile

--benchmark-dir <path>：将剖析文件写到其他位置。
--benchmark-no-force：跳过默认的 --force 端口清理；如果 Gateway 端口已被占用，则快速失败。

基准测试模式默认会抑制同步 I/O 跟踪刷屏。在 --benchmark 时设置 OPENCLAW_TRACE_SYNC_IO=1，可以同时获得 CPU 剖析文件和同步 I/O 堆栈跟踪。在基准测试模式下，这些跟踪块会写入基准测试目录下的 gateway-watch-output.log（从终端窗格中过滤掉）。正常的 Gateway 日志仍然可见。

tmux 包装器会把常见的非机密运行时选择器带入窗格，包括 OPENCLAW_PROFILE、OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR、OPENCLAW_GATEWAY_PORT 和 OPENCLAW_SKIP_CHANNELS。请将 provider 凭据放在常规的 profile/config 中，或者使用原始前台模式来处理一次性的临时机密。

如果受监视的 Gateway 返回启动错误，监视器会运行一次 openclaw doctor --fix --non-interactive，然后重启 Gateway 子进程。设置 OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 可以查看原始的启动失败信息，而不会执行仅限开发环境的修复步骤。

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

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

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

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

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

开发配置文件 + 开发网关 (--dev)¶

当你从某个 checkout 运行 pnpm openclaw、pnpm dev 或 Gateway 开发 runner 时，runner 会优先选择该 checkout 中的插件，而不是具有相同 id 的受跟踪全局副本。在可用的情况下，已构建的插件输出仍然是首选，包括单独发布的 checkout 插件、Doctor 契约以及 Doctor 的 provider/tool 检查。仅源码的插件仍然从 checkout 加载。使用已构建输出时，请重建以获取源码更改。有意的源码入口选择以及挂载的源码覆盖层会继续使用源码，而不是其编译后的对应版本。

这种选择与 --dev profile 是分开的。它不会向任意的本地链接、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 下，并将网关端口默认为 19001（派生端口随之偏移）。
gateway --dev： 告诉 Gateway 在缺少默认配置和工作区时自动创建（并跳过 bootstrap）。

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

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

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

其作用如下：

配置文件隔离（全局 --dev）
OPENCLAW_PROFILE=dev
OPENCLAW_STATE_DIR=~/.openclaw-dev
OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
OPENCLAW_GATEWAY_PORT=19001（浏览器/画布端口随之偏移）
开发 bootstrap（gateway --dev）
当配置缺失时写入最小配置（gateway.mode=local，绑定回环地址）。
将 agents.defaults.workspace 设置为开发工作区，并将 agents.defaults.skipBootstrap 设为 true。
当工作区文件缺失时写入初始文件：AGENTS.md、SOUL.md、IDENTITY.md、USER.md。
默认身份：C3-PO（礼仪机器人）。
pnpm gateway:dev 还会设置 OPENCLAW_SKIP_CHANNELS=1 以跳过渠道提供方。

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

重置流程（全新开始）：

pnpm gateway:dev:reset

Note

--dev 是一个全局配置文件标志，会被某些运行器吞掉。如果需要显式指定，请使用环境变量形式：

OPENCLAW_PROFILE=dev openclaw gateway --dev --reset

--reset 会清除配置、凭据、会话以及开发工作区（移至回收站而非删除），然后重新创建默认开发环境。

Tip

如果已有非开发模式的 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 性能分析标志，并为该命令写入一份 .cpuprofile。在向命令代码添加临时插桩之前，请先使用此方法。

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

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch 默认会为被监视的 Gateway 子进程禁用此标志。如果希望在监视模式下也输出同步 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 性能分析器之前，请先使用此方法。从源码检出中，先执行 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 openclaw <command> 将失败与构建后的运行时进行比较之前，请先从可信的源码检出中运行 pnpm build。仓库的类型检查不会生成构建输出。请在 bug 报告中保留失败命令和版本证据，而不是套用旧调查中的变通方案。

在 VSCode 中调试¶

由于构建会哈希生成的文件名，因此需要 source map。附带的 launch.json 以 Gateway 服务为目标：

Rebuild and Debug Gateway - 删除 /dist，并在启动 Gateway 之前启用调试重新构建。
Debug Gateway - 调试现有构建，不触碰 /dist。

设置¶

打开 运行和调试（活动栏，或 Ctrl+Shift+D）。
选择 Rebuild and Debug Gateway，然后按 开始调试。

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

在终端中启用源映射：
Linux/macOS：export OUTPUT_SOURCE_MAPS=1
Windows (PowerShell)：$env:OUTPUT_SOURCE_MAPS="1"
Windows (CMD)：set OUTPUT_SOURCE_MAPS=1
重新构建：pnpm clean:dist && pnpm build
选择 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

调试