探针校准工具

Klipper 的探针 Z 偏移、Z 限位、网床、Delta 校准等命令，最终都会进入同一个手动探测流程。它由 manual_probe 模块提供——该模块 Klipper 自动加载，printer.cfg 里不用写、也没有可配项；真正要配的是 [probe]（或 [bltouch]）和 [stepper_z]。

该流程输出的大部分提示只是在等你输入 TESTZ，不是故障。真正会导致校准作废或命令起不来的只有下面三条。

一分钟速查

终端提示	性质	该怎么做
`Starting manual Z probe…`	正常提示，等待输入	`TESTZ Z=-0.1` 向下逼近 → `ACCEPT`；放弃用 `ABORT`
`Manual probe failed!…`	本次校准作废（不 shutdown、不写配置）	重新执行校准命令；全程不动 X/Y，且最终 Z 必须比开始时更低
`Already in a manual Z probe…`	命令级错误	先 `ABORT` 结束旧会话，或结束占用 `ACCEPT` 的其他工具

探针硬件与配置类报错（Probe triggered prior to movement、No trigger on probe、Probe samples exceed samples_tolerance、BLTouch、bed_mesh）见运动、限位与调平报错。

哪些命令会进入手动探测

命令	用途	手动探测
`MANUAL_PROBE`	无探头时用纸片法测某点 Z	始终
`PROBE_CALIBRATE`	校准探针 `z_offset`	探测完成后微调
`Z_ENDSTOP_CALIBRATE`	校准 `position_endstop`	始终；仅当 `[stepper_z]` 配了 `position_endstop` 时才存在，以探针为 Z 限位（`probe:z_virtual_endstop`，如 TAP）的机器没有这条命令
`DELTA_CALIBRATE`	Delta 塔高 / 半径	无探针或 `METHOD=manual` 时
`BED_MESH_CALIBRATE`、`BED_TILT_CALIBRATE`、`Z_TILT_ADJUST`、`QUAD_GANTRY_LEVEL`	网床 / 倾斜 / 多 Z 取点	加 `METHOD=manual` 时

界面弹窗

Mainsail / Fluidd 的校准弹窗读的就是 manual_probe 的状态，点 ACCEPT 与终端输入 ACCEPT 等价。

TESTZ 用法

写法	行为
`TESTZ Z=-0.1`	按数值移动，不受步长限制（离得远时用它一步到位）
`TESTZ Z=-` / `--`	向更低的已试探点二分 / 跳转，单步 ≤ `0.2mm`
`TESTZ Z=+` / `++`	向更高的已试探点二分 / 跳转，单步 ≤ `0.2mm`

两点需要知道

+ / - / ++ / -- 每次最多移动 0.2mm，嫌慢就改用数值写法。
每次 TESTZ 会先抬到「目标 + 0.5mm」再下降到目标，所以中途看到喷嘴略微上升是正常的。

三条提示详解

Starting manual Z probe

// Starting manual Z probe. Use TESTZ to adjust position.
// Finish with ACCEPT or ABORT command.
// Z position: ?????? --> 5.000 <-- ??????

正常提示，状态仍是 ready，不会自行结束也不会超时。--> 与 <-- 之间是当前 Z；左右两侧分别是已试探过的更低 / 更高位置，?????? 表示该方向还没有记录。

要做的：按纸片法流程逐步下调，接触后 ACCEPT。

Manual probe failed!

// Manual probe failed! Use TESTZ commands to position the
// nozzle prior to running ACCEPT.

本次校准作废：不触发 shutdown，但不会写入任何配置，ACCEPT / TESTZ / ABORT 随即失效，必须重新执行校准命令（此时点 SAVE_CONFIG 没有意义）。

原因只有两条，任一命中即失败：

X/Y 动过：会话期间用了摇杆 / 方向键，或宏里带 G1 X.. Y..、Klicky 的停泊动作。
Z 没有更低：只向上抬过，或下探过头又抬回起点——判定只看按下 ACCEPT 那一刻的 Z，与中间过程无关（哪怕只高 0.01mm 也不通过）。

解决：

重新执行校准命令，用 TESTZ Z=-0.1（接近后 -0.05）单向向下逼近；确认 Z position 中间数值比开始时更小，再 ACCEPT。
会话期间不要碰 X/Y。
若每次立即失败，检查起始高度是否过低，按结构区分：
- 有独立 Z 限位的机器：看 [stepper_z] position_endstop。
- 用探针当 Z 限位（probe:z_virtual_endstop，如 Voron TAP 这类喷嘴触发结构）：[stepper_z] 没有 position_endstop，应检查 [probe] z_offset 与 Z 轴下限 position_min。
- Delta 机器：还可检查 minimum_z_position。

Already in a manual Z probe

Already in a manual Z probe. Use ABORT to abort it.

命令级错误：启动新会话前，Klipper 发现 ACCEPT 已被占用。

常见原因：上一个会话没以 ACCEPT / ABORT 收尾；BED_SCREWS_ADJUST 等工具同样占用 ACCEPT；自定义了与内置命令同名的 gcode_macro。

解决：

执行 ABORT 结束旧会话。若提示 Unknown command: ABORT，说明当前没有会话——去结束真正占用 ACCEPT 的那个工具（如 BED_SCREWS_ADJUST 里执行 ADJUSTED）。
每次都必现时，检查所有 include 文件里是否有与内置命令同名的宏，重命名或删除后重试。
刷新界面或重启 Klipper 可清掉界面上残留的校准弹窗。

ACCEPT 之后

MANUAL_PROBE 回复 Z position is <数值>；PROBE_CALIBRATE、Z_ENDSTOP_CALIBRATE 会给出建议的新数值。
必须执行 SAVE_CONFIG（或界面上的 SAVE_CONFIG & Restart）才会写入配置并重启生效。
中途放弃用 ABORT：不写配置，也不会触发 Manual probe failed!。

标准纸片法流程

运动风险

校准过程中喷嘴会自动向下移动。执行前移开手和工具，确认喷嘴下方无遮挡、热床上无残留件，并随时准备急停。

完成归位，把喷嘴移到待校准点正上方。
执行校准命令，确认出现 Starting manual Z probe。
纸片放在喷嘴与热床之间，来回抽动。
TESTZ Z=-0.1 逐步下降；接近后改用 TESTZ Z=-0.05 或 Z=- 细分。
纸片被轻微夹住、抽动有明显阻力时停止。
执行 ACCEPT；若报 Manual probe failed!，按该条目排查后重做。
执行 SAVE_CONFIG 保存并重启。

只朝一个方向逼近

始终从高处向下逼近接触点，既能减少 Z 轴间隙误差，也不会因 Z 未低于起始高度而失败。

一分钟速查​

哪些命令会进入手动探测​

TESTZ 用法​

三条提示详解​

Starting manual Z probe​

Manual probe failed!​

Already in a manual Z probe​

ACCEPT 之后​

标准纸片法流程​

相关文档​