古法编程

Appearance

遇到模型混合推理文本、Gateway 启动慢或插件命令卡顿，可以用 OpenClaw 内置调试工具。运行时覆盖用 /debug（需先启用 commands.debug: true）；监视模式用 pnpm gateway:watch 启动 tmux 会话自动重启；原始流日志 pnpm gateway:watch --raw-stream 记录未过滤的助手输出排查推理泄漏。插件生命周期追踪设 OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 查看各阶段耗时。开发隔离用 pnpm gateway:dev 搭配 OPENCLAW_PROFILE=dev，状态独立、默认端口 19001。VSCode 调试前需 OUTPUT_SOURCE_MAPS=1 构建生成 source map。

OpenClaw 调试指南：Watch 模式、原始流日志与开发环境 ​

调试辅助工具主要处理流式输出，尤其当模型提供商将推理内容混入普通文本时很有用。

运行时 debug 覆盖 ​

在聊天中输入 /debug 可以设置仅运行时的配置覆盖（存在内存中，不写入磁盘）。/debug 默认关闭，需通过 commands.debug: true 启用。当你需要临时切换某些不常用设置而不编辑 openclaw.json 时，这个命令很方便。

示例：

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

/debug reset 清除所有运行时覆盖，恢复磁盘配置。

会话跟踪输出 ​

用 /trace 查看某个会话中插件特有的追踪/调试行，无需开启完整的 verbose 模式。

示例：

text
/trace
/trace on
/trace off

/trace 用于插件诊断（如 Active Memory 调试摘要）。正常的状态/工具输出仍用 /verbose，运行时配置覆盖仍用 /debug。

插件生命周期追踪 ​

当插件生命周期命令感觉卡顿时，设置 OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 可以查看插件元数据、发现、注册表、运行时镜像、配置变更和刷新工作的内置阶段耗时。该追踪是 opt-in 的，写入 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 之前，先用这个追踪插件生命周期。如果命令从源码检出运行，建议用 node dist/entry.js ...（先 pnpm build）测量构建后的运行时间；pnpm openclaw ... 会包括源码运行器的额外开销。

CLI 启动和命令性能分析 ​

当命令感觉变慢时，使用代码仓库中内置的启动基准测试：

bash
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：

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 默认禁用了该标志。在 watch 模式下如果明确需要 Node 同步 I/O 跟踪输出，设置 OPENCLAW_TRACE_SYNC_IO=1。

Gateway watch 模式 ​

快速迭代时，在文件监视器下运行 gateway：

bash
pnpm gateway:watch

默认情况下，这会启动或重启一个名为 openclaw-gateway-watch-main 的 tmux 会话（或带 profile/端口后缀的变体，如 openclaw-gateway-watch-dev-19001），并从交互式终端自动附加。非交互式 shell、CI 和 agent exec 调用保持分离状态，只打印附加指令。需要时手动附加：

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

tmux 窗格运行的原始监视器命令：

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

如果不需要 tmux，使用前台模式：

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

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

bash
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

调试启动/运行时热点时，对 watch 模式下的 gateway 做 CPU 性能分析：

bash
pnpm gateway:watch --benchmark

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

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

用 --benchmark-dir <path> 指定其他 profile 目录。用 --benchmark-no-force 让 benchmark 子进程跳过默认的 --force 端口清理，在 gateway 端口已被占用时快速失败。Benchmark 模式默认抑制同步 I/O 跟踪输出；如果同时需要 CPU profile 和 Node 同步 I/O 堆栈跟踪，设置 OPENCLAW_TRACE_SYNC_IO=1 和 --benchmark。在 benchmark 模式下，跟踪块会写入 benchmark 目录下的 gateway-watch-output.log，终端窗格中只过滤掉这些跟踪信息，正常的 Gateway 日志仍然可见。

tmux 包装器会把公共的非机密运行时选择器（如 OPENCLAW_PROFILE、OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR、OPENCLAW_GATEWAY_PORT、OPENCLAW_SKIP_CHANNELS）传递到窗格。把提供商凭证放在正常的 profile/config 中，或者使用前台原始模式运行一次性临时机密。

如果 watch 的 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 但不强制 tsdown 重建；源码和配置变化会先重建 dist 再重启。

在 gateway:watch 后添加任意 gateway CLI 参数，每次重启时都会传递。重复运行相同的 watch 命令会重新生成指定的 tmux 窗格，原始监视器仍然持有单监视器锁，因此重复的监视器父进程会被替换而不会堆积。

开发 profile + 开发 gateway（--dev） ​

使用 dev profile 隔离状态，为调试创建安全、可丢弃的环境。有两个 --dev 标志：

  • 全局 --dev（profile）：将状态隔离到 ~/.openclaw-dev，默认 gateway 端口为 19001（派生端口随之偏移）。
  • gateway --dev：缺少默认配置 + 工作区时自动创建（并跳过 BOOTSTRAP.md）。

推荐流程（dev profile + dev bootstrap）：

bash
pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

如果尚未全局安装 OpenClaw，用 pnpm openclaw ... 运行 CLI。

具体效果：

  1. Profile 隔离（全局 --dev）

    • OPENCLAW_PROFILE=dev
    • OPENCLAW_STATE_DIR=~/.openclaw-dev
    • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
    • OPENCLAW_GATEWAY_PORT=19001（浏览器/canvas 端口随之调整）

  2. Dev bootstrap（gateway --dev）

    • 如果缺少配置，写入最小配置（gateway.mode=local，绑定回环）。
    • 设置 agent.workspace 为 dev 工作区。
    • 设置 agent.skipBootstrap=true（不生成 BOOTSTRAP.md）。
    • 如果工作区文件缺失，植入初始文件：AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md。
    • 默认身份：C3-PO（协议机器人）。
    • Dev 模式跳过渠道提供商（OPENCLAW_SKIP_CHANNELS=1）。

重置流程（全新开始）：

bash
pnpm gateway:dev:reset

--dev 是全局 profile 标志，某些运行器会将其消耗掉。如需明确指定，使用环境变量形式：

bash
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset

--reset 会清除配置、凭据、会话和 dev 工作区（使用 trash 而非 rm），然后重新创建默认 dev 设置。

如果非 dev Gateway 已在运行（通过 launchd 或 systemd），先停止它：

bash
openclaw gateway stop

原始流日志（OpenClaw） ​

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

通过 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=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl

默认文件：

~/.openclaw/logs/raw-stream.jsonl

原始块日志（pi-mono） ​

要捕获尚未解析成块的原始 OpenAI 兼容块，pi-mono 提供了一个独立的日志器：

bash
PI_RAW_STREAM=1

可选路径：

bash
PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl

默认文件：

~/.pi-mono/logs/raw-openai-completions.jsonl

注意：此日志只由使用 pi-mono 的 openai-completions 提供商的项目输出。

安全提示 ​

  • 原始流日志可能包含完整的提示词、工具输出和用户数据。
  • 日志请保存在本地，调试完成后删除。
  • 如果需要分享日志，请先清理其中的密钥和个人信息。

VSCode 调试 ​

在基于 VSCode 的 IDE 中调试需要启用 source map，因为构建过程生成的文件名包含 hash。项目中包含 launch.json 配置，目标为 Gateway 服务，但可快速适配其他用途：

  1. Rebuild and Debug Gateway — 新建构建后调试 Gateway 服务
  2. Debug Gateway — 调试已有构建的 Gateway 服务

设置 ​

默认的 Rebuild and Debug Gateway 配置开箱即用，会自动删除 /dist 文件夹并以调试模式重建项目：

  1. 从活动栏打开 Run and Debug 面板，或按 Ctrl+Shift+D
  2. 在 IDE 中，确保配置下拉菜单选择 Rebuild and Debug Gateway，然后按 Start Debugging 按钮

或者，如果希望手动管理构建和调试：

  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. 在 IDE 的 Run and Debug 配置下拉菜单中选择 Debug Gateway，然后按 Start Debugging 按钮

现在可以在 TypeScript 源文件（src/ 目录）中设置断点，调试器会通过 source map 正确映射到编译后的 JavaScript。可以按预期检查变量、单步执行代码和查看调用栈。

注意事项 ​

  • 如果使用 "Rebuild and Debug Gateway" 选项，每次启动调试时都会完全删除 /dist 文件夹并运行完整的 pnpm build（启用 source map），然后再启动 Gateway。
  • 如果使用 "Debug Gateway" 选项，调试会话可以随时启动和停止，不影响 /dist 文件夹；但必须使用单独的终端进程来启用调试和管理构建周期。
  • 修改 launch.json 中的 args 设置可以调试项目的其他部分。
  • 如果需要使用构建后的 OpenClaw CLI 执行其他任务（例如 dashboard --no-open 以获取调试会话生成的新 auth token），可以在另一个终端中通过 node ./openclaw.mjs 运行，或创建 shell 别名：alias openclaw-build="node $(pwd)/openclaw.mjs"。

常见问题 ​

/debug 命令不生效怎么办？ ​

先确认已在 openclaw.json 中启用 commands.debug: true。/debug 默认禁用。如果仍然不生效，检查是否处于没有聊天权限的渠道会话中。

Gateway watch 模式下启动失败如何处理？ ​

监视器会自动执行 openclaw doctor --fix --non-interactive 一次并重启。如果想保留原始失败信息做分析，设置 OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0。也可以手动执行 openclaw doctor 查看详细修复建议。

怎么确认推理内容是否以 thinking 块形式到达？ ​

启用原始流日志：pnpm gateway:watch --raw-stream，然后查看 ~/.openclaw/logs/raw-stream.jsonl 中的未过滤输出。如果看到单独的 reasoning 或 thinking 字段块，则推理是分开的；如果混合在 content 增量中，则是作为普通文本。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策