Troubleshooting

PhysiClaw exits on its own after a while

PhysiClaw runs fine but quits on its own after a while. This usually happens because the system shuts off the camera after a long stretch of inactivity. Without it, PhysiClaw can’t capture the phone screen, so it exits.

Fix

Make sure the computer running PhysiClaw won’t lock the screen or go to sleep.

Camera preview works, but calibration keeps failing

The camera looks fine when you check it in a video or camera app, yet calibration fails as soon as you run it. This is usually a lighting issue: the room is too dark, a light is shining directly onto the phone screen and causing glare, or the screen brightness is too low.

Fix

Make sure the room is evenly lit, avoid glare on the screen, and set the phone’s screen brightness to a suitable level.

The agent suddenly performs much worse

Tasks that used to run reliably start failing. The agent mis-taps, gets lost, or gives up, yet nothing in software changed. The cause is almost always physical. The camera got bumped and no longer points straight at the phone screen, or a light is now hitting the screen directly, blowing out the image so the agent can barely see it.

Fix

Check what the model actually saw. physiclaw logs lists recent sessions, and physiclaw logs <id> prints the path to the session’s images/ folder, which holds the exact frames sent to the LLM. Tilted, blurry, or washed-out frames confirm it. Re-aim the camera, recalibrate if it moved, and light the screen evenly with no direct glare.

Solenoid clicks sometimes, unresponsive other times

Usually this is flex fatigue in the solenoid cable, meaning the wire has broken. If the joint is soldered, solder wicks into the wire and makes that section stiff and brittle, so it can’t take repeated bending. The cable is pulled straight as the gantry extends and bent as it returns; after enough cycles it breaks at the bend point. The broken ends touch and separate intermittently, so the clicks come and go.

Fix

Rewire it, keeping two things in mind: place the joint within 50 mm of the solenoid, clear of the section that flexes most; and secure the leads to the tube holder (the drag-chain bracket) with a zip tie, so the wiring at the control board terminals doesn’t swing back and forth with the solenoid’s movement and work the terminals loose over time.

Shortcuts suddenly stop working mid-run

The server is still up, but the Shortcuts suddenly fail. Usually the phone or the computer switched WiFi, so they’re no longer on the same LAN and the Shortcuts can’t reach the server.

Fix

Check both devices’ WiFi and put them back on the same network.