What the Clash Verge Rev External Controller Does

Clash Verge Rev external controller is the local HTTP API that allows another interface to communicate with the Mihomo core running inside Clash Verge Rev. Instead of changing every proxy group from the desktop window, you can open a compatible Web dashboard, inspect active connections, switch outbound groups, review traffic, and reload a profile through a browser. The browser is only the control surface; the actual proxy engine, rules, DNS service, and TUN stack continue to run inside Clash Verge Rev.

On Windows, this distinction is important. The external controller is not the same thing as the Windows system proxy, the mixed port, or the TUN adapter. The mixed port carries application traffic through HTTP and SOCKS-compatible listeners. TUN mode captures traffic at the network layer. The external controller carries management requests such as “show current connections” or “select this proxy group.” Enabling it does not automatically make browser traffic use a proxy, and changing the controller port will not repair a broken subscription or a disconnected node.

A typical setup contains four separate values: an API listen address, an API port, an authentication secret, and a Web dashboard location. A safe Windows configuration commonly binds the API to 127.0.0.1:9090, keeps a non-empty secret, and launches a dashboard that connects to that address. The loopback address means that only programs on your own computer can reach the controller. By contrast, binding to 0.0.0.0 exposes the API on every available network interface, which may include Wi-Fi, Ethernet, a virtual adapter, or a VPN network.

Check Windows and Clash Verge Rev Before Editing Settings

Before enabling the API, close other Clash-family clients or at least make sure they are not running their own Mihomo process. Clash for Windows, Clash Verge Rev, Mihomo Party, and command-line Mihomo can each use similar ports. Running two cores at the same time often creates misleading symptoms: one client appears connected while the dashboard is attached to another process, a port is already occupied, or the API responds with a configuration that does not match the profile shown in the foreground window.

Open Clash Verge Rev and identify the active profile and core. The labels differ between releases, but the relevant areas are usually named Settings, General, Core, Controller, or External Controller. Some builds expose controller fields in a graphical settings panel; others expect an override or YAML configuration. Do not assume that a value shown in a provider profile is the value used by the active core. The effective configuration is the one generated after the profile, parser, and local overrides are merged.

It is also useful to record the current mixed port before making changes. In the Windows client, inspect the port section and note whether the application uses one mixed port or separate HTTP and SOCKS ports. This value is unrelated to the controller port. For example, a configuration may use 7890 for application proxy traffic and 9090 for API requests. Reusing the same port for both services will cause a bind failure because one listener cannot normally speak both protocols in the required way.

Use a short, private secret that is difficult to guess, preferably generated by a password manager. Avoid spaces, quotation marks, backslashes, and non-ASCII characters if you are unsure how a particular Verge Rev release serializes YAML. A long random string made from letters, numbers, and hyphens is generally easier to paste consistently. If your organization manages the PC, check whether endpoint security software blocks local listening services or modifies firewall behavior; the API may be perfectly configured while a security policy prevents the dashboard from connecting.

Enable the External Controller in Clash Verge Rev

Start by opening the controller settings in Clash Verge Rev. If the interface provides separate fields, enter the loopback address and port in the address field, then place the secret in the authentication field. Depending on the release, the address may be displayed as 127.0.0.1:9090, 127.0.0.1 plus a separate port field, or a complete external-controller value. The meaning is the same: Mihomo should listen locally on TCP port 9090 and require the configured secret for API calls.

If your version uses a YAML override, the essential structure looks like this:

external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-secret"

Do not copy the sample secret literally. Replace it with your own value and make sure the same value is used by the dashboard. YAML indentation and quotation marks matter when the setting is placed inside a larger override file. A malformed override may cause the core to reject the configuration, silently fall back to an earlier profile, or start without the controller. After saving, use the client’s reload or restart action rather than assuming that editing a file immediately changes the running process.

Some versions also offer built-in Web UI support. In that case, you may see fields such as External UI, External UI URL, or a dashboard download location. An external UI is not required for the API itself. It is simply a set of HTML, JavaScript, and CSS files that call the controller endpoints. You can enable the API first, verify that it responds, and only then add a dashboard. This separation makes troubleshooting much easier because it tells you whether the problem is the Mihomo listener or the dashboard frontend.

1. Open the active settings page: Launch Clash Verge Rev, select the settings area used by your installed release, and locate External Controller or the equivalent Mihomo controller option.
2. Set a local address: Enter 127.0.0.1:9090 or another unused local port. Do not begin with 0.0.0.0 unless you have a specific remote-management requirement and understand the firewall implications.
3. Add authentication: Enter a non-empty random secret. If a dashboard has its own connection dialog, record the secret in a password manager rather than leaving it in a plain-text note.
4. Save and restart the core: Apply the settings, reload the active profile if required, and restart Clash Verge Rev when the release indicates that a core restart is necessary.
5. Confirm the listener: Use a browser or PowerShell request to test the API before installing or configuring a Web dashboard.

Connect a Web Dashboard Safely

Once the core is listening, choose a dashboard that supports the Mihomo API rather than one designed only for an older Clash API. The dashboard can be built into Clash Verge Rev, loaded from a local external UI directory, or opened as a separate Web application. A compatible dashboard normally asks for an API endpoint and a secret. Enter the endpoint as http://127.0.0.1:9090 when the interface expects a full URL, or enter 127.0.0.1:9090 when it has separate protocol and host fields.

The browser’s address bar and the dashboard’s API target are not always the same thing. You might open a dashboard page at one URL while its JavaScript sends requests to the local controller at another URL. If the dashboard is hosted on a different origin, the browser may enforce CORS rules. Mihomo can require an appropriate external-controller configuration or dashboard setting for that cross-origin request. A local dashboard served from the controller’s configured external UI directory usually avoids some of this friction, but it does not remove the need for the correct secret.

After entering the endpoint and secret, look for a connected status, the current mode, the active proxy group, and a non-zero traffic counter. A dashboard that renders its shell but shows no groups may have loaded its static files successfully while failing its API request. In the browser’s developer tools, a 401 response usually means the secret is missing or incorrect; a connection-refused error usually means the controller is not listening on that address; a CORS error usually means the dashboard origin is not permitted or the endpoint was entered incorrectly.

Test the API and Troubleshoot Windows Errors

Testing from PowerShell gives you a clearer answer than staring at a dashboard spinner. First check whether Windows can find a listener on the selected port:

Get-NetTCPConnection -LocalPort 9090 -State Listen
Test-NetConnection 127.0.0.1 -Port 9090

The first command should show a listening TCP socket if the Mihomo core started correctly. The second reports whether the local TCP connection succeeds. If both commands fail, review the controller address, restart the core, and inspect the Clash Verge Rev log. If a different process owns the port, choose another unused port such as 9091 and update the dashboard endpoint to match.

To test an authenticated API endpoint, use a request that includes the secret in the authorization header. Replace the placeholder with your actual value and avoid saving the command in a shared shell history when working on a managed computer:

$secret = "replace-with-your-secret"
Invoke-RestMethod `
  -Uri "http://127.0.0.1:9090/version" `
  -Headers @{ Authorization = "Bearer $secret" }

A successful response normally contains version information from the running core. The exact JSON fields can vary, so focus first on receiving a valid response rather than matching a screenshot. You can then query a general endpoint from the dashboard or use its built-in connection test. If an unauthenticated request returns unauthorized while the authenticated request succeeds, the controller is working and the remaining issue is dashboard credentials or endpoint formatting.

When the API works locally but a remote dashboard cannot reach it, do not immediately open the port to the entire network. Binding to 0.0.0.0 and adding a broad firewall rule increases the attack surface. A safer approach is to keep the controller on loopback and use a local dashboard, Windows Remote Desktop, or an authenticated tunnel that you understand. If remote access is unavoidable, bind to a specific private LAN address, restrict the Windows Firewall rule to a trusted profile and source range, use a strong secret, and avoid exposing the port through router port forwarding.

Finally, remember that controller success does not prove proxy success. The API can answer while the selected node is offline, DNS is misrouted, TUN permissions are incomplete, or the active rules send every request to DIRECT. Use the dashboard’s proxy group and connection view together with a real test site. Change one variable at a time: first verify the API, then verify a group switch, then verify an application request. This sequence prevents a controller problem from being confused with a subscription, DNS, or Windows networking problem.

Compared with older Clash dashboards, which often assume a fixed API path, expose confusing port fields, or provide little guidance when a secret and CORS policy disagree, Clash Verge Rev can still require careful attention to the effective Mihomo configuration and Windows listener state. Clash Official Site is useful here because its Windows-focused instructions separate the controller port from the mixed port, explain local-only binding, and give you PowerShell checks instead of asking you to guess from a blank dashboard. If you want a practical Clash client workflow with the configuration concepts covered in one place, you can download Clash Official Site and use this checklist while enabling the external controller.