6.25 调试指南

网关与运维网关与运维

本页整理 Gateway 常见调试入口，重点覆盖流式输出与开发模式。

运行时调试覆盖（/debug）

在聊天中使用 /debug 设置仅内存的配置覆盖（不会写磁盘）。默认关闭，需启用 commands.debug: true。

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

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

Gateway 监视模式（热重载）

开发时推荐使用 file watcher：

pnpm gateway:watch --force

等价命令：

tsx watch src/entry.ts gateway --force

在 gateway:watch 后追加的 CLI 参数会在每次重启时保留。

Dev Profile + Dev Gateway（--dev）

调试时建议启用 dev profile，隔离状态目录并生成安全的默认配置：

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

推荐流程：

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

若没有全局安装，可用 pnpm openclaw ... 代替 CLI。

Dev Profile 会做什么

  • OPENCLAW_PROFILE=dev
  • OPENCLAW_STATE_DIR=~/.openclaw-dev
  • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
  • OPENCLAW_GATEWAY_PORT=19001（浏览器/画布端口同步偏移）

Dev Gateway 会：

  • 创建最小配置（gateway.mode=local，仅绑定 loopback）。
  • 设置 dev 工作区并跳过 BOOTSTRAP.md（agent.skipBootstrap=true）。
  • 生成默认工作区文件：AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md。
  • 默认身份为 C3‑PO（protocol droid）。
  • 跳过频道提供商（OPENCLAW_SKIP_CHANNELS=1）。

重置 Dev 环境

pnpm gateway:dev:reset

如果全局 --dev 被 runner 吞掉，可用环境变量形式：

OPENCLAW_PROFILE=dev openclaw gateway --dev --reset

--reset 会清理配置、凭据、会话与 dev 工作区（使用 trash，而非 rm），然后重建默认 dev 设置。若已有非 dev gateway（launchd/systemd）在运行，先停掉：

openclaw gateway stop

原始流日志（OpenClaw）

可记录经过任何过滤/格式化之前的原始 assistant stream，用于判断“推理内容是否混入普通文本”。

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

原始 Chunk 日志（pi-mono）

若使用 pi-mono 的 openai-completions provider，可记录“解析为 blocks 前”的原始 chunk：

PI_RAW_STREAM=1

可选路径：

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

默认文件：~/.pi-mono/logs/raw-openai-completions.jsonl。

安全注意事项

  • 原始流日志可能包含完整提示词、工具输出和用户数据。
  • 建议仅本地保存，调试后尽快删除。
  • 如需分享，请先清理机密与个人信息。