How to Set Up Clash Verge Rev External Controller on Windows

Why the External Controller Matters on Windows

Clash Verge Rev is usually operated through its desktop interface, but the client also exposes an external controller: an HTTP API that lets a compatible dashboard inspect running connections, switch proxy groups, review logs, and change selected runtime settings from a browser. On Windows, this is useful when the main window is minimized, when you want to monitor several profiles from one dashboard, or when you prefer a web interface to repeatedly opening the native application.

The controller is not a second proxy port and it does not automatically make the entire computer reachable from your network. The proxy listener handles application traffic such as HTTP, HTTPS, or SOCKS requests. The external controller listens for management requests, normally on a separate local TCP port. A browser dashboard sends commands to that management port, and Clash Verge Rev passes them to the embedded Mihomo-compatible core. Keeping those roles separate is important because opening the wrong port, or confusing a proxy authentication password with an API secret, is one of the most common causes of failed setup.

The controller also has meaningful security consequences. Anyone who can reach an unauthenticated controller may be able to change your active proxy group, read connection metadata, terminate sessions, or retrieve operational information. Even when the controller does not expose the original subscription token directly, it should still be treated as an administrative interface. For a normal Windows desktop, bind it to the loopback address and use a strong secret. Only expose it to a trusted LAN when you have a clear reason, understand Windows Firewall rules, and know which devices can reach that network.

Prepare Clash Verge Rev and Windows Before Editing Settings

Start with a maintained Clash Verge Rev build obtained from a trustworthy release channel. Avoid repacked installers that add unknown launchers or modify configuration files. If you need a fresh installer, use the site’s download page and verify that the application launches normally before changing controller settings. A controller problem is much easier to isolate when the profile can already load, the core is running, and ordinary proxy traffic has been tested.

Close duplicate proxy clients during the initial test. Another Clash fork, a VPN application, a development server, or an old dashboard may already occupy the port you intend to use. The proxy port and controller port must each be available, and neither should silently be redirected by a corporate security product. If the application displays a port conflict, do not keep changing random values; first identify the process that owns the port.

Open Windows Terminal or PowerShell and check a candidate controller port with a local connection test. For example, if you plan to use port 9090, inspect whether another process is listening:

Get-NetTCPConnection -LocalPort 9090 -ErrorAction SilentlyContinue

An empty result normally means that PowerShell found no current listener on that port. A returned row means the port is already in use, so choose another value such as 9091 or 9097. This check does not prove that Clash Verge Rev will bind successfully, but it removes one avoidable variable. You can also inspect the owning process with Task Manager or use Get-Process after identifying its process ID.

Decide whether the dashboard will run on the same Windows machine or on another device. For a same-machine dashboard, use 127.0.0.1 or localhost. For a trusted LAN dashboard, the controller must listen on an address reachable from that LAN, commonly the Windows host’s private address or a wildcard bind supported by the client. The second option is more convenient but also more dangerous: a misconfigured Wi-Fi network, guest device, or broad firewall rule can turn a local administration feature into a network administration feature.

Security baseline: Use loopback binding first, set a non-empty secret, verify the dashboard locally, and only then consider LAN access. Never begin troubleshooting by disabling Windows Firewall or removing the controller secret.

Enable the External Controller in Clash Verge Rev

The exact labels can differ slightly between Clash Verge Rev releases and between the graphical settings page and the active YAML profile. Look for a section named External Controller, External Control, or a similarly translated management setting. Some builds place it under general application settings; others expose the value in the profile editor or in an advanced core configuration panel. The concept is the same: define a listening address and port, then define the secret used by API clients.

Set the controller address to 127.0.0.1:9090 for the safest first test. The address tells the core where to listen, while 9090 is only an example port. If that port is occupied, use the free port you confirmed earlier. Do not use the same number as your mixed port, HTTP port, or SOCKS port unless you have verified that the application explicitly supports such a layout; separate ports make logs and future diagnosis much clearer.

Enter a long, unique secret in the controller secret field. A password manager can generate one containing letters, numbers, and symbols. Avoid reusing your Windows password, subscription token, or a short phrase such as clash123. Treat the secret as an API credential: do not paste it into screenshots, public issue reports, browser bookmarks shared with colleagues, or configuration repositories.

If the interface offers an authentication mode, choose token-based authentication and confirm how the dashboard expects to send it. Mihomo-compatible controllers commonly accept an authorization header in the form Bearer YOUR_SECRET. A dashboard may ask for only the secret and add the header automatically, while a raw API client requires you to type the complete header yourself. These are equivalent only when the client constructs the request correctly.

Save the setting and restart the core if Clash Verge Rev does not apply it immediately. A profile reload may be enough in one release, while another requires restarting the application. After the restart, confirm that the selected profile is still active and that the controller port has not reverted to an empty or default value. Avoid editing a generated configuration file while the GUI is running if the client regenerates that file on every profile update; your manual change may disappear during the next refresh.

When a YAML-based configuration is appropriate, the conceptual structure often looks like this:

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

Treat this as a configuration model rather than a promise that every Clash Verge Rev build exposes identical fields in the same file. If the GUI manages the core configuration, prefer the GUI’s documented field. If a profile provider overwrites local values, place controller settings in the client’s local override or controller-specific settings area instead of modifying a remote subscription that will be regenerated.

Connect a Web Dashboard and Verify the API

With the controller enabled, open a compatible web dashboard in the browser. A dashboard can be hosted locally, served from a trusted internal site, or loaded from a release that you have reviewed. The dashboard URL and the controller API URL are different concepts: the browser loads the dashboard files from one location, then the dashboard makes API requests to the controller address you enter. If the dashboard asks for an API base URL, provide the controller endpoint, for example http://127.0.0.1:9090, without adding an arbitrary path unless the dashboard documentation requires one.

Enter the secret exactly as configured. Watch for copied whitespace, smart quotes, and hidden line breaks when transferring a password from a password manager. If the dashboard provides a connection test, run it before changing a proxy group. A successful connection should normally allow it to display the current version, active mode, proxy groups, or connection list. If the dashboard loads visually but reports “API unavailable,” the static dashboard files are working; the remaining problem is usually the controller URL, port, authentication header, or browser access policy.

You can test the API directly from PowerShell to separate dashboard problems from controller problems. Replace the sample port and secret with your own values:

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

A structured response containing version information confirms that the listener and authentication are responding. An HTTP 401 or 403 response usually means that the controller is reachable but the secret is wrong or the authorization format is not accepted. A connection refusal means that nothing is listening at that address and port, the core did not restart successfully, or a local security product blocked the process. A timeout points more strongly toward an incorrect address, firewall filtering, or an attempt to use a LAN address when the controller is bound only to loopback.

Once connected, test read-only visibility before making changes. Check the running core version, current mode, proxy groups, and active connections. Then make one controlled action, such as selecting a different member in a test group, and confirm that Clash Verge Rev reflects the change. If the dashboard can read data but cannot switch groups, inspect its permissions, API compatibility, and request format rather than assuming that the controller is only partially enabled.

Fix Windows Access, Firewall, and Profile Problems

The most common Windows mistake is testing a LAN address against a controller that is bound to loopback. A service listening on 127.0.0.1 accepts requests originating on that same computer; it does not automatically accept requests arriving at the machine’s Wi-Fi or Ethernet address. If the dashboard runs on another device, change the controller binding only after confirming that remote administration is necessary. Then create a narrow inbound Windows Firewall rule for the selected TCP port and trusted private network profile, rather than enabling the port for every network type.

Before adding a rule, test whether Windows can reach the port from the second device. From another Windows computer, you can use:

Test-NetConnection 192.168.1.20 -Port 9090

Replace the example address with the host running Clash Verge Rev. A failed test does not identify the exact fault, but it confirms that the connection is not reaching a usable listener. Check the host’s private IP address, confirm that the network is marked Private when appropriate, verify the controller bind address, and inspect the firewall rule scope. Do not expose the controller through port forwarding on a home router unless you have a carefully designed authenticated access architecture; direct Internet exposure is unnecessary for ordinary dashboard use and greatly expands the attack surface.

Browser behavior can create another layer of confusion. A dashboard loaded over HTTPS may block requests to an HTTP controller because of mixed-content rules. A dashboard hosted on another origin may also send a preflight request before the actual API call, and the controller or reverse proxy may not provide the expected CORS response. When local testing works in PowerShell but the browser fails, open Developer Tools and inspect the Network panel. Look for the exact request URL, status code, blocked mixed-content message, CORS error, or failed preflight. This evidence is more useful than repeatedly changing the secret.

If the controller works immediately after launch but stops after a profile update, compare the effective configuration before and after the update. Subscription providers generally control proxy groups and rules, while local controller settings belong to the client or core runtime. A remote profile refresh may replace fields that you edited directly. Use a local override mechanism when available, and keep a backup of working values without storing the secret in a publicly synchronized folder.

Port collisions can return after a reboot because Windows startup applications launch in a different order. Check the listener again, disable obsolete clients, and reserve a clearly documented port for Clash Verge Rev. If a security suite reports that the application is listening, confirm its executable path and signature before creating an allow rule. A broad “allow any application on any port” exception is difficult to audit and may accidentally authorize an unrelated process.

Finally, remember that the external controller does not repair broken proxy routing. If the dashboard connects but a selected proxy group cannot reach a destination, inspect the core logs, DNS mode, rule providers, and node health independently. The controller is an observability and management channel; it does not guarantee that every upstream node, rule, or resolver is healthy. Keeping management connectivity separate from proxy connectivity makes this distinction much easier to prove.

A Safe Daily Workflow for the External Controller

After the first successful setup, write down the controller address, port, dashboard URL, and the location where the setting is managed. Do not write the secret in plain text beside the port. A short operational note can state whether the controller is local-only, which Windows account owns the application, and which firewall profile is permitted. This prevents future troubleshooting from turning into guesswork after a system update or a profile migration.

Keep the controller bound to loopback unless another device genuinely needs access. When remote access is required, prefer a private, segmented network and a narrowly scoped firewall rule. Review connected devices, remove old dashboard bookmarks, rotate the secret after sharing it with a third-party tool, and close the dashboard when you are finished. These habits are simple, but they reduce the chance that an old browser session or forgotten laptop retains administrative access.

Use the dashboard for deliberate actions rather than constant automation. Switching a proxy group is easy; understanding why a rule selected that group still requires logs and configuration review. Before changing a production profile, note the current group and mode, make one change, observe the result, and revert if the result is unexpected. This controlled workflow is especially valuable on Windows systems where multiple applications may alter system proxy settings, environment variables, DNS behavior, or network filters independently.

When comparing clients, older Clash for Windows installations may offer a familiar controller workflow but can leave you with aging UI assumptions, incomplete maintenance, or less predictable behavior on current Windows builds. A raw core gives precise control but expects more YAML knowledge and offers less convenient profile management. Clash Verge Rev sits between those extremes with a desktop interface, profile-oriented workflow, and access to Mihomo-compatible runtime controls. For readers who want the same management discipline with a maintained, streamlined desktop experience, Clash V.CORE provides a practical alternative for inspecting listeners, organizing routing profiles, and managing Windows proxy behavior; when you are ready to compare supported packages and choose the appropriate build, download Clash V.CORE from the official page.