diff --git a/.vscode/launch.json b/.vscode/launch.json
index 8bc6c565f3e..3525813ee05 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -5,7 +5,7 @@
       "name": "Debug Gateway",
       "type": "node",
       "request": "launch",
-      "runtimeArgs": ["openclaw.mjs", "gateway", "run"],
+      "args": ["openclaw.mjs", "gateway", "run"],
       "console": "integratedTerminal",
       "skipFiles": ["<node_internals>/**", "node_modules/**"],
       "outFiles": ["${workspaceFolder}/dist/**/*.js"],
@@ -17,8 +17,9 @@
       "name": "Rebuild and Debug Gateway",
       "type": "node",
       "request": "launch",
+      "preLaunchTask": "clean:dist",
       "runtimeExecutable": "pnpm",
-      "runtimeArgs": ["run", "openclaw", "--", "gateway", "run"],
+      "args": ["run", "openclaw", "--", "gateway", "run"],
       "console": "integratedTerminal",
       "skipFiles": ["<node_internals>/**", "node_modules/**"],
       "outFiles": ["${workspaceFolder}/dist/**/*.js"],
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
new file mode 100644
index 00000000000..92bd8f88025
--- /dev/null
+++ b/.vscode/tasks.json
@@ -0,0 +1,17 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "clean:dist",
+      "type": "shell",
+      "command": "npx rimraf dist",
+      "group": "none",
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "focus": false,
+        "panel": "shared"
+      }
+    }
+  ]
+}
diff --git a/docs/help/debugging.md b/docs/help/debugging.md
index 0aade9ae4b0..2f9aa2c4fc1 100644
--- a/docs/help/debugging.md
+++ b/docs/help/debugging.md
@@ -165,7 +165,7 @@ Default file:
 
 ### Overview
 
-The OpenClaw project uses <kbd>tsdown</kbd> to bundle TypeScript code into JavaScript for distribution. Source maps are required to enable debugging in VSCode-based IDEs because many of the generated files end up with hashed names as part of scoped builds. Generating source maps is a single change before build time and the included <kbd>launch.json</kbd> configurations target the Gateway service, but can be adapted quickly for other purposes.
+The OpenClaw project uses `tsdown` to bundle TypeScript code into JavaScript for distribution. Source maps are required to enable debugging in VSCode-based IDEs because many of the generated files end up with hashed names as part of scoped builds. Generating source maps is a single change before build time and the included `launch.json` configurations target the Gateway service, but can be adapted quickly for other purposes.
 
 ### Setup
 
@@ -176,21 +176,18 @@ The OpenClaw project uses <kbd>tsdown</kbd> to bundle TypeScript code into JavaS
 
 #### Using the Debugger
 
-1. First, build the project with source map generation enabled:
-   - Set <kbd>OUTPUT_SOURCE_MAPS</kbd> to <kbd>true</kbd> in <kbd>tsdown.config.ts</kbd>
-   - Run <kbd>rm -rf dist/ && pnpm build</kbd> to rebuild the project
-
-2. Start debugging:
-   - Open the <kbd>Run and Debug</kbd> panel from the Activity Bar or press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>
-   - Select one of the debug configurations from the dropdown
-   - Press the "Start Debugging" button next to the dropdown or press <kbd>F5</kbd>
-
-3. Set breakpoints in your TypeScript source files (under `src/` directory)
+1. Enable debugging support in the `tsdown` configuration and rebuild:
+   - Set `OUTPUT_SOURCE_MAPS` to `true` in `tsdown.config.ts`
+   - Run `npx rimraf dist && pnpm build` to rebuild the project
+2. Open the `Run and Debug` panel from the Activity Bar or press `Ctrl`+`Shift`+`D`
+3. Select one of the debug configurations from the dropdown
+4. Press the "Start Debugging" button next to the dropdown or press `F5`
+5. Set breakpoints in your TypeScript source files (under `src/` directory)
    - The debugger will correctly map breakpoints to the compiled JavaScript via source maps
    - You'll be able to inspect variables, step through code, etc.
 
 #### Additional Notes
 
-- If using the "Rebuild and Debug Gateway" option, restarting the debugger will also rebuild the project with any updated code
-- Change the `launch.json` settings for `runtimeArgs` to debug other sections of the project
+- If using the "Rebuild and Debug Gateway" option, restarting the debugger will completely delete the `/dist` folder, causing the `run-node.mjs` script to rebuild the project
+- Change the `launch.json` settings for `args` to debug other sections of the project
 - If you need to use the built OpenClaw CLI for other tasks (i.e. `dashboard --no-open` if your debug session spawns a new auth token) you can run it in another shell as `node ./openclaw.mjs` or a shell alias like `alias openclaw-build="node $(pwd)/openclaw.mjs"`