Break “update subscription” into five checkpoints
An OpenClash subscription update is more than downloading a file to the router. The official update implementation reads subscription entries, performs the request, tests the configuration, validates YAML content, checks for expected proxy data, and creates or writes the target configuration. Success at an early stage does not guarantee that the result can be selected and loaded by the core.
| Stage | Success proves only | Check on failure |
|---|---|---|
| URL request | The router received an HTTP response | DNS, TLS, status code, and redirects |
| Content recognition | The response resembles configuration content | Login HTML, error text, or an empty body |
| YAML/core validation | Syntax and required structures can be parsed | Error line, indentation, and incompatible fields |
| File write | The processed result reached storage | Free space, permissions, filesystem, and filename |
| Selection and load | The running core actually adopted the new profile | Active path, startup log, and port conflicts |
Read the log from top to bottom and locate the first failed checkpoint. Later messages are often consequences. Changing DNS, conversion service, template, core, and subscription at once can make the red banner disappear without showing which dependency was repaired.
The filename timestamp and size are useful evidence but not final proof. A server can return a full HTML login page, and that response can still have a recent timestamp and nonzero size. Validation and core loading remain separate checks.
Protect the working configuration and subscription secret first
A router-side networking change can remove the same connection needed to troubleshoot it. Back up the currently loadable YAML, OpenClash UCI settings, and related custom files before updating, and record the active configuration name. Store the backup somewhere trusted and independent of the router, but never in a public repository or group chat. A subscription URL often contains a bearer-like token.
- Synchronize time: a substantially wrong clock can break HTTPS certificate validation. Confirm that NTP has completed.
- Check free space: configuration, rule-provider, and temporary files need storage. A successful download does not rule out a later write failure.
- Prove router DNS and WAN: the router itself must resolve the subscription host and establish HTTPS without relying on the profile currently being replaced.
- Protect the URL: redact query parameters from screenshots and logs, and do not paste the link into a public online “parser.”
Do not delete the only working profile before diagnosis. It proves the plugin and core can still operate and preserves a network path for consulting official documentation. Keep it until the replacement passes a core reload and a real traffic test.
If the subscription provider offers a regenerated token, use that only when there is evidence the existing token expired or leaked. Regenerating it as a generic first step can invalidate other devices and obscures the original error.
Run one observable manual update
Temporarily pause scheduled updates and choose one subscription for the test. In the subscription configuration, review whether it is enabled, its configuration name, address, User-Agent, and whether conversion is enabled. Record the original values. Do not rotate through several converter URLs or custom templates in the hope that one succeeds; each adds a different path and response format.
- Clear the current log view or mark a starting point, and record the time at which you will press Update.
- Start one update for one subscription. Wait for the backend sequence to finish without repeatedly clicking or reloading the page.
- Read from the marked point and find messages for download, configuration test, format validation, missing proxy fields, and file creation or writing.
- If the update reports success, compare the target file timestamp and size and confirm that OpenClash's active configuration path identifies that file.
- Reload or restart the core, capture the first parsing error if present, and make one connection to verify actual traffic.
The official script contains distinct branches for testing a downloaded configuration, YAML format validation, and a result with no proxy field. It can also retry without an agent in some failure paths. This confirms why completion of the browser request or the disappearance of a spinner does not prove that all backend checks passed.
Do not judge an update only by the number of nodes in the dashboard. A provider may legitimately change that count. Compare an intentional marker such as the provider's update time, a known group name, or a changed rule, while also confirming that the new profile passes the core test.
Map the first log message to the layer that failed
| Message or symptom | Likely stage | Next check |
|---|---|---|
| DNS, connect, or TLS error | No usable subscription response yet | Router DNS, clock, WAN path, and target host reachability |
| HTTP response, then format validation failed | HTML, empty text, or incompatible YAML may have arrived | Response type, expiry, and User-Agent expectations |
| Has No Proxy Field | The content lacks the proxy structure expected by the script | Whether the provider returned an OpenClash/Mihomo-compatible profile |
| Write file failed | Processed content could not reach the target file | Space, filesystem health, permissions, and filename |
| Old nodes remain after update | A new file may exist but is not selected or loaded | Active configuration path and core startup log |
Enabling subscription conversion adds another external dependency. The original subscription can be healthy while the converter is unavailable, its template cannot be fetched, or its parameters no longer match. After preserving the original settings, compare with a direct Mihomo/Clash YAML supplied by the provider when available. This isolates the conversion layer without sending the secret URL to a new, unknown service.
Inspect a suspicious response without publishing it. An HTML title, an account-expired message, or a tiny error document explains why YAML validation fails. Do not paste the full content into an issue: both URLs and node records may contain credentials.
Before sharing any OpenClash log, search it for the subscription hostname, query parameters, converter URL, proxy server addresses, and local public IP information. Replace secrets with stable labels so maintainers can still follow the sequence.
Restore manual updates before re-enabling the schedule
A complete repair has several observable results: one subscription passes download and validation; the new file is written safely; the active configuration path selects it; the core reloads without a parsing error; and one meaningful node or rule change appears in live behavior. A toast from the page alone does not establish the chain.
Official issue #5239 reports a specific case in which an update button could fail to present the backend result clearly. It supports checking the backend log instead of trusting immediate interface feedback, but it does not prove that every update failure is that same UI defect. Compare the exact OpenClash version, response, and log from the affected router.
- Keep both the verified old profile and the repaired new profile until the next scheduled run has been observed.
- Repeat the manual update once to rule out a one-time DNS cache or converter response.
- Set a reasonable automatic-update interval that does not overlap a router reboot or WAN redial window.
- After the next scheduled event, compare log time, file time, active path, and core status to close the automation test.
If the same stage fails consistently, report it to OpenClash with the plugin version, OpenWrt build and architecture, reproduction time, a minimal redacted log, and whether conversion is enabled. State the first failure, not merely “the update button does nothing.” This gives maintainers evidence they can compare with the current implementation.
Official sources and version scope
- github.com/vernesong/OpenClash
- github.com/vernesong/OpenClash/blob/master/luci-app-openclash/root/usr/share/openclash/openclash.sh
- github.com/vernesong/OpenClash/blob/master/luci-app-openclash/luasrc/view/openclash/update_config.htm
- github.com/vernesong/OpenClash/issues/5239
Version numbers, filenames, and interface labels can change. Confirm them in the linked project documentation before making changes.