调试

本页介绍流式输出的调试辅助工具，尤其适用于模型提供商将推理内容混入普通文本输出的场景。

运行时 debug 覆盖

在聊天中使用 /debug 设置仅运行时的配置覆盖（内存中，不写入磁盘）。 /debug 默认禁用；通过 commands.debug: true 启用。 当你需要在不编辑 openclaw.json 的情况下切换某些冷门设置时，这非常方便。

示例：

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

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

Gateway watch 模式

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

pnpm gateway:watch

等价于：

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

监视器会在以下文件变化时重启：src/ 下的构建相关文件、扩展源文件、扩展 package.json 和 openclaw.plugin.json 元数据、tsconfig.json、package.json、tsdown.config.ts。扩展元数据变更会在不强制 tsdown 重建的情况下重启 Gateway；源代码和配置变更仍会先重建 dist。

在 gateway:watch 后追加任意 Gateway CLI 参数，这些参数会在每次重启时传递。

开发 profile + 开发 Gateway（--dev）

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

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

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

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

如果尚未全局安装，通过 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（浏览器/画布端口随之调整）

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）。

重置流程（全新开始）：

pnpm gateway:dev:reset

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

OPENCLAW_PROFILE=dev openclaw gateway --dev --reset

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

提示：如果非 dev Gateway 已在运行（launchd/systemd），先停止它：

openclaw gateway stop

原始流日志（OpenClaw）

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

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

原始块日志（pi-mono）

要在 OpenAI 兼容块被解析成块之前捕获它们，pi-mono 提供了一个独立的日志器：

PI_RAW_STREAM=1

可选路径：

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

默认文件路径：

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

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

安全提示

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