मुख्य सामग्री पर जाएं
स्ट्रीमिंग आउटपुट के लिए डिबगिंग सहायक, खासकर जब कोई प्रदाता reasoning को सामान्य टेक्स्ट में मिला देता है।

​
रनटाइम डिबग ओवरराइड

केवल-रनटाइम कॉन्फिग ओवरराइड (मेमरी, डिस्क नहीं) सेट करने के लिए चैट में /debug का उपयोग करें। /debug डिफ़ॉल्ट रूप से अक्षम है; इसे commands.debug: true से सक्षम करें। यह तब उपयोगी है जब आपको openclaw.json संपादित किए बिना अस्पष्ट सेटिंग्स टॉगल करनी हों। उदाहरण: 
/debug show
/debug set messages.responsePrefix="[openclaw]"
/debug unset messages.responsePrefix
/debug reset
/debug reset सभी ओवरराइड साफ़ करता है और ऑन-डिस्क कॉन्फिग पर वापस लौटता है।

​
सेशन ट्रेस आउटपुट

जब आप पूर्ण verbose मोड चालू किए बिना एक सेशन में Plugin-स्वामित्व वाली ट्रेस/डिबग लाइनें देखना चाहते हों, तो /trace का उपयोग करें। उदाहरण: 
/trace
/trace on
/trace off
Active Memory डिबग सारांश जैसे Plugin डायग्नॉस्टिक्स के लिए /trace का उपयोग करें। सामान्य verbose स्थिति/टूल आउटपुट के लिए /verbose का उपयोग जारी रखें, और केवल-रनटाइम कॉन्फिग ओवरराइड के लिए /debug का उपयोग जारी रखें।

​
Plugin लाइफ़साइकल ट्रेस

जब Plugin लाइफ़साइकल कमांड धीमे लगें और आपको Plugin मेटाडेटा, डिस्कवरी, रजिस्ट्री, रनटाइम मिरर, कॉन्फिग म्यूटेशन, और रिफ्रेश काम के लिए बिल्ट-इन चरण विभाजन चाहिए, तो OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 का उपयोग करें। ट्रेस ऑप्ट-इन है और stderr पर लिखता है, इसलिए JSON कमांड आउटपुट पार्स किया जा सकता है। उदाहरण: 
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 प्रोफाइलर तक जाने से पहले Plugin लाइफ़साइकल जांच के लिए इसका उपयोग करें। अगर कमांड किसी सोर्स चेकआउट से चल रहा है, तो pnpm build के बाद node dist/entry.js ... के साथ बने हुए रनटाइम को मापना बेहतर है; pnpm openclaw ... सोर्स-रनर ओवरहेड भी मापता है।

​
CLI स्टार्टअप और कमांड प्रोफाइलिंग

जब कोई कमांड धीमा लगे, तो चेक-इन किए गए स्टार्टअप बेंचमार्क का उपयोग करें: 
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
सामान्य सोर्स रनर के माध्यम से एकबारगी प्रोफाइलिंग के लिए, OPENCLAW_RUN_NODE_CPU_PROF_DIR सेट करें: 
OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status
सोर्स रनर Node CPU प्रोफाइल फ़्लैग जोड़ता है और कमांड के लिए .cpuprofile लिखता है। कमांड कोड में अस्थायी इंस्ट्रूमेंटेशन जोड़ने से पहले इसका उपयोग करें। ऐसे स्टार्टअप स्टॉल के लिए जो सिंक्रोनस फाइलसिस्टम या मॉड्यूल-लोडर काम जैसे दिखते हैं, सोर्स रनर के माध्यम से Node का sync I/O ट्रेस फ़्लैग जोड़ें: 
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force
pnpm gateway:watch देखे जा रहे Gateway चाइल्ड के लिए इस फ़्लैग को डिफ़ॉल्ट रूप से अक्षम रखता है। जब आप watch मोड में स्पष्ट रूप से Node sync I/O ट्रेस आउटपुट चाहते हों, तो OPENCLAW_TRACE_SYNC_IO=1 सेट करें।

​
Gateway watch मोड

तेज़ iteration के लिए, gateway को फ़ाइल watcher के तहत चलाएँ: 
pnpm gateway:watch
डिफ़ॉल्ट रूप से, यह openclaw-gateway-watch-main नाम का tmux सेशन शुरू या रीस्टार्ट करता है (या openclaw-gateway-watch-dev-19001 जैसा कोई profile/port-विशिष्ट variant) और interactive terminals से अपने-आप attach होता है। Non-interactive shells, CI, और agent exec calls detached रहते हैं और इसके बजाय attach निर्देश प्रिंट करते हैं। ज़रूरत होने पर मैन्युअल रूप से attach करें: 
tmux attach -t openclaw-gateway-watch-main
tmux pane कच्चा watcher चलाता है: 
node scripts/watch-node.mjs gateway --force
जब tmux नहीं चाहिए, तो foreground मोड का उपयोग करें: 
pnpm gateway:watch:raw
# or
OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch
tmux प्रबंधन बनाए रखते हुए auto-attach अक्षम करें: 
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
स्टार्टअप/रनटाइम hotspots डिबग करते समय देखे जा रहे Gateway CPU समय को प्रोफाइल करें: 
pnpm gateway:watch --benchmark
watch wrapper Gateway को invoke करने से पहले --benchmark consume करता है और .artifacts/gateway-watch-profiles/ के तहत हर Gateway child exit पर एक V8 .cpuprofile लिखता है। वर्तमान प्रोफाइल flush करने के लिए देखे जा रहे gateway को रोकें या रीस्टार्ट करें, फिर उसे Chrome DevTools या Speedscope से खोलें: 
npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile
जब आप profiles कहीं और चाहते हों, तो --benchmark-dir <path> का उपयोग करें। जब आप benchmarked child से default --force port cleanup छोड़वाना चाहते हों और Gateway port पहले से उपयोग में हो तो जल्दी fail करवाना चाहते हों, तो --benchmark-no-force का उपयोग करें। Benchmark मोड डिफ़ॉल्ट रूप से sync-I/O trace spam को दबा देता है। जब आप स्पष्ट रूप से CPU profiles और Node sync-I/O stack traces दोनों चाहते हों, तो --benchmark के साथ OPENCLAW_TRACE_SYNC_IO=1 सेट करें। benchmark मोड में वे trace blocks benchmark directory के तहत gateway-watch-output.log में लिखे जाते हैं और terminal pane से filter किए जाते हैं; सामान्य Gateway logs दिखाई देते रहते हैं। tmux wrapper सामान्य non-secret runtime selectors जैसे OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT, और OPENCLAW_SKIP_CHANNELS को pane में ले जाता है। Provider credentials को अपनी सामान्य profile/config में रखें, या एकबारगी ephemeral secrets के लिए raw foreground mode का उपयोग करें। अगर देखा जा रहा Gateway स्टार्टअप के दौरान exit करता है, तो watcher एक बार openclaw doctor --fix --non-interactive चलाता है और Gateway child को रीस्टार्ट करता है। जब आप dev-only repair pass के बिना मूल startup failure चाहते हों, तो OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 का उपयोग करें। Managed tmux pane readability के लिए रंगीन Gateway logs पर भी डिफ़ॉल्ट करता है; ANSI output अक्षम करने के लिए pnpm gateway:watch शुरू करते समय FORCE_COLOR=0 सेट करें। Watcher src/ के तहत build-relevant files, extension source files, extension package.json और openclaw.plugin.json metadata, tsconfig.json, package.json, और tsdown.config.ts पर restart करता है। Extension metadata changes gateway को tsdown rebuild force किए बिना restart करते हैं; source और config changes पहले अब भी dist rebuild करते हैं। gateway:watch के बाद कोई भी gateway CLI flags जोड़ें और वे हर restart पर pass through किए जाएँगे। वही watch command दोबारा चलाने पर named tmux pane respawn होता है, और raw watcher अब भी अपना single-watcher lock रखता है ताकि duplicate watcher parents piling up होने के बजाय replace हो जाएँ।

​
Dev profile + dev gateway (—dev)

debugging के लिए state को isolate करने और safe, disposable setup spin up करने के लिए dev profile का उपयोग करें। दो --dev flags हैं:
  • Global --dev (profile): state को ~/.openclaw-dev के तहत isolate करता है और gateway port को 19001 पर default करता है (derived ports इसके साथ shift होते हैं)।
  • gateway --dev: Gateway को missing होने पर default config + workspace auto-create करने के लिए कहता है (और BOOTSTRAP.md छोड़ता है)।
Recommended flow (dev profile + dev bootstrap): 
pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui
अगर आपके पास अभी global install नहीं है, तो CLI को pnpm openclaw ... के माध्यम से चलाएँ। यह क्या करता है:
  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 accordingly shift होते हैं)
  2. Dev bootstrap (gateway --dev)
    • missing होने पर minimal config लिखता है (gateway.mode=local, bind loopback)।
    • agent.workspace को dev workspace पर सेट करता है।
    • agent.skipBootstrap=true सेट करता है (कोई BOOTSTRAP.md नहीं)।
    • missing होने पर workspace files seed करता है: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md.
    • Default identity: C3-PO (protocol droid)।
    • dev mode में channel providers छोड़ता है (OPENCLAW_SKIP_CHANNELS=1)।
Reset flow (fresh start): 
pnpm gateway:dev:reset
--dev एक global profile flag है और कुछ runners द्वारा consume हो जाता है। अगर आपको इसे स्पष्ट रूप से लिखना हो, तो env var form का उपयोग करें:
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
--reset config, credentials, sessions, और dev workspace को wipe करता है (trash का उपयोग करके, rm नहीं), फिर default dev setup को दोबारा बनाता है।
अगर non-dev gateway पहले से चल रहा है (launchd या systemd), तो पहले उसे रोकें:
openclaw gateway stop

​
Raw stream logging (OpenClaw)

OpenClaw किसी भी filtering/formatting से पहले raw assistant stream log कर सकता है। यह देखने का सबसे अच्छा तरीका है कि reasoning plain text deltas के रूप में आ रही है या नहीं (या अलग thinking blocks के रूप में)। इसे CLI के माध्यम से सक्षम करें: 
pnpm gateway:watch --raw-stream
Optional path override: 
pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
Equivalent env vars: 
OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
Default file: ~/.openclaw/logs/raw-stream.jsonl

​
Raw OpenAI-compatible chunk logging

Blocks में parse होने से पहले raw OpenAI-compat chunks capture करने के लिए, transport logger सक्षम करें: 
OPENCLAW_RAW_STREAM=1
Optional path: 
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-openai-completions.jsonl
Default file: ~/.openclaw/logs/raw-openai-completions.jsonl

​
सुरक्षा नोट्स

  • Raw stream logs में full prompts, tool output, और user data शामिल हो सकते हैं।
  • logs को local रखें और debugging के बाद delete करें।
  • अगर आप logs share करते हैं, तो पहले secrets और PII scrub करें।

​
VSCode में debugging

VSCode-आधारित IDEs में debugging सक्षम करने के लिए source maps आवश्यक हैं क्योंकि generated files में से कई build process के हिस्से के रूप में hashed names के साथ समाप्त होती हैं। शामिल launch.json configurations Gateway service को target करती हैं, लेकिन इन्हें अन्य उद्देश्यों के लिए जल्दी adapt किया जा सकता है:
  1. Gateway को rebuild और debug करें - नया build बनाने के बाद Gateway service debug करता है
  2. Gateway debug करें - पहले से मौजूद build की Gateway service debug करता है

​
Setup

Default Gateway को rebuild और debug करें configuration batteries-included है, यह /dist folder को automatically delete करेगा और debugging enabled के साथ project को rebuild करेगा:
  1. Activity Bar से Run and Debug panel खोलें या Ctrl+Shift+D दबाएँ
  2. IDE में, सुनिश्चित करें कि configuration dropdown में Gateway को rebuild और debug करें selected है और फिर Start Debugging button दबाएँ
वैकल्पिक रूप से - अगर आप build और debug processes manually manage करना पसंद करते हैं:
  1. terminal खोलें और source maps enable करें:
    • Linux/macOS: export OUTPUT_SOURCE_MAPS=1
    • Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
    • Windows (CMD): set OUTPUT_SOURCE_MAPS=1
  2. उसी terminal में, project rebuild करें: pnpm clean:dist && pnpm build
  3. IDE में, Run and Debug configuration dropdown में Gateway debug करें option चुनें और फिर Start Debugging button दबाएँ
अब आप अपनी TypeScript source files (src/ directory) में breakpoints set कर सकते हैं और debugger source maps के माध्यम से breakpoints को compiled JavaScript पर correctly map करेगा। आप variables inspect कर पाएँगे, code में step through कर पाएँगे, और call stacks को अपेक्षित रूप से examine कर पाएँगे।

​
नोट्स

  • अगर “Gateway को rebuild और debug करें” option का उपयोग कर रहे हैं - debugger launch होने पर हर बार यह /dist folder को पूरी तरह delete करेगा और Gateway शुरू करने से पहले source maps enabled के साथ full pnpm build चलाएगा
  • अगर “Gateway debug करें” option का उपयोग कर रहे हैं - debug sessions को /dist folder को प्रभावित किए बिना कभी भी start और stop किया जा सकता है, लेकिन debugging enable करने और build cycle manage करने दोनों के लिए आपको अलग terminal process का उपयोग करना होगा
  • project के अन्य sections debug करने के लिए args के लिए launch.json settings modify करें
  • अगर आपको अन्य tasks के लिए built OpenClaw CLI का उपयोग करना है (यानी अगर आपका debug session नया auth token spawn करता है तो dashboard --no-open), तो आप इसे दूसरे terminal में node ./openclaw.mjs के रूप में execute कर सकते हैं या alias openclaw-build="node $(pwd)/openclaw.mjs" जैसा shell alias बना सकते हैं

​
संबंधित