How to Install OpenWrt on Raspberry Pi for an OpenClaw-Managed Network Router

OpenWrt 25.12.0, released in March 2026, supports over 2,200 devices and ships with Linux kernel 6.12.71. The release replaced the legacy opkg package manager with apk (Alpine Package Keeper) and rewrote the Wi-Fi management scripts in ucode. For Raspberry Pi owners, the firmware selector at firmware-selector.openwrt.org offers stable images for the Pi 3B+, Pi 4, and Pi 5, with both EXT4 and SquashFS filesystem variants available.

The practical appeal is straightforward. A Raspberry Pi 4 or 5 with OpenWrt installed becomes a full Linux router with VLANs, firewall zones, WireGuard tunnels, DNS filtering, QoS, and traffic shaping, all managed through the LuCI web interface. Consumer routers hide most of this behind simplified menus or lock it out entirely. OpenWrt exposes the routing stack and lets you install additional packages from a repository of thousands of options.

The Pi's single Ethernet port is the main hardware limitation. A dedicated router typically has at least a WAN port and several LAN ports. On a Pi, you either add a USB-to-Ethernet adapter for a second NIC (common chipsets like the Realtek RTL8153 work well on OpenWrt) or you run the Pi as a one-armed router behind an existing modem, using VLAN tagging to separate WAN and LAN traffic on the same physical interface. Both approaches work. The USB adapter is simpler to configure; the VLAN approach avoids buying extra hardware but requires a managed switch.

Where this gets interesting is the management layer. Most OpenWrt guides end at "your router is working." They do not address what happens six months later when you have 40 firewall rules, three VPN peers, a DNS blocklist you forgot to update, and no record of which change broke your kid's gaming traffic. That gap is where an AI agent fits.

Start by choosing your image. Visit the OpenWrt firmware selector and pick your Pi model. For a Pi 5, the target is bcm27xx/bcm2712. For a Pi 4, it is bcm27xx/bcm2711. Download the factory image (the .img.gz file). You do not need to extract it; flashing tools like Raspberry Pi Imager and balenaEtcher handle the compressed image directly. The download is small, usually around 14 MB.

Before flashing, update the bootloader EEPROM on your Pi if it is running Raspberry Pi OS. Boot the Pi into its current OS, run sudo rpi-eeprom-update -a, and reboot. This prevents boot failures caused by an outdated EEPROM that does not recognize the OpenWrt partition layout.

Flash the image to your SD card (or USB SSD for better longevity) and boot the Pi. OpenWrt starts with a default LAN IP of 192.168.1.1, the username root, and a blank password. Connect a keyboard and monitor, or plug the Pi's Ethernet port into your laptop directly and SSH in:

ssh root@192.168.1.1

If your existing network already uses the 192.168.1.x range, change the Pi's LAN IP immediately to avoid conflicts:

uci set network.lan.ipaddr=192.168.50.1
uci commit
/etc/init.d/network restart

Set a root password right away through the LuCI web interface at http://192.168.50.1 under System > Administration. Then configure DNS under Network > Interfaces by adding a public DNS server (like 8.8.8.8 or 1.1.1.1) in the Advanced Settings of the LAN interface. Without this, the Pi cannot resolve package repository hostnames.

For Wi-Fi, navigate to Network > Wireless in LuCI. The Pi's onboard wireless (Cypress CYW43455 on Pi 4 and 5) supports 802.11ac on both 2.4 GHz and 5 GHz bands. Click "Add" next to the radio, configure your SSID and encryption (WPA2/WPA3), and assign it to the LAN zone. Save and apply.

If you are using a USB Ethernet adapter for a WAN port, plug it in before booting. OpenWrt should detect it as a second interface (typically eth1). Create a new WAN interface under Network > Interfaces, assign it to the adapter, set the protocol to DHCP client, and assign it to the WAN firewall zone. Your Pi is now a two-port router.

A running OpenWrt router is stable. The problem is not uptime; it is operational drift. Firewall rules accumulate. DNS blocklists go stale. Someone adds a port forward for a temporary test and never removes it. Three months later, nobody remembers which rules are load-bearing and which are leftovers.

An OpenClaw agent sitting alongside the router (not on it, since the Pi's resources should stay dedicated to routing) addresses this by treating the router's configuration as a managed artifact. The agent reads the current state through SSH or the LuCI JSON-RPC API, compares it against a declared desired state stored in a workspace, and flags or applies changes.

Practical things the agent can handle:

• Firewall rule audits. The agent pulls the current iptables or nftables ruleset, compares it against a baseline stored in the workspace, and reports additions, deletions, or modifications. Every change gets logged with a timestamp and reason.
• DNS blocklist updates. If you run adblock or DNS-based filtering on OpenWrt, the agent can check upstream blocklist sources on a schedule and trigger an update when a new version is available.
• Traffic baseline reports. Pull interface counters, connection tracking stats, and bandwidth usage from the router, then write a daily or weekly summary into the workspace where you or your team can review trends.
• Config backup and versioning. Export the full UCI configuration on a schedule and store each snapshot in the workspace. Every version is retained and timestamped, so rolling back to a known-good state is a file restore, not a memory exercise.

Because the OpenClaw integration path evolves as the project adds new skills and MCP tools, verify the exact skill invocations against the current OpenClaw docs when you implement this. The pattern itself is stable: the agent authenticates to the router, reads state, compares against a source of truth, and writes artifacts to a shared workspace.

Store your router configs and audit logs where your agent and your team can both reach them

Free 50 GB workspace with built-in versioning, search, and AI chat over files. Drop in your OpenWrt backups, drift reports, and firewall baselines. No credit card, no trial expiration.

Sign Up Free

OpenClaw's hardware requirements are modest: 1 GB RAM minimum (2 GB recommended), one CPU core, 500 MB of free disk, and a 64-bit OS. A Raspberry Pi 4 with 2 GB or more handles it comfortably. A Pi 5 gives you headroom for larger context windows and faster skill execution.

Keep the agent on a separate device from the router. Running OpenClaw on the same Pi as OpenWrt creates resource contention (the agent's Node.js process competes with the routing stack for CPU and memory) and creates a single point of failure. If the agent crashes and takes the Pi with it, your network goes down.

The installation flow on the agent Pi, running Raspberry Pi OS Lite (64-bit):

1. Flash Raspberry Pi OS Lite and enable SSH through the Imager's advanced options.
2. Install Node.js 24 from the NodeSource repository.
3. Create a 2 GB swap file for low-RAM models to prevent out-of-memory kills during skill execution.
4. Run the OpenClaw installer: curl -fsSL https://openclaw.ai/install.sh | bash
5. Complete the onboarding wizard. For a headless Pi, use API key authentication rather than OAuth.
6. Configure a cloud model provider. The Pi acts as a gateway, sending inference requests to Claude, GPT-4, or another hosted model. It does not run models locally.

For performance, use a USB SSD instead of an SD card. SD cards wear out under the write patterns that agent logs and workspace syncs produce. Disable Bluetooth and reduce GPU memory allocation to 16 MB in /boot/config.txt to free resources for the agent process.

Once OpenClaw is running, verify with openclaw status and access the dashboard through an SSH tunnel: ssh -L 3000:localhost:3000 pi@agent-pi-ip. The agent is ready to connect to your OpenWrt router.

The agent needs a place to read its instructions from and write its outputs to that a human operator can also access, search, and hand off to the next person on call. This is where the approach diverges from a cron job that writes logs to /var/log and hopes someone reads them.

A Fast.io workspace serves as that shared layer. Create a workspace for the router project and enable Intelligence Mode so everything in it becomes searchable and queryable through AI chat. The structure might look like this:

• baseline/ holds the declared desired state: firewall rules, DNS settings, interface configs, each as a separate file.
• snapshots/ receives timestamped UCI config exports from the agent's scheduled runs.
• reports/ holds drift reports, traffic summaries, and blocklist update logs.
• runbooks/ stores the operational procedures for common tasks, like adding a new VLAN or rotating VPN keys.

Three features earn their keep in this setup. Granular permissions let you share the reports/ folder read-only with a client or a junior admin while keeping baseline/ writable only by the agent and senior engineers. File versioning means every config snapshot is retained with its full history, not just the latest one. And ownership transfer lets the agent build the entire workspace during initial deployment and hand it to the team that will operate the network, while retaining admin access for future runs.

The free agent plan at fast.io/pricing gives you 50 GB of storage and 5,000 credits per month with no credit card required. For a router management workspace holding config files and text reports, that is far more capacity than you will use. The Fast.io MCP server at /mcp exposes workspace operations (file read/write, search, versioning) as tool calls the agent can invoke directly, so the integration is API-native rather than bolted on through file sync scripts.

Local alternatives work too. A git repository on the agent Pi can version configs, and an S3 bucket can hold snapshots. The tradeoff is that you lose the built-in search, chat-over-files, and human-readable audit trail, and you end up stitching together three or four services to match what a single workspace provides.

The router is routing and the agent is auditing. Now make the setup boring and reliable.

Lock down SSH. Disable password authentication on the OpenWrt router and use key-based auth only. The agent Pi should have its own SSH keypair stored in a location only the agent's service account can read. Add the public key to the router's /etc/dropbear/authorized_keys and disable root password login in LuCI under System > Administration.

Separate the management network. If possible, put the agent Pi and the router's management interface on a dedicated VLAN that client devices cannot reach. This limits the blast radius if a client device is compromised. OpenWrt makes VLAN configuration straightforward under Network > Interfaces > Devices.

Monitor the agent, not just the router. Run a lightweight health check (a cron job that curls the agent's local dashboard and logs the HTTP status) from a third device or an external monitoring service. If the agent stops running, you want to know before the next config drift goes undetected.

Plan for SD card failure. If either Pi runs from an SD card, keep a prepared spare with the same image and config. For the router, export the OpenWrt config backup from LuCI (System > Backup) and store it in the workspace. For the agent Pi, the OpenClaw installer is idempotent, so re-running it on a fresh card gets you back to a working state, but your local skill configurations and API keys need to be backed up separately.

Update in stages. When OpenWrt releases a new stable version, test the upgrade on a second SD card before swapping it into the production router. The attended sysupgrade tool (included by default in 25.12) builds a custom image that preserves your installed packages and configuration, but test it anyway. Run the agent's audit immediately after an upgrade to catch any config changes the upgrade introduced.

Review the agent's output. An agent that writes reports nobody reads is a waste of electricity. Set a weekly calendar reminder to open the workspace, scan the drift reports, and either resolve the flagged items or update the baseline to reflect intentional changes. The Intelligence Mode chat makes this faster: ask "what changed in the firewall this week?" and get a cited summary instead of reading raw diffs.