How to Build a Water Leak Detection Agent with OpenClaw on Raspberry Pi

Water damage is the second most common homeowners insurance claim in the United States. Insurance companies pay an average of $13,954 per water-related property damage claim, and roughly 1 in 60 insured homes files a water damage claim each year. A $5 sensor on a Raspberry Pi can prevent thousands in damage, but only if the detection logic is smart enough to act on real leaks and ignore false alarms.

Most Raspberry Pi water leak tutorials follow the same pattern: wire a conductivity sensor to a GPIO pin, poll the pin in a loop, and send an alert when the reading goes HIGH. That works for a dramatic burst pipe. But real-world leak detection is messier. Condensation forms on cold water pipes in humid basements. A water heater's pressure relief valve drips occasionally during normal operation. A pet knocks over a water bowl near the sensor.

A threshold-only script treats all of these the same way: alarm. After a few 3 AM false positives, you silence the notifications. Then a real leak happens and nobody responds.

OpenClaw adds a reasoning layer between the sensor and the alert. Running on the same Raspberry Pi, an OpenClaw agent can evaluate the sensor reading against context: how long has the sensor been wet, what is the ambient humidity, has this sensor triggered before and resolved on its own, is there a pattern that suggests condensation versus a pipe failure? The agent decides whether to send an immediate alert, wait and re-check, or activate a shutoff solenoid.

This is the gap in existing Pi leak detection guides. The hardware wiring is well documented. The decision-making is not. Adding an AI agent to the pipeline turns a binary wet/dry sensor into a contextual monitoring system.

The hardware bill stays under $30 beyond the Pi itself. You need three main components for basic detection, plus a fourth if you want automated shutoff.

Water leak sensor module ($3-8): These are simple PCBs with two exposed traces that measure conductivity. When water bridges the traces, resistance drops and the sensor's digital output pin goes LOW (some modules invert this, so check your specific board). Look for modules labeled "water level sensor" or "rain detection module" on electronics suppliers. They ship with three pins: VCC (3.3V or 5V), GND, and a digital signal output. Avoid bare-wire DIY sensors for permanent installations because exposed copper corrodes over time. Conformal-coated PCB sensors last much longer.

Some sensors also provide an analog output for measuring how wet they are, not just whether they are wet. If you want that analog reading, you will need an ADC (analog-to-digital converter) like the ADS1115, since the Pi's GPIO pins only handle digital signals. For most leak detection, the digital output is sufficient: wet or dry.

Wiring the sensor to GPIO: Connect the sensor's VCC to the Pi's 3.3V pin (pin 1), GND to a ground pin (pin 6), and the digital output to a GPIO pin. GPIO 17 (pin 11) is a common choice because it is not reserved for I2C, SPI, or UART. The sensor pulls the pin LOW when water is detected and HIGH when dry (or vice versa, depending on the module). Always check your specific sensor's datasheet before wiring.

Important safety note: Never connect sensors that operate above 3.3V directly to the Pi's GPIO pins. The Pi's GPIO is rated for 3.3V maximum. A 5V signal will damage the processor. If your sensor outputs 5V logic, use a voltage divider (two resistors) or a level shifter between the sensor and the GPIO pin.

Relay module for shutoff automation ($3-5): If you want the agent to close a water shutoff valve when it detects a confirmed leak, add a single-channel 5V relay module. Connect the relay's signal pin to a second GPIO pin (GPIO 27 is a good choice). The relay switches the power circuit for a normally-open solenoid valve installed on your main water supply line. Use an optically isolated relay to protect the Pi from voltage spikes when the solenoid coil de-energizes.

Solenoid shutoff valve ($15-30): A 12V normally-open solenoid valve sits inline with the water supply you want to protect. "Normally open" means water flows freely until the relay energizes the valve to close it. This is the safer default for a shutoff system: if the Pi crashes or loses power, water continues flowing rather than getting stuck off. A 12V/2A power supply powers the valve through the relay.

Multiple sensor zones: For whole-house coverage, run multiple sensors to different GPIO pins: one under the water heater, one near the washing machine, one in the basement. Each sensor gets its own GPIO pin assignment. A 4-channel ADC module lets you read analog values from all four sensors over a single I2C bus if you want analog sensitivity data.

OpenClaw runs on Raspberry Pi 4 or 5 with at least 2GB RAM (4GB recommended). The official installation guide at docs.openclaw.ai covers the full setup: flash 64-bit Raspberry Pi OS Lite, install Node.js, and run the OpenClaw installer. The process takes about 30 minutes.

Pi recommendations for always-on monitoring: Use a USB SSD instead of an SD card. SD cards degrade under continuous write operations, and a leak monitor that runs 24/7 will write sensor logs constantly. An SSD extends the life of your storage . Wired ethernet is more reliable than Wi-Fi for a device that sits in a basement or utility closet where signal strength may be weak.

LLM provider: OpenClaw connects to external LLM providers (Claude, GPT-4, Gemini) for its reasoning capabilities, or you can run a local model through Ollama if you want to eliminate API costs and internet dependency. For a leak monitor, API calls are infrequent (once per sensor trigger, not continuously), so costs are minimal even with cloud providers.

Sensor scripts: OpenClaw agents interact with hardware through system commands rather than touching GPIO registers directly. You need two Python scripts.

A sensor reading script uses the RPi.GPIO library to check the digital state of your sensor pin. It sets the pin as an input with an internal pull-up resistor, reads the state, and prints "wet" or "dry" to stdout. The agent calls this script whenever it needs a reading.

A valve control script takes "open" or "close" as an argument and sets the appropriate GPIO pin HIGH or LOW to control the relay. This script handles the shutoff solenoid. The agent calls it only when it has confirmed a real leak and decided that shutoff is warranted.

Polling versus interrupts: For leak detection, GPIO interrupt-based monitoring is better than polling. Instead of checking the sensor every few seconds in a loop (which wastes CPU cycles), configure the GPIO library to trigger a callback when the pin state changes. The callback runs your sensor script, which then passes the reading to the OpenClaw agent for evaluation. This approach uses almost zero CPU when no leak is present.

Notification channels: OpenClaw supports multiple notification paths. Telegram is the easiest channel to configure for a headless Pi, according to the official setup guide. The agent can also send alerts through email or push notifications to Home Assistant if you run a home automation hub.

Store your sensor logs where agents and humans can find them

Fast.io gives your OpenClaw agents 50GB of free cloud storage with built-in search and AI indexing. Upload sensor data, review it from anywhere, and hand off monitoring dashboards to your team, no credit card required. Built for openclaw raspberry water leak detection sensor agent workflows.

Sign Up Free

This is where OpenClaw's reasoning transforms a binary sensor into a contextual detection system. Instead of "sensor wet, send alert," the agent evaluates multiple signals before deciding what to do.

Inputs the agent evaluates:

• Current sensor state (wet or dry, plus analog moisture level if available)
• Duration of the wet reading (has the sensor been wet for 5 seconds or 5 minutes?)
• Ambient conditions (temperature and humidity, from a BME280 sensor if installed, or from a weather API)
• Historical sensor behavior (does this sensor trigger briefly every morning due to condensation and then clear?)
• Time of day (a wet reading at 2 AM when no one is using water is more concerning than one at 7 PM during dishwashing)
• Which sensor triggered (under the water heater is higher priority than near a basement window where condensation is common)

Reasoning scenarios the agent can handle:

The sensor under the kitchen sink reads wet. The agent checks duration: it has been wet for 3 seconds. Rather than alerting immediately, it waits 30 seconds and re-checks. The reading clears. Likely a splash from the sink. The agent logs the event but sends no notification.

The basement sensor reads wet. The agent checks the pattern: this sensor has triggered briefly on 12 of the last 14 mornings between 5-7 AM, clearing within 10 minutes each time. Current time is 5:45 AM. The agent classifies this as condensation, logs it, and does not alert. But if the reading persists past 8 AM, the pattern is broken and the agent escalates.

The water heater sensor reads wet and stays wet for 2 minutes. The agent checks the time: 2:30 AM, nobody is using water. No condensation history on this sensor. The agent sends an immediate high-priority Telegram alert: "Water detected at water heater sensor, continuous for 2 minutes, no prior pattern. Check immediately." If a shutoff solenoid is installed and the reading persists for 5 minutes, the agent closes the main valve and sends a follow-up: "Shutoff valve closed. Water heater sensor still reading wet after 5 minutes."

Escalation tiers: Not every wet sensor reading needs the same response. Configure the agent with escalation tiers:

• Tier 1 (observation): Sensor wet for under 60 seconds. Log only.
• Tier 2 (advisory): Sensor wet for 1-5 minutes, or a sensor with no condensation history triggers. Send a low-priority notification.
• Tier 3 (urgent): Sensor wet for over 5 minutes, or multiple sensors trigger simultaneously. Send high-priority alert to all configured channels.
• Tier 4 (automatic action): Sensor wet for over 10 minutes with escalating readings, or a high-priority zone triggers. Activate shutoff solenoid and alert.

These thresholds are starting points. Tune them based on your environment. A sensor directly under a pressure relief valve might need a longer Tier 1 window because occasional drips are normal.

Alerting is valuable. Automated shutoff prevents damage while you are asleep, traveling, or did not hear the notification. The combination of both gives you a system that catches leaks faster than commercial options costing $200-500.

Solenoid shutoff wiring: A 12V normally-open solenoid valve sits inline with the water supply line you want to protect. The relay module acts as a switch: when the agent triggers GPIO 27, the relay energizes the solenoid, closing the valve. An inverse parallel diode across the solenoid coil is not optional. When current stops flowing through the coil, the collapsing magnetic field generates a voltage spike that can damage the relay or the Pi's GPIO. A 1N4007 diode across the coil terminals shunts this spike safely. Most relay modules include flyback protection, but verify yours does before relying on it.

Manual override: Always install a manual bypass valve in parallel with the solenoid. If the Pi crashes, the solenoid fails, or you need to restore water during troubleshooting, the bypass valve lets water flow without involving electronics.

Decision logging for review: Every decision the agent makes, whether it alerts, waits, or triggers shutoff, should be logged with full context. A typical log entry includes the sensor ID, reading value, duration, ambient conditions, the agent's reasoning summary, and the action taken.

Structured logs are more useful than free-text entries. JSON lines format works well: one JSON object per line, each timestamped, with fields for sensor_id, reading, duration_seconds, humidity, decision, reasoning, and action. These logs let you review the agent's judgment over time and adjust thresholds.

Storing logs and sensor data on Fast.io: For long-term data retention beyond the Pi's local storage, upload daily log summaries to a Fast.io workspace. Fast.io provides 50GB of free storage with no credit card required, and its MCP server lets agents upload files directly through API calls. This is useful for two reasons: first, if the Pi's SD card or SSD fails, your historical sensor data is preserved in the cloud. Second, if you run multiple leak detection Pis across different locations (a rental property, a vacation home, a parent's house), all the logs land in one searchable workspace.

Fast.io's Intelligence Mode auto-indexes uploaded files, so you can ask questions about your sensor data through the workspace's AI chat: "How many times did the basement sensor trigger last month?" or "Show me all shutoff events across all properties." No separate database or analytics tool needed. The workspace handles the indexing and retrieval.

Other storage options work too. You can push logs to S3, Google Drive, or a local NAS. Fast.io is convenient for multi-site agent deployments because the workspace is designed for agent-to-human handoff: the agent builds the monitoring archive, and you review it through the same interface.

A leak detection system that fails silently is worse than no system at all. Build maintenance checks into the agent's routine so you know the system is working before you need it.

Daily health checks: Have the agent send a daily "system OK" message at a consistent time. If you stop receiving the daily check-in, the Pi may have crashed, lost network, or the agent may have stopped. A missing health check is itself an alert worth investigating.

Sensor testing: Water leak sensors degrade over time, especially in humid environments. Once a month, place a damp cloth on each sensor to verify it still triggers correctly. The agent can automate part of this by running a self-test sequence where it checks GPIO pin responsiveness and confirms the sensor circuit is intact. If a sensor's analog readings drift outside the expected range, the agent flags it for replacement.

False positive tuning: Review the agent's decision log weekly for the first month. Look for patterns: does one sensor trigger every humid morning? Does the agent correctly classify condensation? Adjust the escalation thresholds based on real data from your specific environment. Every home is different. A basement in Houston has different humidity patterns than a crawl space in Denver.

Common issues and fixes:

• Sensor reads wet constantly: Check for corrosion on the sensor traces. Capacitive or conformal-coated sensors resist this better than bare-trace boards. Also check that the VCC voltage matches the sensor's specification, since overvoltage can cause phantom readings.
• No reading from sensor: Verify wiring with a multimeter. Check that the GPIO pin is not configured for an alternate function (I2C, SPI). Try a different GPIO pin to rule out pin damage.
• Relay clicks but valve does not close: The solenoid may need more current than the power supply delivers. Verify the power supply rating against the solenoid's specifications. Check the diode orientation across the coil.
• Agent does not respond to sensor trigger: Confirm the OpenClaw service is running. Check the notification channel configuration. Review the agent's logs for errors in the decision logic.

Scaling to multiple locations: If you manage several properties, each one gets its own Pi with sensors and an OpenClaw agent. Each agent uploads its logs and alerts to a shared Fast.io workspace. You get a single dashboard view of all properties without building custom infrastructure. The free agent tier covers 5 workspaces with 50GB of storage, enough for years of sensor logs across multiple sites.

For dense sensor networks within a single building, consider running PicoClaw on Raspberry Pi Zero units as lightweight sensor nodes that report to a central Pi 5 running the full OpenClaw agent. The central agent handles reasoning and alerting while the sensor nodes handle GPIO reading and data forwarding.