Clash Verge Rev External Controller Setup Guide for Windows

What the External Controller Does

Clash Verge Rev includes an external controller interface that allows compatible tools to communicate with the running Clash or Mihomo core through an HTTP API. Instead of opening the desktop client every time you want to inspect a proxy group, change a selected node, or check the current connection, you can use a Web dashboard connected to this controller.

On Windows, this feature is useful for remote-style management, troubleshooting, and quick status checks. A dashboard can display active connections, traffic statistics, DNS requests, proxy groups, and rule matches in one place. It can also let you switch a proxy group without opening the main Clash Verge Rev window. However, the controller is not a public website and should not be exposed casually to the internet. Anyone who can reach the API may be able to read connection information or change proxy settings, depending on the permissions provided by the core.

This guide explains how to configure the controller inside Clash Verge Rev, connect a Web dashboard safely, test whether the API is responding, and resolve the most common Windows connection failures. The interface labels may vary slightly between builds, but the workflow remains the same: enable the controller, define a bind address and port, set a secret, connect the dashboard, and verify the result.

1Understand the Controller Settings

Before changing anything, it helps to understand the three values that determine whether a dashboard can connect. These values are normally shown in the controller, external controller, or API section of Clash Verge Rev.

The bind address is the most important security choice. The address 127.0.0.1, also called localhost, limits access to applications running on the same computer. A dashboard opened in your Windows browser can still connect, but another device on your Wi-Fi network cannot directly reach the API. By contrast, 0.0.0.0 listens on all available network interfaces. That may be useful for a carefully controlled home-lab setup, but it also increases the attack surface and can expose the controller to other computers on the network.

The port is simply a communication endpoint. Port 9090 is commonly used in Clash-related configurations, but it is not mandatory. If another program already occupies that port, Clash Verge Rev may fail to start the controller or Windows may refuse the connection. Choosing an unused port above 1024 is usually convenient. Avoid changing the port repeatedly while troubleshooting; first record the exact value and use it consistently in the dashboard.

Controller Port Is Not the Proxy Port

A frequent beginner mistake is confusing the external controller port with the HTTP, SOCKS, or mixed proxy port. The proxy port carries browser and application traffic through Clash. The controller port carries management requests such as API status checks and proxy-group changes. They can have different numbers and should not be treated as interchangeable.

For example, your Windows applications might use a mixed proxy port of 7890, while the Web dashboard connects to the controller at 127.0.0.1:9090. Entering 7890 in the dashboard's controller field will normally produce a timeout or an invalid API response because that port is speaking the proxy protocol rather than the controller API.

2Enable the External Controller in Clash Verge Rev

First launch Clash Verge Rev with administrator permission only if your installation or Windows service requires it. In most cases, the application can run normally. Confirm that a profile is active and that the Mihomo core is running before testing the controller. A dashboard cannot retrieve useful data if the core has not started.

1. Open Clash Verge Rev on Windows.
2. Open the Settings page from the left navigation.
3. Look for a section named External Controller, Controller, API, or a similarly named advanced option.
4. Enable the controller switch if it is disabled.
5. Set the listen address to 127.0.0.1.
6. Enter a controller port, such as 9090.
7. Enter a strong secret and save the settings.
8. Restart the Clash or Mihomo core if the application asks you to do so.

Some versions expose these settings through the active profile instead of a dedicated graphical form. In that case, open the profile editor and inspect the controller-related YAML fields. A typical Mihomo configuration uses the following structure:

The exact location of these keys can differ between generated profiles. Do not create duplicate external-controller or secret entries in different parts of the same YAML file. YAML indentation and duplicate keys can cause confusing results, including a profile that appears to save successfully but starts with unexpected values.

Choose and Store the Secret Carefully

The controller secret is not the same as your proxy subscription password, Windows password, or Wi-Fi password. Generate a separate value with enough length and avoid putting personal information in it. A password manager is a good place to store it. Do not paste the secret into public screenshots, issue reports, or chat messages. If you believe it has been exposed, replace it immediately and reconnect every dashboard that used the old value.

Do not leave the secret blank just because the dashboard appears to work without one. An unauthenticated controller on a shared network can be discovered by other devices, browser extensions, malware, or local development tools. Authentication is particularly important if you later change the bind address from localhost to a LAN address.

3Connect a Web Dashboard Safely

After enabling the API, open a compatible Clash Web dashboard in your Windows browser. The dashboard may ask for an API URL, controller address, or backend endpoint. For a local Clash Verge Rev installation, enter the address in this format:

Replace 9090 with the port configured in your client. If the dashboard has a separate secret field, paste the controller secret there. Some dashboards combine the secret with the URL by using a token parameter, while others provide a dedicated authentication box. Follow the dashboard's own format and avoid adding quotation marks unless it explicitly requests them.

A successful connection normally shows information such as the current mode, active proxy groups, memory usage, upload and download counters, or live connections. Seeing the dashboard page alone does not prove that the API works. Many Web dashboards load their user interface first and only show an error after attempting an API request. Look for a connected status indicator or a populated proxy list.

Test the API Directly

If the dashboard fails, test the controller separately. Open PowerShell and run a request against the controller endpoint. The following command checks whether the core responds:

Replace the placeholder with your actual secret. A successful response should contain JSON or readable version information. Depending on the Mihomo build, the response may include fields such as the core name and version. If you receive an authorization error, the address and port are probably reachable but the secret is wrong. If PowerShell reports that the connection was refused, the controller is not listening at that address and port, or the core is not running.

You can also test the port without an API request:

When TcpTestSucceeded is True, Windows can reach a process on that port. This does not validate the secret or guarantee that the process is the Clash controller, so use the /version request for a complete check.

4Fix Connection Problems and Improve Security

Most controller failures come from a small number of configuration mistakes. Work through the checks below in order rather than changing several values at once. A controlled process makes it easier to identify the real cause.

Check Windows Firewall and Network Scope

For a controller bound to 127.0.0.1, Windows Firewall usually does not need a broad inbound rule because the service is restricted to the local machine. If you create an inbound rule that allows the controller port from all profiles and all remote addresses, you may accidentally expose the API to your home, office, or public network. Avoid disabling the firewall as a troubleshooting shortcut.

If you intentionally need to manage Clash from another trusted device, first understand the risk. Change the bind address to the computer's private LAN address or a controlled interface, keep a strong secret, and create a narrow firewall rule that permits only the trusted device's IP address. Do not forward the controller port on your router, and do not publish it directly to the public internet. A controller API is a management interface, not a service designed for anonymous internet access.

Handle Browser and Dashboard Issues

A browser dashboard can also fail because of cached settings, a blocked mixed-content request, or an incompatible API implementation. If the page was loaded over HTTPS but attempts to call an HTTP localhost endpoint, the browser may block the request as mixed content. Try the dashboard's officially supported connection method, use a local dashboard build when appropriate, and inspect the browser developer console for the exact error.

Clear the saved dashboard profile and enter the endpoint again rather than assuming the old value was replaced. Check for common typing errors such as http://127.0.0.1:9090/ versus an unrelated proxy port, an extra space after the secret, or a secret copied with quotation marks. If one dashboard does not work, test the API with PowerShell first. This separates a Clash configuration issue from a dashboard compatibility issue.

5Final Verification Checklist

Once the dashboard connects, perform a final review before relying on it for daily management. Confirm that the controller remains enabled after restarting Clash Verge Rev and that the active profile still contains the expected values. Use PowerShell to verify the endpoint one more time, then check whether the dashboard shows current proxy groups and live status data.

• The Mihomo core is running inside Clash Verge Rev.
• The controller listens on the intended address and port.
• The dashboard uses the controller port, not the HTTP or SOCKS proxy port.
• A strong secret is enabled and stored privately.
• The API responds to a version request with the correct authorization header.
• The controller is bound to 127.0.0.1 unless restricted LAN access is genuinely required.
• No router port forwarding exposes the controller to the public internet.
• The dashboard is compatible with the Mihomo API used by your Clash Verge Rev build.

The safest Windows setup is usually also the simplest one: keep the controller local, protect it with a unique secret, and connect a dashboard from the same computer. If you later need remote management, treat that as a separate security project rather than casually changing the bind address. With the correct port, authentication header, and API endpoint, Clash Verge Rev's external controller becomes a practical way to inspect and manage your proxy environment without weakening the rest of your network security.

Download Clash for Free – Get Started Now →