Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

ตัวช่วยสำหรับการดีบักเอาต์พุตแบบสตรีม โดยเฉพาะเมื่อ 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:smoke
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm 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
# or
OPENCLAW_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:dev
OPENCLAW_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
--dev เป็น flag โปรไฟล์แบบ global และถูก runner บางตัวกลืนไป หากคุณต้องระบุให้ชัด ให้ใช้รูปแบบ env var:
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
--reset จะล้างคอนฟิก, credential, เซสชัน และ workspace dev (โดยใช้ trash ไม่ใช่ rm) จากนั้นสร้าง setup dev เริ่มต้นขึ้นใหม่
ถ้า gateway ที่ไม่ใช่ dev กำลังรันอยู่แล้ว (launchd หรือ systemd) ให้หยุดก่อน:
openclaw gateway stop

​
การ 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=1
OPENCLAW_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"

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