From f42e8f8d68c9a8d78f522083fc4bf047076e51a8 Mon Sep 17 00:00:00 2001 From: Andrew Porter Date: Fri, 13 Mar 2026 16:56:17 -0700 Subject: [PATCH 1/8] feat(build): add sourcemap config to tsdown.config.ts, add default debug sessions in launch.json, update docs --- .vscode/launch.json | 30 ++++++++++++++++++++++++++++++ README.md | 2 +- docs/help/debugging.md | 34 ++++++++++++++++++++++++++++++++++ tsdown.config.ts | 2 ++ 4 files changed, 67 insertions(+), 1 deletion(-) create mode 100644 .vscode/launch.json diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 00000000000..8bc6c565f3e --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,30 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Debug Gateway", + "type": "node", + "request": "launch", + "runtimeArgs": ["openclaw.mjs", "gateway", "run"], + "console": "integratedTerminal", + "skipFiles": ["/**", "node_modules/**"], + "outFiles": ["${workspaceFolder}/dist/**/*.js"], + "sourceMaps": true, + "smartStep": true, + "internalConsoleOptions": "openOnSessionStart" + }, + { + "name": "Rebuild and Debug Gateway", + "type": "node", + "request": "launch", + "runtimeExecutable": "pnpm", + "runtimeArgs": ["run", "openclaw", "--", "gateway", "run"], + "console": "integratedTerminal", + "skipFiles": ["/**", "node_modules/**"], + "outFiles": ["${workspaceFolder}/dist/**/*.js"], + "sourceMaps": true, + "smartStep": true, + "internalConsoleOptions": "openOnSessionStart" + } + ] +} diff --git a/README.md b/README.md index 767f4bc2141..392e23a7b61 100644 --- a/README.md +++ b/README.md @@ -555,5 +555,5 @@ Thanks to all clawtributors: sktbrd larlyssa Mind-Dragon pcty-nextgen-service-account tmchow uli-will-code Marc Gratch JackyWay aaronveklabs CJWTRUST erik-agens odnxe T5-AndyML Josh Phillips mujiannan Marco Di Dionisio Randy Torres afern247 0oAstro alexanderatallah testingabc321 humanwritten aaronn Alphonse-arianee gtsifrikas hrdwdmrbl hugobarauna jiulingyun kitze loukotal - MSch odrobnik reeltimeapps rhjoh ronak-guliani snopoke + MSch odrobnik reeltimeapps rhjoh ronak-guliani snopoke SwissArmyBud

diff --git a/docs/help/debugging.md b/docs/help/debugging.md index 61539ec39a3..0aade9ae4b0 100644 --- a/docs/help/debugging.md +++ b/docs/help/debugging.md @@ -160,3 +160,37 @@ Default file: - Raw stream logs can include full prompts, tool output, and user data. - Keep logs local and delete them after debugging. - If you share logs, scrub secrets and PII first. + +## Debugging in VSCode + +### Overview + +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 + +#### Included Configurations + +1. **Debug Gateway** - Debugs the Gateway service of a pre-existing build +2. **Rebuild and Debug Gateway** - Debugs the Gateway service after creating a new build + +#### Using the Debugger + +1. First, build the project with source map generation enabled: + - Set OUTPUT_SOURCE_MAPS to true in tsdown.config.ts + - Run rm -rf dist/ && pnpm build to rebuild the project + +2. Start debugging: + - Open the Run and Debug panel from the Activity Bar or press Ctrl+Shift+D + - Select one of the debug configurations from the dropdown + - Press the "Start Debugging" button next to the dropdown or press F5 + +3. 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 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"` diff --git a/tsdown.config.ts b/tsdown.config.ts index 1806debd474..38cd0b7e0c8 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -3,6 +3,7 @@ import { defineConfig } from "tsdown"; const env = { NODE_ENV: "production", }; +const OUTPUT_SOURCE_MAPS = false; function buildInputOptions(options: { onLog?: unknown; [key: string]: unknown }) { if (process.env.OPENCLAW_BUILD_VERBOSE === "1") { @@ -36,6 +37,7 @@ function nodeBuildConfig(config: Record) { env, fixedExtension: false, platform: "node", + sourcemap: OUTPUT_SOURCE_MAPS, inputOptions: buildInputOptions, }; } From 9cc261225b7c5f456c80b25f61b50fc3a72955ce Mon Sep 17 00:00:00 2001 From: Andrew Porter Date: Fri, 13 Mar 2026 21:56:05 -0700 Subject: [PATCH 2/8] (pr feedback) add explicit dist cleanup before debug, update docs for clarity and conformity --- .vscode/launch.json | 5 +++-- .vscode/tasks.json | 17 +++++++++++++++++ docs/help/debugging.md | 23 ++++++++++------------- 3 files changed, 30 insertions(+), 15 deletions(-) create mode 100644 .vscode/tasks.json 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_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_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 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. +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 tsdown to bundle TypeScript code into JavaS #### Using the Debugger -1. First, build the project with source map generation enabled: - - Set OUTPUT_SOURCE_MAPS to true in tsdown.config.ts - - Run rm -rf dist/ && pnpm build to rebuild the project - -2. Start debugging: - - Open the Run and Debug panel from the Activity Bar or press Ctrl+Shift+D - - Select one of the debug configurations from the dropdown - - Press the "Start Debugging" button next to the dropdown or press F5 - -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"` From b036c383fdd034704630cd36714d905be48e0d47 Mon Sep 17 00:00:00 2001 From: Andrew Porter Date: Fri, 13 Mar 2026 22:12:18 -0700 Subject: [PATCH 3/8] (pr feedback): use 'program' pattern in launch.json config --- .vscode/launch.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.vscode/launch.json b/.vscode/launch.json index 3525813ee05..41d4639c349 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -5,7 +5,8 @@ "name": "Debug Gateway", "type": "node", "request": "launch", - "args": ["openclaw.mjs", "gateway", "run"], + "program": "${workspaceFolder}/openclaw.mjs", + "args": ["gateway", "run"], "console": "integratedTerminal", "skipFiles": ["/**", "node_modules/**"], "outFiles": ["${workspaceFolder}/dist/**/*.js"], From 058640f33c90c731b3d13acaca5871d78e6aef76 Mon Sep 17 00:00:00 2001 From: Andrew Porter Date: Sat, 14 Mar 2026 13:51:53 -0700 Subject: [PATCH 4/8] Update .vscode/tasks.json Per greptile Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- .vscode/tasks.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 92bd8f88025..a081a09b354 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -4,7 +4,7 @@ { "label": "clean:dist", "type": "shell", - "command": "npx rimraf dist", + "command": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\"", "group": "none", "presentation": { "echo": true, From 4dfcd5297fb7684141e864ce1c0e8e7f1b77656e Mon Sep 17 00:00:00 2001 From: Andrew Porter Date: Sat, 14 Mar 2026 14:11:36 -0700 Subject: [PATCH 5/8] Update docs/help/debugging.md Another greptile suggestion Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- docs/help/debugging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/help/debugging.md b/docs/help/debugging.md index 2f9aa2c4fc1..8a7a118ef59 100644 --- a/docs/help/debugging.md +++ b/docs/help/debugging.md @@ -178,7 +178,7 @@ The OpenClaw project uses `tsdown` to bundle TypeScript code into JavaScript for 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 + - Run `node -e "require('fs').rmSync('dist', {recursive: true, force: true})" && 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` From 968bfd2d192ae393790bb2413354b1d556b2f24b Mon Sep 17 00:00:00 2001 From: Andrew Porter Date: Sat, 14 Mar 2026 16:07:57 -0700 Subject: [PATCH 6/8] (pr feedback): use process env variable, be more explicit about cleanup, update docs --- .vscode/launch.json | 31 +++++++++++++++++-------------- .vscode/tasks.json | 2 +- docs/help/debugging.md | 36 +++++++++++++++++------------------- package.json | 1 + tsdown.config.ts | 2 +- 5 files changed, 37 insertions(+), 35 deletions(-) diff --git a/.vscode/launch.json b/.vscode/launch.json index 41d4639c349..27fa99cc057 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -1,6 +1,23 @@ { "version": "0.2.0", "configurations": [ + { + "name": "Rebuild and Debug Gateway", + "type": "node", + "request": "launch", + "preLaunchTask": "clean:dist", + "runtimeExecutable": "pnpm", + "args": ["run", "openclaw", "--", "gateway", "run"], + "env": { + "OUTPUT_SOURCE_MAPS": "1" + }, + "console": "integratedTerminal", + "skipFiles": ["/**", "node_modules/**"], + "outFiles": ["${workspaceFolder}/dist/**/*.js"], + "sourceMaps": true, + "smartStep": true, + "internalConsoleOptions": "openOnSessionStart" + }, { "name": "Debug Gateway", "type": "node", @@ -13,20 +30,6 @@ "sourceMaps": true, "smartStep": true, "internalConsoleOptions": "openOnSessionStart" - }, - { - "name": "Rebuild and Debug Gateway", - "type": "node", - "request": "launch", - "preLaunchTask": "clean:dist", - "runtimeExecutable": "pnpm", - "args": ["run", "openclaw", "--", "gateway", "run"], - "console": "integratedTerminal", - "skipFiles": ["/**", "node_modules/**"], - "outFiles": ["${workspaceFolder}/dist/**/*.js"], - "sourceMaps": true, - "smartStep": true, - "internalConsoleOptions": "openOnSessionStart" } ] } diff --git a/.vscode/tasks.json b/.vscode/tasks.json index a081a09b354..3318e75656b 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -4,7 +4,7 @@ { "label": "clean:dist", "type": "shell", - "command": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\"", + "command": "pnpm clean:dist", "group": "none", "presentation": { "echo": true, diff --git a/docs/help/debugging.md b/docs/help/debugging.md index 8a7a118ef59..25afc1c442c 100644 --- a/docs/help/debugging.md +++ b/docs/help/debugging.md @@ -163,31 +163,29 @@ Default file: ## Debugging in VSCode -### Overview +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 the build process. The included `launch.json` 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. +1. **Rebuild and Debug Gateway** - Debugs the Gateway service after creating a new build +2. **Debug Gateway** - Debugs the Gateway service of a pre-existing build ### Setup -#### Included Configurations +The default **Rebuild and Debug Gateway** configuration is batteries-included, it will automatically delete the `/dist` folder and rebuild the project with debugging enabled: -1. **Debug Gateway** - Debugs the Gateway service of a pre-existing build -2. **Rebuild and Debug Gateway** - Debugs the Gateway service after creating a new build +1. Open the **Run and Debug** panel from the Activity Bar or press `Ctrl`+`Shift`+`D` +2. Ensure **Rebuild and Debug Gateway** is selected in the configuration dropdown, then press the **Start Debugging** button -#### Using the Debugger +Alternatively - if you prefer to manage the build and debug processes manually: -1. Enable debugging support in the `tsdown` configuration and rebuild: - - Set `OUTPUT_SOURCE_MAPS` to `true` in `tsdown.config.ts` - - Run `node -e "require('fs').rmSync('dist', {recursive: true, force: true})" && 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. +1. Open a terminal and enable source maps: `export OUTPUT_SOURCE_MAPS=1` +2. In the same terminal, rebuld the project: `pnpm clean:dist && pnpm build` +3. Select the **Debug Gateway** option in the **Run and Debug** configuration dropdown, then press the **Start Debugging** button -#### Additional Notes +You can now set breakpoints in your TypeScript source files (`src/` directory) and the debugger will correctly map breakpoints to the compiled JavaScript via source maps. You'll be able to inspect variables, step through code, and examine call stacks as expected. -- 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"` +### Notes + +- If using the **"Rebuild and Debug Gateway"** option, each time the debugger is launched it will completely delete the `/dist` folder and trigger the `run-node.mjs` script to rebuild the project +- If using the **"Debug Gateway"** option, debug sessions can be started and stopped at any time without affecting the `/dist` folder, but you must use a separate terminal process to both enable debugging and manage the build cycle +- Modify 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 execute it in another terminal as `node ./openclaw.mjs` or create a shell alias like `alias openclaw-build="node $(pwd)/openclaw.mjs"` diff --git a/package.json b/package.json index 6cde8d84431..17338d4209a 100644 --- a/package.json +++ b/package.json @@ -233,6 +233,7 @@ "check:docs": "pnpm format:docs:check && pnpm lint:docs && pnpm docs:check-links", "check:host-env-policy:swift": "node scripts/generate-host-env-security-policy-swift.mjs --check", "check:loc": "node --import tsx scripts/check-ts-max-loc.ts --max 500", + "clean:dist": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\"", "deadcode:ci": "pnpm deadcode:report:ci:knip", "deadcode:knip": "pnpm dlx knip --config knip.config.ts --isolate-workspaces --production --no-progress --reporter compact --files --dependencies", "deadcode:report": "pnpm deadcode:knip; pnpm deadcode:ts-prune; pnpm deadcode:ts-unused", diff --git a/tsdown.config.ts b/tsdown.config.ts index 6a2caa0cbda..4a92fa05483 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -3,7 +3,7 @@ import { defineConfig } from "tsdown"; const env = { NODE_ENV: "production", }; -const OUTPUT_SOURCE_MAPS = false; +const OUTPUT_SOURCE_MAPS = process.env.OUTPUT_SOURCE_MAPS === "1"; function buildInputOptions(options: { onLog?: unknown; [key: string]: unknown }) { if (process.env.OPENCLAW_BUILD_VERBOSE === "1") { From bae32d19249fb74810f2e9f72bad467b418c8b6f Mon Sep 17 00:00:00 2001 From: Andrew Porter Date: Sat, 14 Mar 2026 16:39:17 -0700 Subject: [PATCH 7/8] (pr feedback): use process env variable, be more explicit about cleanup, update docs --- docs/help/debugging.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/help/debugging.md b/docs/help/debugging.md index 25afc1c442c..ab54a0c5ee0 100644 --- a/docs/help/debugging.md +++ b/docs/help/debugging.md @@ -173,13 +173,16 @@ Source maps are required to enable debugging in VSCode-based IDEs because many o The default **Rebuild and Debug Gateway** configuration is batteries-included, it will automatically delete the `/dist` folder and rebuild the project with debugging enabled: 1. Open the **Run and Debug** panel from the Activity Bar or press `Ctrl`+`Shift`+`D` -2. Ensure **Rebuild and Debug Gateway** is selected in the configuration dropdown, then press the **Start Debugging** button +2. In the IDE, ensure **Rebuild and Debug Gateway** is selected in the configuration dropdown and then press the **Start Debugging** button Alternatively - if you prefer to manage the build and debug processes manually: -1. Open a terminal and enable source maps: `export OUTPUT_SOURCE_MAPS=1` -2. In the same terminal, rebuld the project: `pnpm clean:dist && pnpm build` -3. Select the **Debug Gateway** option in the **Run and Debug** configuration dropdown, then press the **Start Debugging** button +1. Open a terminal and enable source maps: + - **Linux/macOS**: `export OUTPUT_SOURCE_MAPS=1` + - **Windows (PowerShell)**: `$env:OUTPUT_SOURCE_MAPS="1"` + - **Windows (CMD)**: `set OUTPUT_SOURCE_MAPS=1` +2. In the same terminal, rebuild the project: `pnpm clean:dist && pnpm build` +3. In the IDE, select the **Debug Gateway** option in the **Run and Debug** configuration dropdown and then press the **Start Debugging** button You can now set breakpoints in your TypeScript source files (`src/` directory) and the debugger will correctly map breakpoints to the compiled JavaScript via source maps. You'll be able to inspect variables, step through code, and examine call stacks as expected. From e48a1dedc37187897289730cc849a40aad1bce89 Mon Sep 17 00:00:00 2001 From: Andrew Porter Date: Sat, 14 Mar 2026 16:47:43 -0700 Subject: [PATCH 8/8] Update .vscode/tasks.json per greptile Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- .vscode/tasks.json | 1 + 1 file changed, 1 insertion(+) diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 3318e75656b..2eac84a7b7d 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -6,6 +6,7 @@ "type": "shell", "command": "pnpm clean:dist", "group": "none", + "problemMatcher": [], "presentation": { "echo": true, "reveal": "always",