What the Clash Verge Rev external controller does on Windows
The Clash Verge Rev external controller is a local HTTP API that lets another interface inspect and operate the running Clash or Mihomo core. It is not the same thing as the Windows system proxy, the mixed port, or a subscription URL. The system proxy decides which Windows applications send traffic through Clash; the mixed port accepts that proxied traffic; the external controller exposes management functions such as current connections, proxy groups, rules, profiles, traffic statistics, and logs. Keeping these roles separate is the first step toward entering the right values.
On a normal Windows installation, the controller should listen on a local address such as 127.0.0.1 and a dedicated API port such as 9090. A dashboard then connects to an address like http://127.0.0.1:9090 and sends the configured secret in its requests. The dashboard does not become a proxy server, and changing the controller port does not automatically change the port used by browsers or games. If a Web dashboard cannot connect, changing the mixed port at random usually makes the diagnosis harder rather than fixing it.
This guide assumes that Clash Verge Rev is already installed, a profile has been imported, and a compatible core can start successfully. The exact menu names may differ slightly between releases because Verge Rev can bundle different Mihomo builds and update its interface over time. Look for wording such as External Controller, External Controller API, API Port, Controller, or Secret. The concepts remain the same even when a setting moves from a general page to a core or profile settings panel.
Prepare Windows and choose safe controller values
Before opening Clash Verge Rev, close other Clash-family clients, old tray utilities, and development dashboards that may already use the same API port. Running two clients at once can produce a misleading result: one application displays a valid profile while the other owns port 9090, or the dashboard reaches an old core instead of the core you are trying to configure. If you use a corporate VPN, security agent, or local traffic inspection product, note its status as well; these tools can alter local firewall behavior without changing any Clash setting.
Choose a controller port that is free and easy to recognize. 9090 is a common example, but it is not mandatory. The important rule is consistency: the port entered in the dashboard must exactly match the port exposed by Verge Rev. Do not reuse the mixed port, SOCKS port, or HTTP port unless the client explicitly documents that arrangement. A separate controller listener makes it easier to distinguish “the proxy cannot carry traffic” from “the management API is not responding.”
Use a non-empty secret even when the listener is bound to 127.0.0.1. Localhost is safer than a LAN address, but browser extensions, local applications, malware, and accidental firewall changes are still part of the threat model. Generate a long random value, store it in a password manager, and avoid placing it in screenshots or public support posts. The secret is normally entered into the dashboard connection form; it is not the same as your subscription token, provider password, or Windows account password.
Windows can also hold a port open after an application window appears to be closed. If you want to verify availability before configuring Verge Rev, open Windows Terminal or PowerShell and inspect the chosen port with a command such as Get-NetTCPConnection -LocalPort 9090 -ErrorAction SilentlyContinue. An empty result generally means that no TCP listener is currently visible on that port. If another process owns it, record the process information rather than repeatedly changing values without understanding the collision.
Enable the external controller in Clash Verge Rev
Start Clash Verge Rev and wait until the selected profile and core show a running state. Open the application settings, then inspect the section associated with the core, API, or advanced network options. In some builds, the relevant controls appear under a general Settings page; in others, they are grouped beside core management or runtime options. Search the settings page for controller if the visible labels do not match this article.
-
Locate the controller address. Enter
127.0.0.1or select a localhost-only option when Verge Rev presents a bind address. This keeps the API on the Windows machine instead of advertising it to every device on the network. -
Enter the API port. Use a free TCP port, for example
9090. Do not add a protocol prefix, slash, or dashboard path to a field that accepts only a number. - Create the secret. Paste a strong random secret into the controller secret field. Check for invisible spaces at the beginning or end, especially when copying from a password manager.
- Save or apply the settings. Some versions apply the controller immediately, while others restart the core or require a profile reload. Wait for the running indicator to return before testing.
A controller address may also be written as 127.0.0.1:9090 in a combined field. If the interface separates host and port, enter only 127.0.0.1 in the host field and only 9090 in the port field. If it requests a complete external controller value, use the exact format shown by the interface. Common mistakes include entering http://127.0.0.1:9090 into a numeric port box, entering the mixed port instead of the API port, or using 0.0.0.0 because a guide used it for a different network scenario.
After saving, reopen the setting and confirm that the value persisted. Then look at the core log or status panel for messages indicating that the controller is listening. A successful core start does not always prove that the API is available: the proxy engine may run while the controller fails to bind because another process already owns the port. Conversely, a dashboard error does not necessarily mean the profile or nodes are broken. Test the management listener independently before changing routing rules.
0.0.0.0 or a public interface for convenience. If remote administration is genuinely required, use a private network, firewall allowlist, strong authentication, and an encrypted access path rather than exposing a plain local API.
Connect a Web dashboard and verify the API
A compatible Web dashboard can provide a clearer view of proxy groups, active connections, rule matches, memory use, and traffic counters than a compact desktop panel. Open the dashboard from a trusted local copy or the distribution method recommended by its maintainer. Avoid pasting the controller secret into an unknown hosted page: the secret grants management access, not merely read-only statistics. If the dashboard offers a browser-only connection mode, confirm that it supports the API dialect exposed by the Mihomo core bundled with your Verge Rev version.
In the dashboard connection form, create a new endpoint and enter the controller URL. For the example values in this guide, the address is http://127.0.0.1:9090. Enter the exact secret configured in Verge Rev, save the endpoint, and select it as the active connection. Do not append /ui, /dashboard, or a random path unless the dashboard documentation specifically asks for that path. The dashboard normally adds the API routes itself.
A successful connection should reveal at least one combination of core status, proxy groups, or traffic information. Change a harmless display option or inspect the current selected group, then refresh the page. If the value remains consistent with Verge Rev, the dashboard is probably talking to the intended listener. For a stronger test, temporarily switch between two permitted nodes in a selector group and confirm that the selected policy changes in both interfaces. Return to your preferred node after testing rather than leaving an experimental route active.
The Windows browser may report a generic network error when the API is healthy but the browser blocks a request through cross-origin policy. This can happen when the dashboard is loaded from a different origin and the controller does not permit that origin. Treat this as an integration issue, not proof that the port is closed. A dashboard designed for local controller use may include an origin setting, a local proxy mode, or a documented configuration field. Do not solve it by disabling browser security globally.
| Symptom | Likely layer | First check |
|---|---|---|
| Dashboard says connection refused | Listener or port | Confirm the core is running and the port is free |
| Dashboard says unauthorized | Secret or authentication header | Re-enter the exact secret without spaces |
| Dashboard loads but shows no data | API compatibility or wrong endpoint | Check the URL, core type, and dashboard support |
| Proxy traffic works but dashboard fails | Controller configuration | Separate mixed-port testing from API testing |
Troubleshoot port conflicts, firewall rules, and stale values
When the controller port is already in use
If Verge Rev reports that the API cannot start, inspect the port owner in PowerShell. A useful sequence is Get-NetTCPConnection -LocalPort 9090, followed by Get-Process -Id <PID> for the process identifier shown in the result. The owner may be another Clash client, a development server, a container tool, or a process left behind after a crash. Close the known application cleanly, or choose a different unused controller port and update the dashboard at the same time.
Do not terminate an unfamiliar process merely because it occupies the example port. Windows services and security products can use ordinary development ports for legitimate reasons. If the process belongs to an organization-managed tool, ask the administrator before changing its state. Once the conflict is resolved, restart the core, verify the listener again, and remove old dashboard endpoints so you do not accidentally connect to the previous service.
When Windows Firewall or security software interferes
A localhost listener normally does not require a broad inbound firewall rule, but endpoint security can still inspect or block the application. If the API works immediately after disabling a security product, restore protection and create the narrowest approved exception instead of leaving the product disabled. Prefer an application-specific rule or localhost scope over an “allow any port from any address” rule. Corporate devices may prohibit user-created firewall exceptions entirely; follow the device policy.
Also verify that the dashboard is really opened on the same Windows machine. 127.0.0.1 always means “this device.” If you open the dashboard on a phone or another computer and enter 127.0.0.1:9090, that device will look for a controller on itself, not on the Windows PC running Verge Rev. A LAN address can make remote access possible, but it changes the security model and should not be used as a casual fix.
When the secret or endpoint is uncertain
The cleanest recovery is to stop guessing. Copy the controller host, port, and secret from the current Verge Rev settings, delete the old dashboard endpoint, and create a new one from scratch. If you suspect a hidden whitespace character, type the secret into a temporary local text editor, inspect it, and paste it again without adding quotation marks. Never include quotation marks unless the dashboard explicitly requires them.
Test in layers: first confirm that the core is running, then confirm that the TCP port is listening, then confirm that the dashboard reaches the endpoint, and finally confirm that authentication succeeds. Only after those checks pass should you investigate proxy groups, DNS mode, rule providers, or node health. The external controller is a management channel; it does not repair an invalid subscription, an unavailable node, or a broken routing rule by itself.
Secure daily use and practical maintenance
Treat the external controller secret like an administrative credential. Rotate it after sharing a configuration file, importing an unknown dashboard, lending the computer, or noticing unexpected policy changes. Keep the controller bound to localhost for ordinary desktop use, and remove unused dashboard endpoints from browser storage. If you use a portable dashboard, verify its source and keep it updated separately from Clash Verge Rev. A dashboard can be visually polished while still being incompatible with the API version or unsafe with stored credentials.
Record the meaning of each local port in a small private note: mixed port for application traffic, SOCKS port for SOCKS-aware tools, HTTP port for HTTP-aware tools, and external controller port for management. This simple inventory prevents accidental substitutions during future profile changes. When importing a new profile, check whether it changes core arguments, controller behavior, or the active core type. A profile may alter proxy listeners without changing the controller setting, while an application update may reset an advanced option.
Finally, test after Windows updates, Verge Rev upgrades, and core changes rather than assuming yesterday’s dashboard endpoint remains valid. Confirm that the core starts, the API port listens, the secret still authenticates, and the dashboard shows current groups. If only the dashboard fails while normal proxy traffic remains stable, focus on the controller address, API compatibility, CORS behavior, or firewall scope. If both fail, start with the core and profile instead of treating the controller as the root cause.
Compared with lightweight tray clients that hide API fields, older Clash builds with inconsistent controller defaults, or generic browser dashboards that provide little guidance when authentication fails, Clash Verge Rev gives Windows users a visible settings workflow, profile-aware core management, and a practical way to verify the API from both the application and a Web interface. Once the host, port, secret, and firewall scope are documented, external-controller maintenance becomes repeatable rather than guesswork; if you want those controls in a maintained Windows client, download Clash V.CORE and configure the controller with the same localhost-first principles.