Debugging

Trang này hướng dẫn các công cụ debug cho streaming output, đặc biệt khi provider trộn lẫn reasoning vào text thông thường.

Runtime debug overrides

Dùng /debug trong chat để thiết lập config overrides chỉ ở runtime (lưu trong memory, không ghi vào disk). /debug mặc định bị tắt; bật lên bằng cách set commands.debug: true. Cái này tiện khi các bạn cần toggle các setting khó tìm mà không muốn edit openclaw.json.

Ví dụ:

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

/debug reset xóa tất cả overrides và quay về config trên disk.

Gateway watch mode

Để phát triển nhanh, chạy gateway dưới file watcher:

pnpm gateway:watch --force

Lệnh này tương đương với:

tsx watch src/entry.ts gateway --force

Các bạn có thể thêm bất kỳ gateway CLI flags nào sau gateway:watch và chúng sẽ được truyền qua mỗi lần restart.

Dev profile + dev gateway (—dev)

Dùng dev profile để cô lập state và tạo một setup an toàn, có thể xóa đi để debug. Có hai flag --dev:

  • Global --dev (profile): cô lập state dưới ~/.openclaw-dev và đặt gateway port mặc định là 19001 (các derived ports cũng thay đổi theo).
  • gateway --dev: bảo Gateway tự động tạo config mặc định + workspace khi thiếu (và bỏ qua BOOTSTRAP.md).

Quy trình khuyên dùng (dev profile + dev bootstrap):

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

Nếu các bạn chưa cài global, chạy CLI qua pnpm openclaw ....

Lệnh này làm gì:

  1. Profile isolation (global --dev)

    • OPENCLAW_PROFILE=dev
    • OPENCLAW_STATE_DIR=~/.openclaw-dev
    • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
    • OPENCLAW_GATEWAY_PORT=19001 (browser/canvas cũng thay đổi theo)

  2. Dev bootstrap (gateway --dev)

    • Ghi một config tối thiểu nếu thiếu (gateway.mode=local, bind loopback).
    • Set agent.workspace thành dev workspace.
    • Set agent.skipBootstrap=true (không có BOOTSTRAP.md).
    • Tạo sẵn các workspace files nếu thiếu: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md.
    • Identity mặc định: C3‑PO (protocol droid).
    • Bỏ qua channel providers ở dev mode (OPENCLAW_SKIP_CHANNELS=1).

Reset flow (bắt đầu lại từ đầu):

pnpm gateway:dev:reset

Lưu ý: --dev là flag global profile và có thể bị một số runners ăn mất. Nếu cần viết rõ ràng, dùng dạng env var:

OPENCLAW_PROFILE=dev openclaw gateway --dev --reset

--reset xóa config, credentials, sessions, và dev workspace (dùng trash, không phải rm), sau đó tạo lại dev setup mặc định.

Mẹo: nếu một gateway không phải dev đang chạy (launchd/systemd), dừng nó trước:

openclaw gateway stop

Raw stream logging (OpenClaw)

OpenClaw có thể log raw assistant stream trước khi filtering/formatting. Đây là cách tốt nhất để xem reasoning có đang đến dưới dạng plain text deltas hay không (hoặc là các thinking blocks riêng biệt).

Bật lên qua CLI:

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

Override path tùy chọn:

pnpm gateway:watch --force --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl

Env vars tương đương:

OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl

File mặc định:

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

Raw chunk logging (pi-mono)

Để capture raw OpenAI-compat chunks trước khi chúng được parse thành blocks, pi-mono cung cấp một logger riêng:

PI_RAW_STREAM=1

Path tùy chọn:

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

File mặc định:

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

Lưu ý: cái này chỉ được emit bởi các processes dùng provider openai-completions của pi-mono.

Lưu ý an toàn

  • Raw stream logs có thể chứa full prompts, tool output, và user data.
  • Giữ logs ở local và xóa chúng sau khi debug xong.
  • Nếu chia sẻ logs, nhớ xóa secrets và PII trước nhé.