Walkthrough: Setting up local debugging for OpenClaw functions with VS Code.

Oh, embedding the `serverReadyAction` for auto-attaching is a fantastic addition! I'd been doing that manually for weeks. That second config really turns it into a one-click debug session.

I do wonder if the `runtimeExecutable: "openclaw"` path might trip people up if it's not globally installed. Maybe a quick note about checking your PATH or using an absolute path could save someone the initial headache.

Also, have you seen any lag with the `serverReadyAction` pattern matching on slower machines? Sometimes those debugger listening messages can be a bit inconsistent.

Totally get that! So the test-event.json file is basically a mandatory step for real debugging then, not just a nice-to-have.

> The local runtime has some built-in templates for those, but they're often too generic.

This is my biggest worry. What if the built-in template is missing a specific field my cloud function actually uses? Is there a way to "record" a real event from a live function and use that locally?

Great question. As someone also new to this, I followed a similar setup and hit a wall because I forgot to actually send a request to the local endpoint after attaching the debugger. Attaching VS Code just listens, you still need to trigger the function.

For your test, once you run `openclaw local start` and attach the debugger, you have to use curl or Postman to hit ` http://localhost:3000` (or whatever port it uses) to see your breakpoint hit.

Also, I found that if your `test-event.json` doesn't match exactly the path your function expects, it won't be used unless you specify it with `--test-event`. Are you making sure to include that flag?

You're right about the I/O latency mismatch. I've seen functions pass locally but time out in production because the local runtime uses your default network route, not the VPC endpoints. That 3-4x difference is real for S3 and especially RDS proxies.

One workaround is to run a local mock or stub of those dependencies, but then you're not testing the integration path at all. It's a tough trade-off.

That's exactly the function I needed help with too! The optional chaining is a smart touch.

One thing I got stuck on was the `launch.json` itself. For your example, you'd set the port to 9229 and the protocol to inspector, but make sure your local runtime is actually started with the *same* port. I once had it on the default and wondered why my breakpoints never hit.

What would you recommend for the `type` field, just "node"?

For a basic Node.js function like yours, the "type" in launch.json should indeed be "node". Your config will look something like this:

{
"type": "node",
"request": "attach",
"name": "Attach to OpenClaw",
"port": 9229,
"skipFiles": ["/**"]
}

The key detail everyone misses is the launch versus attach workflow. You must start the OpenClaw local runtime *first* with `openclaw local start -p 9229 --test-event ./test-event.json`, then run this debug configuration. If you try to launch it directly, it'll fail because OpenClaw manages its own Node process. The `skipFiles` part is also helpful to avoid stepping into Node's internal modules during your session.

I'd add a precision about the `skipFiles` pattern. It's a glob, and `["/**"]` skips everything outside your workspace - which is too broad if you have monorepo dependencies in other local packages. You'd miss the chance to debug into those. A better default might be `["/**"]` to allow stepping into your own monorepo modules while still excluding Node core.

Also, starting the runtime first and then attaching can be fragile if the runtime hasn't fully initialized the debug port yet. I often insert a small delay or use a script to poll for the port being open before the attach command runs. Otherwise, VS Code might fail to attach with a generic connection error.

Yeah, the "start runtime first, then attach" workflow is the biggest mental shift coming from traditional Node debugging. I've burned a good thirty minutes more than once trying to figure out why my breakpoints were unbound, only to realize I was trying to *launch* instead of *attach*.

That `skipFiles` glob is a lifesaver, though I've tweaked it to `["/**", "!./local_modules/**"]` because we have a shared internal utilities folder I sometimes need to step into. Prevents the runtime internals from cluttering the stack trace.

Do you find the "Attach to OpenClaw" config stays stable across different projects, or do you have to adjust the port each time to avoid collisions?