การดีบัก

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

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

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

ตัวอย่าง:

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

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

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

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

ตัวอย่าง:

/trace/trace on/trace off

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

trace วงจรชีวิต Plugin

ใช้ OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 เมื่อคำสั่งวงจรชีวิต Plugin รู้สึกช้า และคุณต้องการการแยกย่อย phase ในตัวสำหรับเมทาดาทา Plugin, discovery, registry, runtime mirror, การแก้ไขคอนฟิก และงาน refresh trace นี้เป็นแบบ opt-in และเขียนไปที่ 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 การเริ่มต้นที่อยู่ใน repo เมื่อคำสั่งรู้สึกช้า:

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 จะเพิ่ม flag โปรไฟล์ CPU ของ Node และเขียน .cpuprofile สำหรับ คำสั่ง ใช้สิ่งนี้ก่อนเพิ่ม instrumentation ชั่วคราวในโค้ดคำสั่ง

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

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

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

โหมด watch ของ Gateway

เพื่อการ iterate ที่รวดเร็ว ให้รัน gateway ภายใต้ file watcher:

pnpm gateway:watch

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

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

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

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

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

wrapper ของ tmux จะพา selector รันไทม์ที่ไม่ใช่ความลับและใช้บ่อย เช่น OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT, และ OPENCLAW_SKIP_CHANNELS เข้าไปใน pane ใส่ credential ของ provider ไว้ใน profile/config ปกติของคุณ หรือใช้โหมด foreground ดิบ สำหรับความลับชั่วคราวแบบครั้งเดียว ถ้า Gateway ที่ถูก watch ออกระหว่างการเริ่มต้น watcher จะรัน openclaw doctor --fix --non-interactive หนึ่งครั้งและรีสตาร์ต child ของ Gateway ใช้ OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 เมื่อคุณต้องการ failure การเริ่มต้นเดิม โดยไม่มี pass ซ่อมแซมเฉพาะ 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 และคอนฟิก ยังคง rebuild dist ก่อน

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

โปรไฟล์ dev + gateway dev (--dev)

ใช้โปรไฟล์ dev เพื่อแยก state และเริ่ม setup ที่ปลอดภัยและทิ้งได้สำหรับ การดีบัก มี flag --dev สอง แบบ:

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

flow ที่แนะนำ (โปรไฟล์ dev + dev bootstrap):

pnpm gateway:devOPENCLAW_PROFILE=dev openclaw tui

ถ้าคุณยังไม่มีการติดตั้งแบบ global ให้รัน CLI ผ่าน pnpm openclaw ...

สิ่งที่ทำ:

1. การแยกโปรไฟล์ (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)

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

flow รีเซ็ต (เริ่มใหม่):

pnpm gateway:dev:reset

--reset จะล้างคอนฟิก, credential, เซสชัน และ workspace dev (โดยใช้ trash ไม่ใช่ rm) จากนั้นสร้าง setup dev เริ่มต้นขึ้นใหม่

การ log stream ดิบ (OpenClaw)

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

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

pnpm gateway:watch --raw-stream

การ override path แบบ optional:

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

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

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

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

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

การ log chunk ดิบ (pi-mono)

เพื่อจับ chunk ดิบที่เข้ากันได้กับ OpenAI ก่อนถูก parse เป็นบล็อก pi-mono มี logger แยกต่างหาก:

PI_RAW_STREAM=1

path แบบ optional:

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

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

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

หมายเหตุ: สิ่งนี้จะถูก emit เฉพาะโดย process ที่ใช้ provider openai-completions ของ pi-mono

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

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

การดีบักใน VSCode

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

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

การตั้งค่า

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

1. เปิด panel Run and Debug จาก Activity Bar หรือกด Ctrl+Shift+D
2. ใน IDE ตรวจสอบให้แน่ใจว่าเลือก Rebuild and Debug Gateway ใน dropdown คอนฟิกแล้ว จากนั้นกดปุ่ม Start Debugging

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

1. เปิดเทอร์มินัลและเปิดใช้งาน source map:
   • Linux/macOS: export OUTPUT_SOURCE_MAPS=1
   • Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
   • Windows (CMD): set OUTPUT_SOURCE_MAPS=1
2. ในเทอร์มินัลเดียวกัน rebuild project: pnpm clean:dist && pnpm build
3. ใน IDE เลือกตัวเลือก Debug Gateway ใน dropdown คอนฟิก Run and Debug แล้วกดปุ่ม Start Debugging

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

หมายเหตุ

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

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

• การแก้ไขปัญหา
• FAQ