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 分析器。在源码检出目录中，先执行 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 分析标志，并为该命令写入一个 .cpuprofile。在命令代码中添加临时插桩前，应先使用此功能。

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

bash
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch 默认会为受监视的 Gateway 网关子进程禁用此标志；如果还需要在监视模式下输出同步 I/O 跟踪，请设置 OPENCLAW_TRACE_SYNC_IO=1。

Gateway 网关监视模式

bash
pnpm gateway:watch

默认情况下，此命令会启动或重启名为 openclaw-gateway-watch-<profile> 的 tmux 会话（例如 openclaw-gateway-watch-main）；仅当 OPENCLAW_GATEWAY_PORT 与默认端口 18789 不同时，才会添加类似 openclaw-gateway-watch-dev-19001 的端口后缀。它会从交互式终端自动连接；非交互式 shell、CI 和智能体 Exec 调用会保持分离状态，并改为输出连接说明：

bash
tmux attach -t openclaw-gateway-watch-main# 在不连接的情况下读取近期输出tmux capture-pane -ep -t openclaw-gateway-watch-main -S -200

该窗格使用 tmux remain-on-exit，因此启动失败信息会保留，可供连接或捕获，而不会删除会话。重新运行 pnpm gateway:watch 会重新生成该窗格。

tmux 窗格运行原始监视器：

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

在监视已配置的端口或默认端口前，tmux 包装器会停止当前配置文件中已安装的 Gateway 网关服务。这样可将端口交给源码监视器，避免 launchd、systemd 或计划任务重新生成服务并将其替换。服务仍保持安装状态；监视会话结束后，使用以下命令恢复服务：

bash
pnpm openclaw gateway start

当显式设置的 --port 或 OPENCLAW_GATEWAY_PORT 与已安装服务的有效端口不同时，包装器会让该服务继续运行，使两个 Gateway 网关能够并行运行。

不使用 tmux 的前台模式：

bash
pnpm gateway:watch:raw# 或OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

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

保留 tmux 管理但禁用自动连接：

bash
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

调试启动/运行时热点时，分析受监视 Gateway 网关的 CPU 时间：

bash
pnpm gateway:watch --benchmark

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

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

基准测试模式默认会抑制同步 I/O 跟踪产生的大量输出。将 OPENCLAW_TRACE_SYNC_IO=1 与 --benchmark 一同设置，即可同时获取 CPU 分析文件和同步 I/O 堆栈跟踪；在基准测试模式下，这些跟踪块会写入基准测试目录下的 gateway-watch-output.log（并从终端窗格中过滤掉），而常规 Gateway 网关日志仍保持可见。

tmux 包装器会将常用的非机密运行时选择项传入窗格，包括 OPENCLAW_PROFILE、OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR、OPENCLAW_GATEWAY_PORT 和 OPENCLAW_SKIP_CHANNELS。请将提供商凭据放入常规配置文件/配置中；如需使用一次性的临时密钥，请使用原始前台模式。

如果受监视的 Gateway 网关在启动期间退出，监视器会运行一次 openclaw doctor --fix --non-interactive，然后重启 Gateway 网关子进程。设置 OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0，可查看未经仅限开发环境的修复步骤处理的原始启动失败信息。

受管理的 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 标志，它们会在每次重启时透传。重新运行相同的监视命令会重新生成具名 tmux 窗格；原始监视器会保持单监视器锁，因此重复的监视器父进程会被替换，而不会不断堆积。

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

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

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

推荐流程（开发配置文件 + 开发引导初始化）：

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. 开发引导初始化（gateway --dev）

    • 如果缺失，则写入最小配置（gateway.mode=local，绑定 local loopback）。
    • 将 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 可以在任何过滤/格式化之前记录原始助手流。这是确认推理是否以纯文本增量（或独立思考块）形式到达的最佳方式。

通过 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

安全说明

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

在 VSCode 中调试

由于构建过程会对生成的文件名进行哈希处理，因此必须使用源码映射。内置的 launch.json 面向 Gateway 网关服务：

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

设置

  1. 打开 Run and Debug（Activity Bar，或 Ctrl+Shift+D）。
  2. 选择 Rebuild and Debug Gateway，然后按 Start Debugging。

如果要改为手动管理构建/调试周期：

  1. 在终端中启用源码映射：
    • 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. 选择 Debug Gateway，然后按 Start Debugging。

在 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" 的别名。

相关内容

Was this useful?
On this page

On this page