免费在 GitHub 公开中文介绍

python-debugpy

通过暂停Python执行、检查变量和跟踪代码流程来查找故障原因。可查看异常发生时的状态，也可连接正在运行的进程，调查测试失败或服务中的问题。

原文查看原文说明

Debug Python with pdb, breakpoint(), post-mortem inspection, and debugpy remote attach.

openclaw/openclaw

AI 评分100分/ 100 查看安装方法

适用场景

检查失败的Python测试中的变量
追踪意外的状态变化
查看异常发生时的程序状态
调试正在运行的服务

中文介绍

功能

暂停Python程序的执行，通过检查变量值和代码流程查找故障原因。可根据情况选择写入代码的breakpoint()、启动程序时使用的pdb，或从外部连接正在运行程序的debugpy。还可查看异常发生时的状态，或设置条件，让程序仅在满足条件时暂停。

适用场景

适合调查原因不明的测试失败，或查找变量在何处发生了意外变化。也可用于检查长期运行的服务，以及没有图形界面的环境中的进程。

使用示例

“用最小条件复现这个失败的测试，并用pdb检查变量。”
“用debugpy连接正在运行的服务，检查执行停在了哪里。”

注意事项

需要python3，并在当前使用的环境中安装debugpy。连接地址原则上限制为127.0.0.1，连接运行中的进程前应确认目标PID。使用pdb调查时，应关闭测试的并行执行。调查结束后，移除调试代码，并重新运行常规测试。

本介绍由 AI（OpenAI Codex）根据公开的 SKILL.md 撰写。准确的规格请查看下方原文。

客观评估

AI 仅根据 SKILL.md 的内容，从 4 个方面进行了评估。星标数和热度不计入评估。

指令清晰度能否看出何时使用、做什么: A良好明确列出测试失败、运行中服务等场景，并说明调试器的选择方法。
步骤具体性步骤、输入输出和示例是否具体: A良好提供启动、连接PID的命令、pdb操作及调查后重新测试的步骤。
安全性发送数据、删除文件、执行命令等是否有说明: A良好要求仅绑定本机地址、确认目标PID并移除调试代码。
安装难易度所需工具和 API 密钥是否少且有说明: A良好说明需要python3，并提供在当前环境安装debugpy的命令。

总分按每项 A=25 分、B=15 分、C=5 分相加。由 AI（OpenAI Codex）于 2026年10月19日评估。仅供参考，安装前请同时查看原文。

如果您认为评估有误，请申请复核

包含的文件（1）

SKILL.md2.5 KB

SKILL.md（原文）

安装前可以查看交给 AI 代理的指令内容。

Python Debugpy

Use when Python code needs interactive debugging: hidden locals, confusing state mutation, failing tests, subprocesses, long-running services, or remote/headless attach.

Pick the smallest debugger that reaches the bad frame.

Choose

breakpoint(): local code, source edits ok, fastest path.
python3 -m pdb: no source edit, launch from the beginning.
python3 -m pdb -c continue: stop at an unhandled exception.
debugpy: remote/headless process, DAP client, already-running PID, or service startup race.

Commands

python3 -m pdb path/to/script.py arg1
python3 -m pdb -c continue path/to/script.py
python3 -c "import debugpy" || python3 -m pip install debugpy
python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client path/to/script.py
python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client -m package.module
python3 -m debugpy --listen 127.0.0.1:5678 --pid <pid>

For source-edit attach:

import debugpy

debugpy.listen(("127.0.0.1", 5678))
debugpy.wait_for_client()
debugpy.breakpoint()

For post-mortem:

import pdb, sys

try:
    run()
except Exception:
    pdb.post_mortem(sys.exc_info()[2])
    raise

pdb

Flow: n, s, r, c, q.
Stack/source: w, u, d, a, l, ll.
Values: p expr, pp expr, display expr.
Breakpoints: b file.py:42, b func, b file.py:42, condition, cl <num>.
Mutate/evaluate: !statement; full REPL: interact.

Rules

Reproduce with the smallest command/test first.
Disable parallel test workers for pdb; interactive stdin usually breaks inside worker pools.
Keep debugpy in the active env; do not add it as a project dependency unless the project already wants it.
Bind debug servers to 127.0.0.1; do not expose 0.0.0.0 unless isolated or tunnelled.
Use unique ports for parallel sessions.
debugpy --pid injects into a running process; confirm the target pid before attaching.
If PID attach fails on Linux, check ptrace/container privileges before changing the target.
Cleanup before commit: rg -n 'breakpoint\\(|pdb\\.set_trace|debugpy\\.' --type py.
Rerun the normal project test/gate without the debugger.
PYTHONBREAKPOINT=0 disables breakpoint().
If a process is stuck after debugger detach, confirm it is not still paused at a breakpoint.