Python Debugging Skill: pdb, breakpoint() & Remote Debugpy Attach

OpenClaw's official Python debugging skill. Picks the smallest debugger per scenario: breakpoint() for source edits, pdb for launch-time, debugpy for remote or headless attach — from local scripts to stubborn prod bugs.

Skill

The biggest Python debugging trap is not "no breakpoints" — it is using the wrong debugger. Reaching for heavyweight tooling on a tiny local script, or finding no entry point on a production service. OpenClaw's official Python Debugpy Skill states the principle plainly: pick the smallest debugger that can reach the bad frame, then act.

Choosing a debugger by scenario

  • breakpoint(): local code, source edits allowed, fastest path — drop one line where you suspect trouble and run

  • python3 -m pdb: no source edits, launch from entry — python3 -m pdb script.py; -c continue stops at the first unhandled exception

  • debugpy: remote/headless processes, DAP clients, already-running PIDs, service startup races — the most general remote-attach option

The standard remote-attach posture

For services already running, the skill offers two paths: listen at startup — python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client script.py; or attach to an existing process — python3 -m debugpy --listen 127.0.0.1:5678 --pid <pid>. For source-edit attach, use the three-piece combo debugpy.listen() + wait_for_client() + breakpoint() to bind a port in code and wait for a client.

For headless/background processes, subprocesses, and startup races, debugpy is the only option that reliably reaches the right frame — which is exactly why it earned its own skill.

Typical use cases

  • Hidden locals: state mutating inside a function — inspect the true value at each frame

  • Startup races: crashing at boot — use --wait-for-client to attach at entry

  • Production / remote processes: attach to a running PID and debug without a restart

How to use & download

OpenClaw users: python-debugpy is a built-in skill — trigger it in natural language when debugging Python. See OpenClaw docs.

Other agent users: depends on python3 and debugpy (pip install debugpy); the whole decision tree is reusable via the standard SKILL.md convention. Source: OpenClaw GitHub repo.

Related resources

Debugging skills work in pairs: Node.js debugging (node-inspect-debugger) covers the JS/TS side; stubborn bugs found during Spike (spike) validation can be handed to a debugging skill.