OpenWrt Bypass Router with mihomo: Transparent Proxy Setup and Troubleshooting

Decide What the Bypass Router Should Do

A bypass router is a deployment role, not a special proxy protocol. A common setup adds an OpenWrt device alongside the existing main router and sets selected devices to use it as their default gateway. The main router continues to handle the broadband connection, Wi-Fi, and internet access, while OpenWrt applies rules to traffic routed through it.

mihomo is a proxy core developed from the Clash Meta project. It reads configuration, matches rules, and establishes connections; it is not a complete router management interface. Copying the core onto a device is only one part of deployment. Transparent proxying also requires coordinated routing, DNS, and firewall rules.

Choose a Traffic Interception Method

• Explicit proxy: Enter an HTTP or SOCKS proxy address on each device. This is useful for checking whether a subscription and its nodes work, but only apps that honor the proxy settings will use it.
• Transparent proxy: OpenWrt intercepts or routes device traffic. This can use TProxy or a TUN virtual interface with mihomo; each option has different kernel module and routing requirements.
• Integrated management plugin: A plugin manages the core, configuration, and firewall. This suits users who want a LuCI interface, but check the plugin's support for your OpenWrt version first.

Use one solution to manage transparent interception. Don't let two plugins write competing DNS redirection, policy routing, or firewall rules. If a plugin generates the configuration automatically, don't then edit its temporary runtime files directly.

Plan IP Addresses, the Default Gateway, and DHCP

This example uses one network interface and a single subnet: the main router is 192.168.10.1, OpenWrt is 192.168.10.2, and the test Mac is 192.168.10.50. All use the subnet mask 255.255.255.0. These addresses are examples. Before setup, replace them with your home network's subnet and make sure none are already in use.

Set OpenWrt's Upstream Connection First

1. Connect a LAN port on the main router to the LAN interface on OpenWrt with an Ethernet cable. Check the device's current network configuration to confirm port assignments; don't rely on labels printed on the case.
2. In LuCI, go to Network → Interfaces → LAN → Edit. Set a static IPv4 address and subnet mask, then set the IPv4 gateway to the main router.
3. Configure a working upstream DNS server for OpenWrt itself. It needs to resolve proxy server hostnames and download the core or update subscriptions before the proxy starts.
4. If the main router will continue providing DHCP, go to DHCP Server → General Setup for the corresponding LAN interface in OpenWrt and select Ignore interface. This disables DHCP address assignment on that interface; it does not disable DNS.

DHCP automatically assigns IP addresses, gateways, and DNS settings. Avoid running conflicting address-assignment services on the same broadcast domain. Otherwise, a device might get the main router as its gateway one time and the bypass router the next, causing intermittent connectivity.

Configure the Test Mac

On macOS, go to System Settings → Network → your current network service → Details → TCP/IP. Note the existing settings, then enter the test IP address, subnet mask, and Router address from the table. On the DNS page, enter 192.168.10.2. Make sure the test address is outside the DHCP pool or reserved for the Mac to avoid an IP conflict.

To apply this across the LAN, configure the main router's DHCP server to advertise option 3 (default gateway) and option 6 (DNS server), both pointing to the bypass router. Some home routers don't let you set these options separately; in that case, configuring devices individually is easier to roll back. After changing DHCP settings, renew each device's lease. Existing leases won't all update immediately.

Check CPU Architecture and Available Resources

A router runs a Linux executable, not a macOS app installer. First check the system over SSH, then choose a mihomo release that matches its architecture. Don't assume that a 64-bit-capable processor means the firmware has a 64-bit userspace.

ubus call system board
uname -m
getconf LONG_BIT
free -m
df -h
cat /etc/openwrt_release

Minimal firmware may not include getconf, so use system board information and the firmware target to identify the architecture. Common targets include x86_64 (AMD64) and aarch64 (ARM64). For MIPS devices, check endianness, instruction set, and floating-point ABI too. If you see Exec format error at launch, check the architecture first instead of repeatedly changing the file's permissions.

Separate Sizing Guidelines from Actual Usage

• Memory: Treat 256 MB as a capacity that needs careful evaluation. With 512 MB or more, there's usually more room for rule sets, DNS cache, and concurrent connections. This is a planning guideline, not a fixed minimum requirement for the core.
• Storage: Check the available space in /overlay. The core, rule databases, and old and new files created during updates all use storage, so don't estimate space based on the compressed archive alone.
• CPU: Proxy encryption, rule matching, and large numbers of connections all use CPU resources. A 1,000 Mbps broadband plan doesn't mean the router can deliver that speed through a proxy.

After installation, run mihomo -v to record the installed version. When troubleshooting, also note the firmware version, interception method, and rule set size. Check top and free -m when idle, after loading a subscription, and after 10 minutes of continuous transfer. Watch the process's resident memory and the system's available memory; Linux cache usage isn't automatically a memory leak.

Configure the Core, Transparent Proxy, and DNS Separately

OpenWrt 22.03 and later commonly use firewall4, which generates firewall rules with nftables. Don't paste iptables commands from older guides as if they were universal. With a plugin, check which firewall backend it supports. For a manual setup, confirm that the current firmware has the modules required by TProxy or TUN.

Validate the Configuration Before Redirecting Device Traffic

Store the runtime configuration and resource files in fixed locations. The commands below assume the core is installed at /usr/bin/mihomo and the configuration is at /etc/mihomo/config.yaml; run them only if you're using these paths.

/usr/bin/mihomo -v
/usr/bin/mihomo -t -d /etc/mihomo -f /etc/mihomo/config.yaml

A successful configuration check only confirms that the configuration can be loaded. It doesn't verify subscription updates, node connectivity, or transparent proxy operation. Check the selected proxy groups, final fallback rule, and whether the node server's hostname resolves. Subscription URLs often contain access credentials, so redact the full URL before sharing logs or screenshots.

Know What Each Port Does

If your configuration includes mixed-port: 7890, port 7890 is a mixed HTTP/SOCKS proxy endpoint for apps to connect to explicitly. If it includes tproxy-port: 7893, port 7893 is used by transparent forwarding rules. These are configurable example values, not ports that are guaranteed to exist whenever the core starts. Opening 7890 alone won't automatically route LAN traffic through the proxy.

TUN creates a virtual network interface and requires the right device support, permissions, and routes. Even with automatic routing enabled, check LAN forwarding, firewall zones, and the DNS path; TUN doesn't configure every part of a bypass router for you. TProxy generally relies on traffic marks and policy routing to send intercepted packets to the local proxy.

Create a One-Way DNS Flow

A common DNS path is: a device sends a request to port 53 on the bypass router, dnsmasq receives it, then forwards it to mihomo's local DNS listener, for example 127.0.0.1:1053. Make sure 1053 matches the actual configuration. Don't forward requests from dnsmasq to mihomo and then have mihomo send those same requests back to dnsmasq, creating a loop.

• Using fake-ip: The core returns a mapped address to the device, then uses the mapping to recover the domain name. A common address pool is 198.18.0.0/16; make sure it doesn't overlap with a network or VPN subnet already in use.
• Resolving node hostnames: Keep a working bootstrap DNS path for the proxy servers themselves. Otherwise, you can create a dependency loop where the proxy must connect before it can resolve the proxy server's hostname.
• Check encrypted DNS: Custom DoH settings in a browser may bypass LAN DNS. This can make domain-based rules and fake-ip mappings behave differently than expected. Use a consistent DNS path while testing.

When a bypass router returns a fake IP, the device's connection must continue through the same core that created the mapping. If DNS points to the bypass router but the default gateway remains the main router, the main router usually can't handle those mapped addresses. A common symptom is that domain names resolve but websites won't load.

Handle Single-Interface Routing, IPv6, and Security

A single-interface bypass router has one main LAN interface, so incoming and outgoing traffic may use the same interface. Traffic on the way out can pass through the bypass router while return traffic takes a different path directly from the main router to the device. Whether to apply source NAT on the bypass router depends on connection tracking, firewall behavior, and upstream routing.

Some setups use SNAT or masquerading on forwarded traffic, so the main router sees the bypass router's address as the source and sends return traffic back through it. This can simplify some single-interface topologies, but it hides the individual device addresses from the upstream router. Don't treat enabling masquerading on the LAN zone as a required step for every device.

Check IPv6 Separately After Configuring IPv4

The main router may continue advertising an IPv6 default route to devices through RA (Router Advertisements). Changing only the IPv4 gateway won't control IPv6 traffic. Decide whether your setup will also intercept IPv6 and provide the corresponding DNS and forwarding rules. For comparison, you can temporarily disable IPv6 on the test device, then decide on a permanent dual-stack setup once you've confirmed the results.

Restrict Management Access to Trusted Devices

• Don't forward proxy ports, DNS services, or control interfaces to the public internet.
• If you need to provide a LAN proxy, check allow-lan, the listening address, client authentication, and firewall source restrictions.
• Keep the control API listening only on loopback where possible. If you need a remote dashboard, set a strong secret and limit access to trusted management devices.
• Use OpenWrt's procd service manager or the plugin's built-in service management to keep the core running across sessions and reboots. Don't start it only from an SSH session.

Troubleshoot Connectivity and Routing in Order

Change one thing at a time when troubleshooting. Check IP addressing and routes first, then DNS, then rules and nodes. Changing the subscription, gateway, and firewall all at once makes it hard to identify what caused the problem.

Check the Network Path on the Test Mac

route -n get default
scutil --dns
ping -c 3 192.168.10.2
dig @192.168.10.2 example.com
curl -I --connect-timeout 10 https://example.com

The default IPv4 gateway should be 192.168.10.2 in this example. DNS queries should return a response rather than time out. System DNS output may include separate resolution domains for a VPN, so check which network service is in use. A failed ping to one host doesn't prove the internet is down; check DNS and HTTPS too.

Check Forwarding and Logs on OpenWrt

ip route
ip rule
ip route show table all
logread | tail -n 80
nft list ruleset

These commands inspect the system without flushing existing rules. Check for the expected default route, policies related to traffic marks, and a forwarding path from the LAN to the target processing chain. Rule output may contain LAN addresses and service details; share only the parts needed for troubleshooting.

If small requests work but large transfers stall, check MTU, Path MTU Discovery, and upstream PPPoE encapsulation. Don't force every interface to the same value as a first step. Measure baseline throughput without the proxy, then test through the proxy using the same device and connection type. This helps distinguish kernel performance issues from changes in Wi-Fi signal.

Keep a Rollback Plan Before Expanding Interception

1. Save the initial state. Back up the OpenWrt configuration and record the main router's address, DHCP pool, and the test device's original automatic network settings.
2. Verify basic functionality. Confirm that direct connections, traffic that should use the proxy, and access to LAN printers and NAS devices all follow the expected rules.
3. Test restarts and reconnects. Restart the core and the bypass router separately. Then disconnect and reconnect the Mac and check that it still uses the correct gateway and DNS.
4. Practice taking the bypass router offline. Restore the main router as the test device's gateway and restore its original DNS settings. Confirm that basic internet access returns. With fake-ip, also flush the DNS cache or restart affected apps.
5. Expand gradually. Add a few devices at a time before changing DHCP settings. Keep one device connected directly to the main router's management interface.

A bypass router on the same subnet usually has no automatic failover. If a device still uses an offline bypass router as its default gateway, the main router won't take over just because it's still online. Keep a record of address assignments, the DNS path, service autostart, and rollback steps to make issues easier to track after updating the core or changing subscriptions.

If only one Mac needs a proxy, start with a desktop client to test subscriptions and rules. Move the rules to OpenWrt only if you need to share them with a TV, gaming device, or multiple devices. These options address different traffic interception needs; there's no need to reconfigure your entire home network from the start.