การแก้ไขข้อบกพร่อง

ตัวช่วยดีบักสำหรับเอาต์พุตแบบสตรีม การวนพัฒนา Gateway และการทำโปรไฟล์การเริ่มต้นระบบ

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

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

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

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

เอาต์พุตการติดตามเซสชัน

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

/trace/trace on/trace off

การติดตามวงจรชีวิตของ Plugin

ตั้งค่า OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 เพื่อดูรายละเอียดแบบแยกแต่ละเฟสของเมทาดาทา Plugin การค้นหา รีจิสทรี มิเรอร์รันไทม์ การเปลี่ยนแปลงคอนฟิก และงานรีเฟรช โดยจะเขียนไปยัง stderr เพื่อให้เอาต์พุตคำสั่ง JSON ยังคงแยกวิเคราะห์ได้ เมื่อเปิดการติดตามนี้ ความล้มเหลวในการโหลด Plugin จะรวมสแต็กเทรซไว้ด้วย

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"

ใช้วิธีนี้ก่อนเลือกใช้ตัวทำโปรไฟล์ CPU จากเช็กเอาต์ซอร์ส ให้วัดรันไทม์ที่สร้างแล้วด้วย node dist/entry.js ... หลังจาก pnpm build; ส่วน pnpm openclaw ... จะรวมการวัดโอเวอร์เฮดของตัวรันซอร์สด้วย

สำหรับการวัดเวลาการโหลดโมดูลแบบซิงโครนัส ให้ใช้พื้นผิวการวินิจฉัยร่วมแทนสวิตช์สภาพแวดล้อมที่แยกไว้เฉพาะ Plugin:

OPENCLAW_DIAGNOSTICS=plugin.load-profile openclaw plugins list

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

เบนช์มาร์กการเริ่มต้นที่เช็กอินไว้:

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

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

OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

ตัวรันซอร์สจะเพิ่มแฟล็กโปรไฟล์ CPU ของ Node และเขียน .cpuprofile สำหรับคำสั่ง ใช้วิธีนี้ก่อนเพิ่มเครื่องมือวัดชั่วคราวลงในโค้ดคำสั่ง

สำหรับอาการค้างระหว่างเริ่มต้นที่ดูเหมือนเกิดจากระบบไฟล์แบบซิงโครนัสหรืองานของตัวโหลดโมดูล ให้เพิ่มแฟล็กติดตาม I/O แบบซิงโครนัสของ Node ผ่านตัวรันซอร์ส:

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

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

โหมดเฝ้าดู Gateway

pnpm gateway:watch

ตามค่าเริ่มต้น คำสั่งนี้จะเริ่มหรือเริ่มเซสชัน tmux ชื่อ openclaw-gateway-watch-<profile> ใหม่ (ตัวอย่างเช่น openclaw-gateway-watch-main) โดยจะเพิ่มส่วนต่อท้ายพอร์ต เช่น openclaw-gateway-watch-dev-19001 เฉพาะเมื่อ OPENCLAW_GATEWAY_PORT แตกต่างจากพอร์ตเริ่มต้น 18789 เท่านั้น ระบบจะแนบเซสชันโดยอัตโนมัติจากเทอร์มินัลแบบโต้ตอบ ส่วนเชลล์แบบไม่โต้ตอบ, CI และการเรียกใช้ exec ของเอเจนต์จะยังคงแยกออกจากเซสชันและพิมพ์คำแนะนำการแนบแทน:

tmux attach -t openclaw-gateway-watch-main# อ่านเอาต์พุตล่าสุดโดยไม่ต้องแนบเซสชันtmux capture-pane -ep -t openclaw-gateway-watch-main -S -200

พาเนลใช้ remain-on-exit ของ tmux ดังนั้นความล้มเหลวระหว่างเริ่มต้นจะยังคงอยู่ให้แนบหรือบันทึกเอาต์พุตได้ แทนที่จะลบเซสชัน การเรียก pnpm gateway:watch อีกครั้งจะสร้างพาเนลนั้นใหม่

พาเนล tmux จะรันตัวเฝ้าดูโดยตรง:

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

ก่อนเฝ้าดูพอร์ตที่กำหนดค่าไว้/พอร์ตเริ่มต้น แรปเปอร์ tmux จะหยุดบริการ Gateway ที่ติดตั้งไว้ของโปรไฟล์ที่ใช้งานอยู่ วิธีนี้ส่งมอบพอร์ตให้ตัวเฝ้าดูซอร์สโดยไม่ให้ launchd, systemd หรือ Scheduled Task สร้างโปรเซสใหม่และแทนที่ตัวเฝ้าดู บริการจะยังคงติดตั้งอยู่ ให้คืนค่าหลังจากเซสชันเฝ้าดูด้วย:

pnpm openclaw gateway start

เมื่อ --port หรือ OPENCLAW_GATEWAY_PORT ที่ระบุอย่างชัดเจนแตกต่างจากพอร์ตที่มีผลของบริการที่ติดตั้งไว้ แรปเปอร์จะปล่อยให้บริการทำงานต่อไป เพื่อให้ Gateway ทั้งสองทำงานเคียงข้างกันได้

โหมดเบื้องหน้าโดยไม่ใช้ tmux:

pnpm gateway:watch:raw# หรือOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

โหมดโดยตรงจะไม่จัดการบริการที่ติดตั้งไว้ ให้รัน pnpm openclaw gateway stop ก่อนเมื่อบริการใช้พอร์ตเดียวกัน

คงการจัดการ tmux ไว้แต่ปิดการแนบอัตโนมัติ:

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

ทำโปรไฟล์เวลา CPU ของ Gateway ที่เฝ้าดูเมื่อดีบักฮอตสปอตระหว่างเริ่มต้น/รันไทม์:

pnpm gateway:watch --benchmark

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

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

• --benchmark-dir <path>: เขียนโปรไฟล์ไปยังตำแหน่งอื่น
• --benchmark-no-force: ข้ามการล้างพอร์ตเริ่มต้น --force และล้มเหลวทันทีหากพอร์ต Gateway ถูกใช้งานอยู่แล้ว

โหมดเบนช์มาร์กจะระงับข้อความรบกวนจากการติดตาม I/O แบบซิงโครนัสตามค่าเริ่มต้น ตั้งค่า OPENCLAW_TRACE_SYNC_IO=1 ร่วมกับ --benchmark เพื่อรับทั้งโปรไฟล์ CPU และสแต็กเทรซ I/O แบบซิงโครนัส ในโหมดเบนช์มาร์ก บล็อกการติดตามเหล่านั้นจะถูกเขียนไปยัง gateway-watch-output.log ภายใต้ไดเรกทอรีเบนช์มาร์ก (และถูกกรองออกจากพาเนลเทอร์มินัล) ขณะที่บันทึก Gateway ตามปกติยังคงมองเห็นได้

แรปเปอร์ tmux จะส่งต่อตัวเลือกรันไทม์ทั่วไปที่ไม่เป็นความลับไปยังพาเนล รวมถึง OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT และ OPENCLAW_SKIP_CHANNELS ให้ใส่ข้อมูลประจำตัวของผู้ให้บริการไว้ในโปรไฟล์/คอนฟิกตามปกติ หรือใช้โหมดเบื้องหน้าโดยตรงสำหรับข้อมูลลับชั่วคราวที่ใช้ครั้งเดียว

หาก Gateway ที่เฝ้าดูออกระหว่างเริ่มต้น ตัวเฝ้าดูจะรัน openclaw doctor --fix --non-interactive หนึ่งครั้งแล้วเริ่มโปรเซสลูก Gateway ใหม่ ตั้งค่า OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 เพื่อดูความล้มเหลวระหว่างเริ่มต้นเดิมโดยไม่ผ่านขั้นตอนซ่อมแซมสำหรับการพัฒนาเท่านั้น

พาเนล tmux ที่มีการจัดการจะใช้บันทึก Gateway แบบมีสีตามค่าเริ่มต้น ตั้งค่า FORCE_COLOR=0 เมื่อเริ่ม pnpm gateway:watch เพื่อปิดเอาต์พุต ANSI

ตัวเฝ้าดูจะเริ่มใหม่เมื่อไฟล์ที่เกี่ยวข้องกับการสร้างภายใต้ src/, ไฟล์ซอร์สของส่วนขยาย, เมทาดาทา package.json และ openclaw.plugin.json ของส่วนขยาย, tsconfig.json, package.json และ tsdown.config.ts เปลี่ยนแปลง การเปลี่ยนแปลงเมทาดาทาของส่วนขยายจะเริ่ม Gateway ใหม่โดยไม่บังคับให้สร้างใหม่ ส่วนการเปลี่ยนแปลงซอร์สและคอนฟิกจะยังคงสร้าง dist ใหม่ก่อน

เพิ่มแฟล็ก CLI ของ Gateway หลัง gateway:watch แล้วแฟล็กเหล่านั้นจะถูกส่งต่อในการเริ่มใหม่แต่ละครั้ง การเรียกคำสั่งเฝ้าดูเดิมอีกครั้งจะสร้างพาเนล tmux ที่มีชื่อนั้นใหม่ ตัวเฝ้าดูโดยตรงจะใช้ล็อกตัวเฝ้าดูเดี่ยว เพื่อแทนที่โปรเซสหลักของตัวเฝ้าดูที่ซ้ำกันแทนที่จะปล่อยให้สะสม

โปรไฟล์พัฒนา + Gateway สำหรับพัฒนา (--dev)

มีแฟล็ก --dev แยกกัน สองรายการ:

• --dev ส่วนกลาง (โปรไฟล์): แยกสถานะไว้ภายใต้ ~/.openclaw-dev และตั้งค่าพอร์ต Gateway เริ่มต้นเป็น 19001 (พอร์ตที่คำนวณต่อเนื่องจะเลื่อนตาม)
• gateway --dev: สั่งให้ Gateway สร้างคอนฟิกเริ่มต้น + เวิร์กสเปซโดยอัตโนมัติเมื่อยังไม่มี (และข้าม bootstrap)

ขั้นตอนที่แนะนำ (โปรไฟล์พัฒนา + bootstrap สำหรับพัฒนา):

pnpm gateway:devOPENCLAW_PROFILE=dev openclaw tui

หากไม่ได้ติดตั้งแบบส่วนกลาง ให้รัน CLI ผ่าน pnpm openclaw ...

สิ่งที่กระบวนการนี้ทำ:

1. การแยกโปรไฟล์ (--dev ส่วนกลาง)

   • OPENCLAW_PROFILE=dev
   • OPENCLAW_STATE_DIR=~/.openclaw-dev
   • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
   • OPENCLAW_GATEWAY_PORT=19001 (พอร์ตเบราว์เซอร์/แคนวาสจะเลื่อนตาม)

2. Bootstrap สำหรับพัฒนา (gateway --dev)

   • เขียนคอนฟิกขั้นต่ำหากยังไม่มี (gateway.mode=local, ผูกกับ loopback)
   • ตั้งค่า agents.defaults.workspace เป็นเวิร์กสเปซสำหรับพัฒนาและ agents.defaults.skipBootstrap=true
   • สร้างไฟล์เริ่มต้นในเวิร์กสเปซหากยังไม่มี: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md
   • ข้อมูลประจำตัวเริ่มต้น: C3-PO (ดรอยด์พิธีการ)
   • pnpm gateway:dev ยังตั้งค่า OPENCLAW_SKIP_CHANNELS=1 เพื่อข้ามผู้ให้บริการช่องทางด้วย

Gateway สำหรับพัฒนาจะเพิกเฉยต่อทริกเกอร์สภาพแวดล้อมของช่องทางโดยค่าเริ่มต้น ดังนั้นข้อมูลประจำตัวที่รับช่วงมาจากเชลล์จะไม่เชื่อมต่ออินสแตนซ์สำหรับพัฒนาเข้ากับบริการช่องทางจริง คอนฟิก channels.<id> ที่ระบุอย่างชัดเจนยังคงทำงาน ส่ง --dev-ambient-channels ร่วมกับ --dev เพื่อคืนค่าการกำหนดค่าช่องทางอัตโนมัติจากสภาพแวดล้อมสำหรับการรันครั้งนั้น

ขั้นตอนรีเซ็ต (เริ่มใหม่ทั้งหมด):

pnpm gateway:dev:reset

--reset จะล้างคอนฟิก ข้อมูลประจำตัว เซสชัน และเวิร์กสเปซสำหรับพัฒนา (ย้ายไปถังขยะ ไม่ได้ลบถาวร) จากนั้นสร้างการตั้งค่าพัฒนาเริ่มต้นใหม่

การบันทึกสตรีมดิบ

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

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

pnpm gateway:watch --raw-stream

การแทนที่พาธซึ่งเป็นตัวเลือกเสริม:

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

ตัวแปรสภาพแวดล้อมที่เทียบเท่า:

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

ไฟล์เริ่มต้น: ~/.openclaw/logs/raw-stream.jsonl

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

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

การดีบักใน VSCode

จำเป็นต้องใช้ซอร์สแมป เนื่องจากกระบวนการสร้างจะแฮชชื่่อไฟล์ที่สร้างขึ้น launch.json ที่รวมไว้กำหนดเป้าหมายไปยังบริการ Gateway:

1. Rebuild and Debug Gateway - ลบ /dist และสร้างใหม่โดยเปิดใช้งานการดีบักก่อนเริ่ม Gateway
2. Debug Gateway - ดีบักบิลด์ที่มีอยู่โดยไม่แตะต้อง /dist

การตั้งค่า

1. เปิด Run and Debug (Activity Bar หรือ Ctrl+Shift+D)
2. เลือก Rebuild and Debug Gateway แล้วกด Start Debugging

หากต้องการจัดการรอบการสร้าง/ดีบักด้วยตนเองแทน:

1. เปิดใช้งานซอร์สแมปในเทอร์มินัล:
   • Linux/macOS: export OUTPUT_SOURCE_MAPS=1
   • Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
   • Windows (CMD): set OUTPUT_SOURCE_MAPS=1
2. สร้างใหม่: pnpm clean:dist && pnpm build
3. เลือก Debug Gateway แล้วกด Start Debugging

ตั้งค่าเบรกพอยต์ในไฟล์ TypeScript src/; ดีบักเกอร์จะแมปไฟล์เหล่านั้นไปยัง JavaScript ที่คอมไพล์แล้วผ่านซอร์สแมป

หมายเหตุ

• Rebuild and Debug Gateway จะลบ /dist และรัน pnpm build แบบเต็มพร้อมซอร์สแมปทุกครั้งที่เปิด
• Debug Gateway สามารถเริ่ม/หยุดได้โดยไม่กระทบ /dist แต่ต้องจัดการรอบการสร้างในเทอร์มินัลแยกต่างหาก
• แก้ไข args ของ launch.json เพื่อดีบักคำสั่งย่อย CLI อื่น
• หากต้องการใช้ CLI ที่สร้างแล้วสำหรับงานอื่น (ตัวอย่างเช่น dashboard --no-open หากเซสชันดีบักสร้างโทเค็นการยืนยันตัวตนใหม่) ให้รันจากเทอร์มินัลอื่น: node ./openclaw.mjs หรือนามแฝง เช่น alias openclaw-build="node $(pwd)/openclaw.mjs"

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

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