OpenClash installation and configuration

For OpenWrt / LuCI. The download center links to upstream installation guidance. Upstream releases provide .ipk / .apk packages but do not guarantee the oixCloud account integration described below. Confirm that your installed maintained build includes that entry before following the account workflow. Changing only the core cannot add the account tab to a generic build.

Firmware and dependency requirements

↔ Swipe left or right to see all columns

Item	Selection
Firmware	OpenWrt / LuCI with feeds supplying the required kernel modules and dependencies; the router model alone is insufficient.
Package manager	.ipk for opkg, .apk for apk. The LuCI plugin package is marked all; the proxy core still needs the correct CPU architecture.
Firewall	Match dependencies to Firewall4 / nftables or Firewall3 / iptables; see the maintained repository's installation instructions.
Storage and memory	Reserve space for the plugin, core, configurations and runtime cache. Resolve firmware/feed mismatches if matching kernel modules are unavailable.

1. Install or update the plugin

1. Existing users should back up under Services → OpenClash → Plugin Settings → Version Update first. Backups can contain credentials and subscription URLs.
2. Download the matching package from the relevant release page or the provider of your maintained build: .ipk for opkg firmware or .apk for apk firmware. Upload through System → Software.
3. Select dependencies for both the package manager and firewall: Firewall4/nftables and Firewall3/iptables require different combinations. Use the corresponding release instructions.
4. Check the CPU build architecture on the update page. To update the plugin, wait for download-address checks, select an available Plugin version and wait for the log to finish before refreshing.

The LuCI plugin and proxy core update separately. Updating only the core cannot add a new web menu. For installation failures, inspect the package error, free storage and firmware dependencies.

2. Sign in to oixCloud

Open Services → OpenClash → Plugin Settings → oixCloud. First use email/password to create the dedicated OpenClash token. You can then use Token Login with that Access Token itself, not a subscription URL. See first sign-in for obtaining an oixCloud password after Google registration and restricting client password sign-in.

Wait for account information, profile download and core processing. The plugin creates or updates the oixCloud - smart subscription. Visible plan and traffic data proves account retrieval, not that the correct profile is active.

3. Select the profile and start

Interface simulation based on the maintained version · Fictional data · Click to enlarge

1. Find oixCloud - smart.yaml in the profile area on Overview / Running Status.
2. Select it and use Switch if another profile is active. Wait for any resulting restart; enable the start switch if it is still stopped.
3. Inspect logs for successful configuration loading and core startup. The core version should include oix.
4. Begin with the generated profile and Rule mode, then select an available node or group in the dashboard.

While signed in, the integrated build prioritizes the dedicated core; the separate Smart Core switch is not required. Do not pass the dedicated subscription through a third-party converter, which can discard required settings.

Common-port capture scope

The maintained build enables common-port proxying by default: listed destination ports use the proxy, while others go direct. Check the router's actual settings for existing installations. If a game, call or self-hosted service uses uncommon ports, review Plugin Settings → Traffic Control → Common Ports Proxy Mode, adjust, restart and verify.

UDP forwarding remains subject to the port range. Port filtering does not identify all BT/P2P traffic and does not authorize BT/P2P downloads or account sharing.

4. Verify from a LAN device

1. Check the device's gateway, DNS and OpenClash access controls for your main-router or secondary-router setup.
2. Visit both a direct destination and a destination requiring a proxy.
3. Check the target, matched rule and outbound in the dashboard's connection records.

An account card, latency result or Running status alone does not prove that device traffic is captured. Browser secure DNS, other DNS plugins, IPv6 and secondary-router gateways can change the path.

5. Updates and node filters

• Update the profile from Overview or configure an automatic schedule under Config Subscribe; verify the selected profile and nodes afterwards.
• Open Node Filter on the oixCloud tab to edit on the website. Restart OpenClash after saving to fetch immediately, or wait for the core's next subscription update. OpenClash devices on the same account share the filter; see Subscriptions and filters.
• Back up before plugin/core upgrades, and use the matching update control. A plugin upgrade and a subscription refresh are separate operations.

6. Replace or update the oix core

Interface simulation based on the maintained version · Fictional data · Click to enlarge

The oix core is a Mihomo build supporting oixCloud managed nodes; an ordinary Mihomo package is not a substitute. The maintained integration prioritizes it after sign-in. Plugin, core and subscription updates are separate operations.

Online core update

1. Open Services → OpenClash → Plugin Settings → Version Update. Export a backup including the core and save it to your computer first.
2. Check the CPU build architecture, such as linux-arm64, linux-amd64-v1 or linux-armv7.
3. Click the version link in the Core column and wait for the log to confirm download, validation and replacement using the matching dedicated package.
4. Return to Overview / Running Status, start OpenClash if needed, check that the version contains oix, and verify a connection from a LAN device.

The usual installation path is /etc/openclash/core/clash_meta; small-flash mode uses /tmp/etc/openclash/core/clash_meta. The updater selects the path for the active mode and sets executable permissions.

Manual core replacement via SSH

If online updates fail, download a .gz file matching the CPU build architecture from the mihomo-oix Pre-Alpha release. Do not use an ordinary Mihomo build, a different CPU architecture or a desktop installer.

Back up and check space before replacing

Export a backup including the old core, and record the architecture and installation path. File size varies by version and architecture; use the actual extracted size. Run df -h to check temporary and destination storage. These commands assume ordinary mode and router address 192.168.1.1. Use your actual address; in small-flash mode, replace the destination with /tmp/etc/openclash/core/clash_meta.

1. Extract on your computer, replacing the placeholder with the actual downloaded filename:

   gzip -dc 'mihomo-<arch>-<version>.gz' > clash_meta

2. Stop OpenClash in LuCI's Running Status page, then upload the new file to a temporary location:

   scp clash_meta root@192.168.1.1:/tmp/clash_meta.new

3. Sign in to the router over SSH and confirm the new file runs and its version contains oix:

   chmod 755 /tmp/clash_meta.new
   /tmp/clash_meta.new -v

   If it fails, check architecture, file integrity and the exact error before replacing anything.
4. Confirm the destination path, copy the file and set permissions as the plugin does:

   cp /tmp/clash_meta.new /etc/openclash/core/clash_meta
   chmod 4755 /etc/openclash/core/clash_meta
   /etc/openclash/core/clash_meta -v

5. Start OpenClash from the web interface, inspect logs and test from a LAN device. If it fails, stop it, extract the old core from your backup and restore it with the same upload and validation steps. Repeated subscription updates do not fix a core that cannot start.

After successful verification, remove the uploaded /tmp/clash_meta.new if desired. Keep the computer-side backup for recovery.

Troubleshooting

↔ Swipe left or right to see all columns

Symptom	Next step
No oixCloud tab	Confirm that the maintained build includes account integration; a generic upstream package or a core-only update does not guarantee the tab.
Core download/start fails	Read the current log, then check CPU architecture, time, space and dependencies. The dedicated core has its own download source; GitHub reachability alone is inconclusive.
Signed in but no profile	Check and update oixCloud - smart under Config Subscribe, then explicitly switch to it.
Router running but device fails	Check device gateway, DNS, access controls and IPv6, then inspect connections.

Before reporting, generate debug logs from Running Log → Generate Log and include plugin/core versions, mode and reproduction time, with credentials removed. References: maintained OpenClash integration and OpenClash upstream installation guide.