调试

本页介绍用于 Streaming 输出的调试工具，特别是当 Provider 将推理内容混入正常文本时。

Runtime 调试覆盖

在聊天中使用 /debug 来设置 仅 Runtime 的配置覆盖（内存中，不写入磁盘）。 /debug 默认禁用；通过 commands.debug: true 启用。当你需要切换一些不常用的设置而不想编辑 openclaw.json 时，这很方便。

示例：

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

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

为了快速迭代，可以在文件监视器下运行 Gateway：

pnpm gateway:watch --force

这相当于：

tsx watch src/entry.ts gateway --force

在 gateway:watch 后添加任何 Gateway CLI 参数，它们会在每次重启时传递。

使用 dev profile 来隔离状态，并启动一个安全、可丢弃的调试环境。有两个 --dev 标志：

全局 --dev (profile)： 将状态隔离到 ~/.openclaw-dev 下，并将 Gateway 端口默认设为 19001（派生端口也会相应调整）。
gateway --dev：告诉 Gateway 在缺失时自动创建默认配置 + Workspace（并跳过 BOOTSTRAP.md）。

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

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

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

这会做什么：

Profile 隔离（全局 --dev）
- OPENCLAW_PROFILE=dev
- OPENCLAW_STATE_DIR=~/.openclaw-dev
- OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
- OPENCLAW_GATEWAY_PORT=19001（浏览器/画布端口也会相应调整）
Dev bootstrap（gateway --dev）
- 如果缺失则写入最小配置（gateway.mode=local，绑定本地回环）。
- 将 agent.workspace 设置为 dev workspace。
- 设置 agent.skipBootstrap=true（不使用 BOOTSTRAP.md）。
- 如果缺失则生成 Workspace 文件： AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md。
- 默认身份：C3‑PO（协议机器人）。
- 在 dev 模式下跳过 Channel Provider（OPENCLAW_SKIP_CHANNELS=1）。

重置流程（全新开始）：

pnpm gateway:dev:reset

注意：--dev 是一个全局 profile 标志，会被某些运行器吞掉。如果需要明确指定，使用环境变量形式：

OPENCLAW_PROFILE=dev openclaw gateway --dev --reset

--reset 会清除配置、凭证、Session 和 dev workspace（使用 trash 而非 rm），然后重新创建默认的 dev 设置。

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

openclaw gateway stop

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

通过 CLI 启用：

pnpm gateway:watch --force --raw-stream

可选路径覆盖：

pnpm gateway:watch --force --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

要在解析为块之前捕获 原始 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 Provider 的进程输出。