Python 调试 Skill：pdb / breakpoint / debugpy 远程调试一条龙

Python 调试最大的坑不是「不会断点」，而是「用错了调试器」——本地小脚本用上了重量级工具，生产服务又找不到入口。OpenClaw 官方的 Python Debugpy Skill 给出的原则很朴素：先选能到达问题帧的最小调试器，再动手。

按场景选调试器

  • breakpoint()：本地代码、能改源码、要最快路径——在可疑处插一行，跑起来就停
  • python3 -m pdb：不改源码、从入口启动——python3 -m pdb script.py；-c continue 直接停在未处理异常处
  • debugpy：远程/无头进程、DAP 客户端、已运行 PID、服务启动竞态——最通用的远程附加方案

远程附加的标准姿势

对已经跑起来的服务，Skill 给出两条路：一是启动时监听——python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client script.py；二是附加到已有进程——python3 -m debugpy --listen 127.0.0.1:5678 --pid <pid>。需要改源码附加时，用 debugpy.listen() + wait_for_client() + breakpoint() 三件套，在代码里指定监听端口并等待客户端接入。

调试无头/后台进程、子进程、启动竞态这些场景，debugpy 是唯一能稳定到达正确帧的方案——这也是它被单独做成 Skill 的原因。

典型使用场景

  • 隐藏的局部变量：函数里的状态在改，用断点看每一帧的真实值
  • 服务启动竞态：启动阶段就崩，用 --wait-for-client 在入口等待调试器接入
  • 生产/远程进程：附加到已运行 PID，不用重启服务即可排查

使用方法与下载

OpenClaw 用户：python-debugpy 是 OpenClaw 内置 skill，调试 Python 时自然语言触发（「帮我调这个 Python」）即可。见 OpenClaw 官方文档。

其他 Agent 用户：依赖 python3 与 debugpy（pip install debugpy），遵循标准 SKILL.md 约定即可复用整套调试决策树。源码见 OpenClaw GitHub 仓库。

相关资源

调试类 Skill 成对使用：Node.js 调试（node-inspect-debugger） 处理 JS/TS 侧；Spike（spike） 验证阶段发现的疑难 bug 可交给调试 Skill 处理。

---

滚动至顶部