การดีบัก

ตัวช่วยดีบักสำหรับเอาต์พุตแบบสตรีม โดยเฉพาะเมื่อผู้ให้บริการผสมเหตุผลเข้ากับข้อความปกติ

การแทนที่ค่าดีบักขณะรันไทม์

ใช้ /debug ในแชทเพื่อตั้งค่าการแทนที่ config แบบ เฉพาะรันไทม์ (อยู่ในหน่วยความจำ ไม่ได้เขียนลงดิสก์) /debug ถูกปิดใช้โดยค่าเริ่มต้น; เปิดใช้ด้วย commands.debug: true วิธีนี้สะดวกเมื่อคุณต้องสลับการตั้งค่าที่ไม่ค่อยได้ใช้โดยไม่ต้องแก้ไข openclaw.json

ตัวอย่าง:

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

/debug reset จะล้างการแทนที่ทั้งหมดและกลับไปใช้ config บนดิสก์

เอาต์พุต trace ของเซสชัน

ใช้ /trace เมื่อคุณต้องการดูบรรทัด trace/ดีบักที่ Plugin เป็นเจ้าของในเซสชันเดียว โดยไม่ต้องเปิดโหมด verbose เต็มรูปแบบ

ตัวอย่าง:

/trace/trace on/trace off

ใช้ /trace สำหรับการวินิจฉัย Plugin เช่น สรุปดีบักของ Active Memory ใช้ /verbose ต่อไปสำหรับสถานะ verbose และเอาต์พุตเครื่องมือแบบปกติ และใช้ /debug ต่อไปสำหรับการแทนที่ config แบบเฉพาะรันไทม์

trace วงจรชีวิต Plugin

ใช้ OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 เมื่อคำสั่งวงจรชีวิต Plugin รู้สึกช้า และคุณต้องการการแจกแจงเฟสในตัวสำหรับเมตาดาตา Plugin, การค้นพบ, registry, runtime mirror, การเปลี่ยนแปลง config และงานรีเฟรช trace นี้เป็นแบบเลือกเปิดและเขียน ไปยัง stderr ดังนั้นเอาต์พุตคำสั่ง JSON จึงยัง parse ได้

ตัวอย่าง:

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

ตัวอย่างเอาต์พุต:

[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"

ใช้สิ่งนี้เพื่อตรวจสอบวงจรชีวิต Plugin ก่อนจะหันไปใช้ CPU profiler หากคำสั่งรันจาก source checkout ให้เลือกวัดรันไทม์ที่ build แล้ว ด้วย node dist/entry.js ... หลังจาก pnpm build; pnpm openclaw ... จะวัด overhead ของ source-runner ด้วยเช่นกัน

การโปรไฟล์การเริ่มต้น CLI และคำสั่ง

ใช้ benchmark การเริ่มต้นที่เช็คอินไว้เมื่อคำสั่งรู้สึกช้า:

pnpm test:startup:bench:smokepnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu

สำหรับการโปรไฟล์ครั้งเดียวผ่าน source runner ปกติ ให้ตั้ง OPENCLAW_RUN_NODE_CPU_PROF_DIR:

OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

source runner จะเพิ่มแฟล็ก Node CPU profile และเขียน .cpuprofile สำหรับ คำสั่ง ใช้วิธีนี้ก่อนเพิ่ม instrumentation ชั่วคราวลงในโค้ดคำสั่ง

สำหรับอาการค้างตอนเริ่มต้นที่ดูเหมือนงานระบบไฟล์แบบ synchronous หรืองาน module-loader ให้เพิ่มแฟล็ก sync I/O trace ของ Node ผ่าน source runner:

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch จะปิดแฟล็กนี้โดยค่าเริ่มต้นสำหรับ Gateway child ที่ถูก watch ตั้ง OPENCLAW_TRACE_SYNC_IO=1 เมื่อคุณต้องการเอาต์พุต Node sync I/O trace ในโหมด watch อย่างชัดเจน

โหมด watch ของ Gateway

สำหรับการวนแก้ไขอย่างรวดเร็ว ให้รัน gateway ภายใต้ file watcher:

pnpm gateway:watch

โดยค่าเริ่มต้น คำสั่งนี้จะเริ่มหรือรีสตาร์ตเซสชัน tmux ชื่อ openclaw-gateway-watch-main (หรือ variant เฉพาะ profile/port เช่น openclaw-gateway-watch-dev-19001) และ auto-attach จากเทอร์มินัลแบบโต้ตอบ shell แบบไม่โต้ตอบ, CI และการเรียก agent exec จะยังคง detached และพิมพ์คำแนะนำ การ attach แทน attach เองเมื่อจำเป็น:

tmux attach -t openclaw-gateway-watch-main

pane ของ tmux จะรัน watcher ดิบ:

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

ใช้โหมด foreground เมื่อไม่ต้องการ tmux:

pnpm gateway:watch:raw# orOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

ปิด auto-attach โดยยังคงการจัดการ tmux ไว้:

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

โปรไฟล์เวลา CPU ของ Gateway ที่ถูก watch เมื่อดีบัก hotspot ตอนเริ่มต้น/รันไทม์:

pnpm gateway:watch --benchmark

watch wrapper จะ consume --benchmark ก่อนเรียกใช้ Gateway และเขียน V8 .cpuprofile หนึ่งไฟล์ต่อการออกของ Gateway child แต่ละครั้งไว้ใต้ .artifacts/gateway-watch-profiles/ หยุดหรือรีสตาร์ต gateway ที่ถูก watch เพื่อ flush profile ปัจจุบัน จากนั้นเปิดด้วย Chrome DevTools หรือ Speedscope:

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

ใช้ --benchmark-dir <path> เมื่อคุณต้องการเก็บ profile ไว้ที่อื่น ใช้ --benchmark-no-force เมื่อคุณต้องการให้ child ที่ถูก benchmark ข้ามการ cleanup port ค่าเริ่มต้น --force และ fail fast หากพอร์ต Gateway ถูกใช้งานอยู่แล้ว โหมด benchmark จะกด spam ของ sync-I/O trace โดยค่าเริ่มต้น ตั้ง OPENCLAW_TRACE_SYNC_IO=1 ร่วมกับ --benchmark เมื่อคุณต้องการทั้ง CPU profile และ stack trace ของ Node sync-I/O อย่างชัดเจน ในโหมด benchmark บล็อก trace เหล่านั้น จะถูกเขียนไปยัง gateway-watch-output.log ใต้ไดเรกทอรี benchmark และ ถูกกรองออกจาก pane ของเทอร์มินัล; log ปกติของ Gateway ยังคงมองเห็นได้

tmux wrapper จะส่งตัวเลือก runtime ที่ไม่ใช่ความลับทั่วไป เช่น OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT และ OPENCLAW_SKIP_CHANNELS เข้าไปใน pane ใส่ credentials ของ provider ไว้ใน profile/config ปกติของคุณ หรือใช้โหมด raw foreground สำหรับความลับชั่วคราวแบบครั้งเดียว หาก Gateway ที่ถูก watch ออกระหว่างการเริ่มต้น watcher จะรัน openclaw doctor --fix --non-interactive หนึ่งครั้งและรีสตาร์ต Gateway child ใช้ OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 เมื่อคุณต้องการดูความล้มเหลวตอนเริ่มต้นเดิม โดยไม่มีรอบซ่อมสำหรับ dev เท่านั้น pane ของ tmux ที่ถูกจัดการยังใช้ log Gateway แบบมีสีเป็นค่าเริ่มต้นเพื่อให้อ่านง่าย; ตั้ง FORCE_COLOR=0 เมื่อเริ่ม pnpm gateway:watch เพื่อปิดเอาต์พุต ANSI

watcher จะรีสตาร์ตเมื่อมีไฟล์ที่เกี่ยวข้องกับ build ใต้ src/, ไฟล์ source ของ extension, เมตาดาตา package.json และ openclaw.plugin.json ของ extension, tsconfig.json, package.json และ tsdown.config.ts เปลี่ยนแปลง การเปลี่ยนแปลงเมตาดาตา extension จะรีสตาร์ต gateway โดยไม่บังคับ rebuild tsdown; การเปลี่ยนแปลง source และ config ยังจะ rebuild dist ก่อน

เพิ่มแฟล็ก CLI ของ gateway ใด ๆ หลัง gateway:watch แล้วแฟล็กเหล่านั้นจะถูกส่งผ่านใน การรีสตาร์ตแต่ละครั้ง การรันคำสั่ง watch เดิมซ้ำจะ respawn pane tmux ที่มีชื่อนั้น และ raw watcher ยังคงรักษา lock แบบ single-watcher ของตัวเองไว้ ดังนั้น parent watcher ที่ซ้ำกัน จะถูกแทนที่แทนที่จะสะสมเพิ่ม

Dev profile + dev gateway (--dev)

ใช้ dev profile เพื่อแยก state และเปิดชุดตั้งค่าที่ปลอดภัย ใช้แล้วทิ้งได้สำหรับ การดีบัก มีแฟล็ก --dev สอง แบบ:

• Global --dev (profile): แยก state ไว้ใต้ ~/.openclaw-dev และ ตั้งพอร์ต gateway ค่าเริ่มต้นเป็น 19001 (พอร์ตที่ derive มาจะเลื่อนตาม)
• gateway --dev: บอกให้ Gateway สร้าง config + workspace ค่าเริ่มต้นโดยอัตโนมัติ เมื่อไม่มีอยู่ (และข้าม BOOTSTRAP.md)

flow ที่แนะนำ (dev profile + dev bootstrap):

pnpm gateway:devOPENCLAW_PROFILE=dev openclaw tui

หากคุณยังไม่มี global install ให้รัน CLI ผ่าน pnpm openclaw ...

สิ่งที่คำสั่งนี้ทำ:

1. การแยก profile (global --dev)

   • OPENCLAW_PROFILE=dev
   • OPENCLAW_STATE_DIR=~/.openclaw-dev
   • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
   • OPENCLAW_GATEWAY_PORT=19001 (browser/canvas จะเลื่อนตาม)

2. Dev bootstrap (gateway --dev)

   • เขียน config ขั้นต่ำหากไม่มี (gateway.mode=local, bind loopback)
   • ตั้ง agent.workspace เป็น dev workspace
   • ตั้ง agent.skipBootstrap=true (ไม่มี BOOTSTRAP.md)
   • seed ไฟล์ workspace หากไม่มี: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md
   • identity ค่าเริ่มต้น: C3-PO (protocol droid)
   • ข้าม provider ของ channel ในโหมด dev (OPENCLAW_SKIP_CHANNELS=1)

flow สำหรับ reset (เริ่มใหม่):

pnpm gateway:dev:reset

--reset จะลบ config, credentials, sessions และ dev workspace (ใช้ trash ไม่ใช่ rm) จากนั้นสร้างชุด dev ค่าเริ่มต้นใหม่

การ logging สตรีมดิบ (OpenClaw)

OpenClaw สามารถ log สตรีม assistant ดิบ ก่อนการกรอง/จัดรูปแบบใด ๆ นี่เป็นวิธีที่ดีที่สุดในการดูว่า reasoning มาถึงเป็น plain text deltas (หรือเป็นบล็อก thinking แยกต่างหาก)

เปิดใช้ผ่าน CLI:

pnpm gateway:watch --raw-stream

override path แบบเลือกได้:

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

env vars ที่เทียบเท่า:

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

ไฟล์ค่าเริ่มต้น:

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

การ logging chunk ดิบที่เข้ากันได้กับ OpenAI

เพื่อจับ chunk ดิบที่เข้ากันได้กับ OpenAI ก่อนที่จะถูก parse เป็นบล็อก ให้เปิดใช้ transport logger:

OPENCLAW_RAW_STREAM=1

path แบบเลือกได้:

OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-openai-completions.jsonl

ไฟล์ค่าเริ่มต้น:

~/.openclaw/logs/raw-openai-completions.jsonl

หมายเหตุด้านความปลอดภัย

• log สตรีมดิบอาจรวม prompt เต็ม, เอาต์พุตเครื่องมือ และข้อมูลผู้ใช้
• เก็บ log ไว้ในเครื่องและลบหลังดีบักเสร็จ
• หากคุณแชร์ log ให้ลบความลับและ PII ออกก่อน

การดีบักใน VSCode

จำเป็นต้องใช้ source maps เพื่อเปิดใช้การดีบักใน IDE ที่ใช้ VSCode เพราะไฟล์ที่ generated จำนวนมากจะลงท้ายด้วยชื่อที่ hash เป็นส่วนหนึ่งของกระบวนการ build configuration launch.json ที่รวมมาจะ target บริการ Gateway แต่สามารถปรับใช้เพื่อวัตถุประสงค์อื่นได้อย่างรวดเร็ว:

1. สร้างใหม่และดีบัก Gateway - ดีบักบริการ Gateway หลังจากสร้าง build ใหม่
2. ดีบัก Gateway - ดีบักบริการ Gateway ของ build ที่มีอยู่แล้ว

การตั้งค่า

configuration ค่าเริ่มต้น สร้างใหม่และดีบัก Gateway มีทุกอย่างพร้อมใช้ โดยจะลบโฟลเดอร์ /dist โดยอัตโนมัติและ rebuild โปรเจกต์โดยเปิดใช้การดีบัก:

1. เปิดแผง Run and Debug จาก Activity Bar หรือกด Ctrl+Shift+D
2. ใน IDE ตรวจสอบว่าเลือก สร้างใหม่และดีบัก Gateway ใน dropdown configuration แล้วกดปุ่ม เริ่มดีบัก

อีกทางหนึ่ง - หากคุณต้องการจัดการกระบวนการ build และดีบักด้วยตัวเอง:

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. ในเทอร์มินัลเดียวกัน ให้ rebuild โปรเจกต์: pnpm clean:dist && pnpm build
3. ใน IDE เลือกตัวเลือก ดีบัก Gateway ใน dropdown configuration Run and Debug แล้วกดปุ่ม เริ่มดีบัก

ตอนนี้คุณสามารถตั้ง breakpoint ในไฟล์ source TypeScript ของคุณ (ไดเรกทอรี src/) และ debugger จะ map breakpoint ไปยัง JavaScript ที่ compile แล้วได้อย่างถูกต้องผ่าน source maps คุณจะสามารถตรวจสอบตัวแปร, step ผ่านโค้ด และตรวจดู call stack ได้ตามที่คาดไว้

หมายเหตุ

• หากใช้ตัวเลือก "สร้างใหม่และดีบัก Gateway" - ทุกครั้งที่เปิด debugger ระบบจะลบโฟลเดอร์ /dist ทั้งหมดและรัน pnpm build เต็มรูปแบบโดยเปิดใช้ source maps ก่อนเริ่ม Gateway
• หากใช้ตัวเลือก "ดีบัก Gateway" - สามารถเริ่มและหยุดเซสชันดีบักได้ทุกเมื่อโดยไม่กระทบโฟลเดอร์ /dist แต่คุณต้องใช้ process เทอร์มินัลแยกต่างหากเพื่อทั้งเปิดใช้การดีบักและจัดการ build cycle
• แก้ไขการตั้งค่า launch.json สำหรับ args เพื่อดีบักส่วนอื่นของโปรเจกต์
• หากคุณต้องใช้ OpenClaw CLI ที่ build แล้วสำหรับงานอื่น (เช่น dashboard --no-open หากเซสชันดีบักของคุณสร้าง auth token ใหม่) คุณสามารถ execute ในเทอร์มินัลอื่นเป็น node ./openclaw.mjs หรือสร้าง shell alias เช่น alias openclaw-build="node $(pwd)/openclaw.mjs"

ที่เกี่ยวข้อง

• การแก้ไขปัญหา
• คำถามที่พบบ่อย