Node Inspect Debugger

--- name: node-inspect-debugger description: DebugNode.jss using Node Inspect, including--inspects, breakpoints, CDP, heap, and CPU profiles. metadata: { "openclaw": { "emoji": "🪲", "requires": { "bins": ["node"] } } } --- # Node Inspect Debugger Use for Node.js debugging that requires inspector access: hidden locals, async hangs, flaky tests, child processes, startup races, memory growth, or CPU hot paths. Start with node inspect first. Use the Chrome DevTools Protocol only when you need scripted breakpoints, automated state capture, heap snapshots, or CPU profiles. Quick start - Pause on entry: node inspect path/to/script.js - TypeScript: node --inspect-brk --import tsx path/to/script.ts - Existing PID: kill -SIGUSR1 <pid> then node inspect -p <pid> - Inspect target list: curl -s http://127.0.0.1:9229/json/list | jq - OpenClaw CLI path: node --inspect-brk openclaw.mjs ... - OpenClaw test path: OPENCLAW_VITEST_MAX_WORKERS=1 node --inspect-brk scripts/run-vitest.mjs <file> Debugger REPL - Continue/step: cont, next, step, out, pause - Breakpoints: sb('file.js', 42), sb(42), sb('functionName'), breakpoints, cb('file.js', 42) - Inspect: bt, list(8), watch('expr'), exec expr - Current scope: repl, then evaluate locals directly; Ctrl+C exits repl mode. - Exit safely: cont before quitting if the process should continue; otherwise kill. OpenClawtips - Prefer 127.0.0.1 inspector binds. Do not expose --inspect=0.0.0.0 unless the network is isolated. - For Vitest, debug one file with one worker. Avoid worker pools while stepping. - For TS source breakpoints, use --enable-source-maps when useful; node inspect can still show emitted paths. - For child processes, NODE_OPTIONS=--inspect-brk can propagate the inspector, but each child needs its own port. - For long-lived gateway or dev processes, attach by PID after confirming the target with /json/list. Programmatic CDP Install tooling outside the repo unless the project already depends on it: ``bash mkdir -p /tmp/cdp-tools npm --prefix /tmp/cdp-tools i chrome-remote-interface NODE_PATH=/tmp/cdp-tools/node_modules node /tmp/cdp-debug.cjs Minimal driver: js const CDP = require("chrome-remote-interface"); (async () => { const client = await CDP({ port: 9229 }); const { Debugger, Runtime } = client; Debugger.paused(async ({ callFrames, reason }) => { const top = callFrames[0]; console.log("paused", reason, top.url, top.location.lineNumber + 1); const { result } = await Debugger.evaluateOnCallFrame({ callFrameId: top.callFrameId, expression: "JSON.stringify({ pid: process.pid })", }); console.log(result.value ?? result.description); await Debugger.resume(); }); await Runtime.enable(); await Debugger.enable(); await Debugger.setBreakpointByUrl({ urlRegex: ".*target\\.js$", lineNumber: 41 }); await Runtime.runIfWaitingForDebugger(); })(); Profiles - CPU: enable Profiler , start , wait, stop , write /tmp/profile.cpuprofile, open in Chrome DevTools. - Heap: enable HeapProfiler , collect addHeapSnapshotChunk, call takeHeapSnapshot, write /tmp/heap.heapsnapshot. Pitfalls - --inspect does not pause; use --inspect-brk when setup must happen before code runs. - Default port is 9229 ; use --inspect=0` or a unique port for parallel targets. - If a breakpoint is missed, verify the file path, source map behavior, and whether execution has already passed the line. - If the process appears frozen after detaching, it may still be paused in the debugger.