1. Skill Overview
This skill applies to scenarios requiring Node.js debugging with Inspector privileges. It defaults to the
node inspect CLI debugger, and only leverages the Chrome DevTools Protocol (CDP) when scripted breakpoints, automated state capture, heap snapshots, or CPU profiling are required.2. Core Capabilities
2.1 Quick Debug Session Startup
Multiple ways to launch debug sessions for different scenarios:
| Scenario | Command | |
|---|---|---|
| Pause at entry for debugging | node inspect path/to/script.js |
|
| TypeScript debugging | node --inspect-brk --import tsx path/to/script.ts |
|
| Attach to a running process | kill -SIGUSR1 <PID> then node inspect -p <PID> |
|
| List inspectable debug targets | `curl -s http://127.0.0.1:9229/json/list | jq` |
| OpenClaw CLI debugging | node --inspect-brk openclaw.mjs ... |
|
| Single-file Vitest debugging | OPENCLAW_VITEST_MAX_WORKERS=1 node --inspect-brk scripts/run-vitest.mjs <file> |
2.2 Debugger REPL Commands
Interactive debugging commands available within a debug session:
| Command | Purpose |
|---|---|
cont, next, step, out, pause |
Continue, step over, step into, step out, pause execution |
sb('file.js', 42), sb(42), sb('functionName') |
Set breakpoint: file + line number, line number in current file, function name |
breakpoints, cb('file.js', 42) |
List all breakpoints, clear specified breakpoint |
bt |
Print full call backtrace |
list(8) |
Show source code around current execution position |
watch('expr') |
Watch the value of an expression |
exec expr |
Evaluate arbitrary expressions in current scope |
repl |
Enter REPL mode to inspect local variables; press Ctrl+C to exit |
Exit rule: Run
cont first before exiting if the process should keep running; terminate directly otherwise.2.3 OpenClaw Project Debugging Best Practices
Optimized debugging guidance tailored to the OpenClaw codebase:
- Inspector binding rule: Bind exclusively to
127.0.0.1by default. Avoid--inspect=0.0.0.0unless running within an isolated private network. - Vitest debugging: Use single-worker mode for single-file test debugging to avoid worker pool interference during stepping.
- TypeScript source breakpoints: Enable
--enable-source-mapsto render original TS file paths insidenode inspect. - Child process debugging:
NODE_OPTIONS=--inspect-brkpropagates inspector flags to child processes, but each subprocess requires a unique dedicated port. - Long-lived daemons: Attach via PID; always list targets via
/json/listto confirm the correct debug endpoint first.
2.4 Programmatic CDP (Chrome DevTools Protocol)
Use CDP for automated scripted breakpoint logic and unattended state capture:
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();
})();Temporary CDP tool installation outside repo source tree:
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.cjs2.5 CPU & Heap Memory Profiling via CDP
CDP-powered performance profiling workflows:
| Profiling Type | Operation Flow |
|---|---|
| CPU Profiling | Enable Profiler → Start capture → Wait for workload → Stop capture → Write output to /tmp/profile.cpuprofile for inspection in Chrome DevTools |
| Heap Snapshot | Enable Heap Profiler → Subscribe to chunk events → Trigger snapshot capture → Save full snapshot file to /tmp/heap.heapsnapshot |
3. Primary Use Cases
- Debug hidden variables & asynchronous hangs — Trace elusive async call chains and closure-scoped state
- Flaky test troubleshooting — Isolate root causes of intermittent test failures via breakpoints and single-step execution
- Child process & startup race condition debugging — Diagnose initialization ordering issues in multi-process architectures
- Memory growth analysis — Compare sequential heap snapshots to identify memory leaks
- CPU hot path profiling — Locate performance bottlenecks via CPU profiling traces
- Dedicated OpenClaw debugging — Debug OpenClaw CLI entrypoints and isolated Vitest test files
4. Critical Guiding Principles
- Default to
node inspect: Only use CDP when automated scripting logic is mandatory - Avoid public inspector binding
--inspect=0.0.0.0: Introduces severe security risks without isolated network segmentation - Single-worker Vitest mode required for stepping: Worker pools disrupt predictable single-step debugging
- Independent ports for child processes:
NODE_OPTIONS=--inspect-brkpropagates flags, but each subprocess needs a unique port --inspectvs--inspect-brk:--inspectdoes not pause on launch; use--inspect-brkto halt execution before application logic runs- Default inspector port 9229: Use
--inspect=0or custom unique ports for parallel simultaneous debug sessions - Breakpoint misfire troubleshooting: Validate file path resolution, source map generation, and whether execution has already passed the target line
- Frozen process handling: If a process appears unresponsive after detaching, it may still be suspended at a debugger breakpoint
Summary
Node Inspect Debugger is a dedicated skill for deep Node.js debugging within the OpenClaw project. It provides two core tooling paths — the lightweight
node inspect CLI debugger and fully programmable Chrome DevTools Protocol (CDP) — covering debugging scenarios including hidden closure variables, async stalls, flaky tests, child process race conditions, memory bloat analysis, and CPU bottleneck profiling. It delivers a complete workflow from one-click debug startup to automated programmatic tracing, with specialized debugging guidance built for OpenClaw CLI and Vitest test suites.
