How to Build an Air Quality and CO2 Monitoring Agent with OpenClaw on Raspberry Pi

CO2 levels above 1,000 ppm impair cognitive function. A 2015 Harvard study measured a 15% decline in cognitive ability scores at 950 ppm and a 50% decline at 1,400 ppm. PM2.5 exposure is responsible for an estimated 4.2 million premature deaths annually worldwide, according to the WHO. These are not exotic industrial hazards. They are everyday indoor air conditions in offices, classrooms, and homes with poor ventilation.

The standard Raspberry Pi air quality project reads a sensor, logs the value to InfluxDB or a CSV, and displays it on a Grafana chart. That tells you what the air quality was. It does not tell you what to do about it, whether conditions are getting worse, or how today's pattern compares to last week. You check the dashboard when you remember, which is usually after you already have a headache.

An OpenClaw agent running on the same Pi changes the role of the hardware from passive logger to active monitor. Instead of just recording that CO2 hit 1,200 ppm, the agent can recognize that CO2 has been climbing for 45 minutes, cross-reference humidity and VOC readings to assess whether the problem is occupancy or off-gassing, and decide whether to send an alert, activate a fan relay, or both. The sensor hardware stays the same. The intelligence layer is what changes.

This guide covers the full build: selecting and wiring sensors for CO2, particulate matter, and volatile organic compounds, configuring the OpenClaw agent to poll and interpret readings, and setting up automated responses and historical logging.

Air quality monitoring involves three main pollutant categories, each requiring different sensor technology. You do not need all three to start, but a complete station covers CO2, particulate matter (PM2.5/PM10), and volatile organic compounds (VOCs).

CO2 sensors

The Sensirion SCD41 is the strongest choice for Raspberry Pi projects. It uses photoacoustic sensing to measure CO2 between 400 and 5,000 ppm with accuracy of plus or minus 40 ppm plus 5% of the reading. It communicates over I2C, runs on 3.3V, and also provides temperature and humidity readings. At around $40-50 for a breakout board (available from Adafruit, SparkFun, and Pimoroni), it is more expensive than the MH-Z19B ($15-20) but smaller and lower-power.

The MH-Z19B uses NDIR (non-dispersive infrared) sensing and communicates via UART serial at 9600 baud. It is cheaper but bulkier, draws more current, and requires a 5V supply. It works well for stationary indoor monitors where size and power are not constraints.

The SCD30 offers the best raw accuracy (plus or minus 30 ppm plus 3% of reading) but has documented I2C clock-stretching issues with Raspberry Pi hardware. If you choose the SCD30, you may need to lower the I2C bus speed or use a software I2C implementation.

PM2.5 sensors

The Plantower PMS5003 is the standard choice for Pi-based particulate matter monitoring. It uses laser scattering to measure PM1.0, PM2.5, and PM10 concentrations simultaneously. It connects via UART serial and costs $15-25 for a module with cable. The SEN55 from Sensirion combines PM measurement with VOC, NOx, temperature, and humidity sensing in one module, but costs $35-50.

VOC sensors

The BME680 from Bosch measures temperature, humidity, pressure, and gas resistance (which correlates with VOC levels). It communicates over I2C and costs $10-15 for a breakout board. The gas resistance reading is not a calibrated VOC concentration in ppb. It is a relative index that trends upward as air quality improves. The SGP40 from Sensirion provides a more standardized VOC Index output over I2C for a similar price.

Recommended starter configuration: SCD41 (CO2/temperature/humidity) plus PMS5003 (particulate matter) gives you the two most health-relevant measurements for under $70 in sensors. Add a BME680 or SGP40 later for VOC tracking.

The SCD41 and BME680 both use I2C, so they share the same two data lines on the Pi. The PMS5003 uses UART serial, which connects to different pins.

I2C connections (shared bus)

Both I2C sensors connect in parallel to the same pins:

• SDA to GPIO 2 (pin 3)
• SCL to GPIO 3 (pin 5)
• VIN to 3.3V (pin 1)
• GND to any ground pin (pin 6 or pin 9)

The SCD41 uses I2C address 0x62 and the BME680 uses 0x76 (or 0x77 if the SDO pin is pulled high), so they coexist on the same bus without conflicts. After wiring, verify both devices appear by running i2cdetect -y 1 from the terminal. You should see entries at the expected addresses.

UART connections (PMS5003)

The PMS5003 connects to the Pi's hardware UART:

• TX (sensor) to GPIO 15 / RXD (pin 10)
• VCC to 5V (pin 2 or pin 4)
• GND to ground (pin 14)

Enable the UART interface through raspi-config under Interface Options. Disable the serial console (which uses the same pins) but keep the serial port hardware enabled.

Relay for ventilation control (optional)

If you want the agent to control a fan or ventilation system, add a relay module. Connect the signal pin to GPIO 17 (pin 11), VCC to 5V, and GND to ground. Use an optically isolated relay to protect the Pi's GPIO from back-EMF when switching inductive loads like fan motors.

Software dependencies

Install the Adafruit Blinka library and sensor-specific CircuitPython libraries. Blinka provides a CircuitPython compatibility layer so sensor libraries written for microcontrollers work directly on the Pi's Linux GPIO. For the PMS5003, the pms5003 Python library from Pimoroni handles the serial protocol and frame parsing.

Testing each sensor independently

Before involving OpenClaw, verify each sensor returns valid readings with a short Python test script. The SCD41 needs about 5 seconds after power-on before its first reading is available. The PMS5003 needs about 30 seconds of warm-up time for stable particulate readings. The BME680's gas sensor needs several minutes of burn-in before its resistance readings stabilize.

Store Your Air Quality Data Where Any Agent Can Search It

Upload sensor logs and agent decisions to a Fastio workspace. Intelligence Mode indexes everything for natural language queries across months of air quality data. generous storage, no credit card required. Built for openclaw raspberry air quality co2 monitoring agent workflows.

Start 14-Day Trial

OpenClaw runs on Raspberry Pi 5 (8GB recommended) or Pi 4 (4GB minimum). The official installer handles dependencies and service configuration. Once installed, the agent needs three things: sensor polling scripts it can call as tools, a decision framework, and output channels for alerts and logging.

Sensor polling

Create Python scripts that each return a structured reading. A read_co2.py script initializes the SCD41 over I2C, triggers a measurement, and outputs CO2 in ppm, temperature in Celsius, and relative humidity as a JSON object. A read_pm.py script reads the PMS5003 over serial and returns PM1.0, PM2.5, and PM10 values in micrograms per cubic meter. A read_voc.py script queries the BME680 and returns gas resistance, temperature, humidity, and pressure.

The agent calls these scripts as system commands and receives structured data it can reason about. Polling frequency depends on the use case. For occupied spaces, every 60 seconds is reasonable. For energy-conscious setups, every 5 minutes catches trends without burning API credits on routine readings.

Decision framework

The agent's value is context-aware reasoning that a simple threshold script cannot provide. Rather than triggering an alert whenever CO2 crosses 1,000 ppm, the agent can consider:

• Is CO2 rising or falling? A reading of 1,050 ppm that is dropping after a window was opened needs no intervention.
• How fast is the rate of change? A jump from 600 to 900 ppm in 10 minutes suggests a sudden occupancy increase and predicts the level will exceed 1,000 ppm within minutes.
• Do the readings correlate? High CO2 with normal VOCs suggests occupancy. High VOCs with stable CO2 suggests off-gassing from materials or cleaning products.
• What is the historical baseline? A reading of 800 ppm at 3 AM is unusual if the space is normally unoccupied overnight and might indicate a ventilation system failure.

This contextual reasoning is where the LLM backend earns its keep. OpenClaw supports cloud APIs (Claude, GPT-4, Gemini) for stronger reasoning or local models through Ollama for privacy and zero API costs. For air quality monitoring, cloud APIs are practical since the polling interval means only a few dozen API calls per hour at most.

Alert outputs

The agent can trigger multiple response types: send a push notification through a webhook (Telegram, Slack, Pushover), toggle a GPIO relay to activate a fan, log the event with reasoning to a local file or remote workspace, and adjust polling frequency (increase during degrading conditions, decrease when stable).

Raw sensor readings become far more useful when they are searchable and queryable over time. Local logging to SQLite or CSV works, but creates data silos that only someone with SSH access to the Pi can query. For a monitoring system that multiple people need to review, or that an agent needs to analyze historically, centralized storage with search capabilities is more practical.

You have several options. InfluxDB with Grafana is the standard open-source time-series stack for IoT data. It handles high-frequency numeric writes well and Grafana provides polished dashboards. The downside is running another service (or paying for InfluxDB Cloud) and the limitation that queries are numeric. You can ask "what was the average CO2 between 2 PM and 4 PM" but not "why did the agent activate the fan on Tuesday."

AWS S3 or Google Cloud Storage work for archival, but neither indexes content for search without additional services.

Fastio workspaces offer a middle ground. Upload sensor logs and agent decision reports to a shared workspace, and Intelligence Mode auto-indexes the content for semantic search. You can ask natural language questions about your air quality data, like "show me all the times CO2 exceeded 1,000 ppm last month" or "what triggered the ventilation fan on March 15." The Fastio MCP server gives OpenClaw agents direct workspace access for uploads and queries. The Business Trial includes 50GB storage and included credits with no credit card required, which is enough for months of continuous sensor logging.

The practical workflow: the OpenClaw agent writes a structured JSON log entry after each decision cycle (timestamp, sensor readings, assessment, actions taken, reasoning). Every hour or at the end of each day, a script uploads the accumulated log to a Fastio workspace. Anyone on the team can then search or chat with the data through the web interface, and other agents can query the workspace through the MCP server for cross-site analysis if you run multiple monitoring stations.

This also supports the ownership transfer pattern. If you are building air quality monitoring for a client, school, or office, you can set up the workspace, configure the agent, and then transfer ownership to the building manager. They get the workspace with all historical data and ongoing uploads. You keep admin access for maintenance.

Sensor placement matters more than sensor quality. A $50 SCD41 mounted next to a window that is frequently opened will give worse data than a $15 MH-Z19B mounted at desk height in the center of the room. Place CO2 sensors at breathing height (1-1.5 meters), away from windows, doors, HVAC vents, and direct sunlight. PM2.5 sensors should not be placed near cooking areas unless kitchen air quality is specifically what you are monitoring.

Calibration and drift. The SCD41 supports automatic self-calibration (ASC), which assumes the sensor sees fresh outdoor air (approximately 420 ppm) at least once per week. If the sensor is in a continuously occupied space that never drops to outdoor levels, disable ASC and perform manual calibration with a known reference. The PMS5003 does not require calibration but degrades over time as laser power drops. Plan to replace PM sensors every 2-3 years.

Power and reliability. For always-on monitoring, use an M.2 SSD on a Pi 5 instead of an SD card. Continuous write operations from sensor logging can wear out SD cards within months. A UPS HAT (battery backup board) keeps the Pi running during brief power outages and provides clean shutdown on extended outages, preventing database corruption.

Network dependency. If you use a cloud LLM provider, internet outages mean the agent cannot reason about readings. Build in a fallback: a simple threshold-based Python script that runs independently and activates the ventilation relay if CO2 exceeds 1,500 ppm or PM2.5 exceeds 35 micrograms per cubic meter, regardless of whether the agent is operational. This ensures safety even when the smart layer is offline.

Multi-room deployment. For monitoring multiple rooms, you have two approaches. Run a separate Pi with sensors in each room and a central Pi running OpenClaw that aggregates data from all nodes. Or use cheaper sensor nodes (Pi Zero 2 W or ESP32 boards) that publish readings over MQTT, with a single Pi 5 running OpenClaw subscribing to all topics and reasoning about the building as a whole. The second approach is more cost-effective but requires MQTT infrastructure (Mosquitto runs fine on the same Pi 5).

What this approach does not replace. An OpenClaw air quality agent is a monitoring and automation tool, not a certified safety system. For environments with CO or combustible gas hazards (kitchens, garages, boiler rooms), install dedicated UL/EN-listed detectors with built-in alarms. Those devices are designed, tested, and certified for life safety. A Pi sensor project is not.