Clash Verge Rev External Controller Setup on Windows

Clash Verge Rev includes a built-in external controller that exposes Clash or Mihomo through a local HTTP API. Once it is enabled, a compatible web dashboard can display traffic, inspect connections, switch proxy groups, update providers, and reload profiles without repeatedly opening the desktop client. On Windows, the setup is usually straightforward, but small details matter: the controller address must use the correct port, the dashboard must connect to the same address, and the API secret must be entered exactly as configured. This guide explains how to configure the external controller in Clash Verge Rev, connect a browser-based dashboard, and diagnose failed access while keeping your proxy controls private.

Understand the External Controller Before You Enable It

The external controller is an HTTP API server provided by the Clash-compatible core running inside Clash Verge Rev. It is separate from the local HTTP or SOCKS proxy port. The proxy port handles application traffic; the controller port handles management requests such as reading the current mode, changing a proxy group, retrieving connection information, and reloading configuration.

For example, a typical Windows installation may use port 7890 for HTTP proxy traffic and port 9090 for the external controller. These ports serve different purposes and should not be confused. Entering 127.0.0.1:7890 into a dashboard will normally fail because that port expects proxy requests rather than controller API requests.

On a personal Windows computer, binding the controller to 127.0.0.1 is the safest default. It means that only programs running on the same computer can reach the API. A dashboard opened in a browser on that computer can still connect normally, while other devices on the network cannot directly control your Clash instance.

Configure the Controller in Clash Verge Rev

Clash Verge Rev can expose controller settings through its profile editor, depending on the installed version and selected core. The most reliable method is to edit the active YAML profile and add the controller fields at the top level. These fields must not be placed inside proxy-groups, dns, or another nested section.

First open Clash Verge Rev on Windows and confirm that the profile you intend to use is active. Open the profile management page, locate the current YAML configuration, and choose the edit option. If the application offers both a visual editor and a raw YAML editor, use the raw editor for these settings. Add the following configuration:

# Clash Verge Rev / Mihomo controller settings
external-controller: 127.0.0.1:9090
secret: replace-with-a-long-random-secret

The value after external-controller contains two parts: the bind address and the TCP port. 127.0.0.1 means local-only access, while 9090 is the port on which the API listens. You may choose another unused port, such as 9097 or 19090, but the same port must be entered in the dashboard later.

The secret value is used as a Bearer token by dashboard requests. Use a unique value with a mixture of upper- and lowercase letters, numbers, and symbols. Avoid reusing your Windows password, subscription password, or a short word that could be guessed. YAML treats some punctuation specially, so enclosing the secret in quotation marks is a practical way to avoid parsing surprises.

After saving the profile, reload it from the Clash Verge Rev interface. Some versions reload automatically, while others require you to click the reload button or restart the selected core. The controller is not available until the running core has accepted the configuration. If the profile editor reports a YAML error, inspect indentation, quotation marks, and duplicate top-level keys.

A complete minimal example may look like this:

mixed-port: 7893
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-secret"

proxies: []
proxy-groups: []
rules:
  - MATCH,DIRECT

The empty proxy and proxy-group sections above are only structural examples; a real subscription profile will normally contain its own nodes, groups, and rules. Do not replace your working profile with this sample. Add the controller fields to the profile you already use, and keep a backup before editing.

Choose the Right Address, Port, and Secret

There are three common controller binding choices. The first is 127.0.0.1:9090, which is recommended for a dashboard used on the same Windows computer. The second is 0.0.0.0:9090, which listens on all local network interfaces. The third is a specific private LAN address, such as 192.168.1.20:9090. The latter two can support access from a phone or another computer, but they increase the attack surface.

Do not bind the controller to a public server address simply because the dashboard is hosted on the internet. A public-facing API endpoint can be scanned and attacked. If remote access is genuinely necessary, prefer a private VPN, an SSH tunnel, or another authenticated private network rather than exposing the controller directly to the public internet.

Windows may also ask whether to allow Clash Verge Rev through the firewall. A local-only controller generally does not need a broad inbound firewall rule, because loopback traffic stays on the computer. If you intentionally enable LAN access, create the narrowest rule possible: allow the selected TCP port only on the Private network profile, avoid Public networks, and keep the secret enabled.

To check whether another program already uses the chosen port, open PowerShell and run:

Get-NetTCPConnection -LocalPort 9090 -ErrorAction SilentlyContinue

If the command returns an existing listener, choose a different port or stop the conflicting application. You can also inspect listening ports with netstat -ano | findstr :9090. A port conflict can make the profile appear correct while the controller still fails to start.

Connect a Web Dashboard

Once the core has reloaded successfully, open a compatible Clash dashboard in your browser. Metacubexd is a common choice for Mihomo-based configurations, while Yacd and Zashboard are also used by many Clash-compatible clients. A dashboard is only a front-end; it does not replace the Clash core and does not create a proxy connection by itself.

When the dashboard asks for a backend or API address, enter the full controller URL. For a local setup, use:

• Backend address: http://127.0.0.1:9090
• Secret: the exact value configured under secret
• HTTPS option: leave disabled unless a separate HTTPS reverse proxy is actually configured

Do not add an extra path such as /ui unless the dashboard specifically requires it. The controller API is normally served from the root address. Do not enter the HTTP proxy port, SOCKS port, or the address of a subscription server. Those endpoints have different protocols and cannot authenticate dashboard API requests.

If the dashboard is downloaded and hosted locally, the browser may display a cross-origin error when it tries to call the controller. This is usually related to CORS rather than the secret itself. Mihomo-based cores may support an external-controller-cors setting. If your dashboard requires it, allow only the exact origin used by the dashboard rather than using a wildcard.

external-controller-cors:
  allow-origins:
    - http://127.0.0.1:8080
    - http://localhost:8080

Only add this option if the selected core supports it and the browser console clearly indicates a CORS problem. A hosted dashboard may use a different origin from the address visible in the browser, so copy the origin exactly, including the scheme and port. Avoid adding broad origins such as * when the controller exposes management functions.

After saving the dashboard connection, verify several read-only details first. The dashboard should show the core version, current mode, active proxy groups, and a traffic graph. Then test a harmless action such as switching between two nodes in a non-critical group. If the dashboard can read status but cannot change settings, check whether the profile is read-only or whether the dashboard is using an API feature not supported by the selected core.

Troubleshoot Failed Access on Windows

When a dashboard reports “connection failed,” troubleshoot in layers rather than changing several settings at once. First confirm that Clash Verge Rev is running and that the intended profile is active. Then verify that the controller fields are present in that profile, not only in an inactive template or a downloaded subscription file that gets overwritten during the next update.

Check Whether the API Is Listening

Run this PowerShell command after reloading the profile:

Test-NetConnection 127.0.0.1 -Port 9090

If TcpTestSucceeded is False, the problem is below the dashboard layer. Check for a YAML syntax error, an occupied port, a failed core, or a controller field that was placed under the wrong section. If the result is True, the port is reachable and you should focus on the URL format, secret, browser origin, or dashboard settings.

Match Common Error Messages

A 401 response is useful because it proves that the dashboard reached the controller. In that situation, do not change the port or Windows firewall first; inspect the secret, quotation marks, leading or trailing spaces, and whether the dashboard has saved an old token. If you recently changed the secret, remove the saved dashboard connection and create it again.

If the controller works at 127.0.0.1 but not from another device, check the binding address and Windows network profile. A loopback binding intentionally rejects LAN clients. If you changed the binding to a private LAN address, make sure you are using the current Windows IP address and that the firewall allows the port on a Private network. Never test by disabling all firewall protection permanently.

Secure and Maintain the Setup

Once the dashboard works, keep the configuration maintainable. Record the controller port in a private note, but do not store the secret in a public repository or share it with a profile URL. If you export a YAML profile for troubleshooting, replace the real token with a placeholder before uploading it. A controller secret grants management access; it is not merely a label for the dashboard.

Review the binding after every major profile change. Subscription updates can replace or merge top-level settings depending on how the profile is managed. If the controller suddenly disappears after an update, compare the active generated configuration with your saved version. Keep a small backup containing the controller address and secret separately from the subscription content, and reapply the settings only when necessary.

For a single Windows computer, the recommended final arrangement is simple:

• Bind the controller to 127.0.0.1.
• Use a non-conflicting local TCP port.
• Set a long, unique secret.
• Connect the dashboard to the exact HTTP controller URL.
• Enable CORS only for a known dashboard origin when required.
• Avoid exposing the controller through port forwarding or a public reverse proxy.
• Test the listener with PowerShell before troubleshooting the browser.

With these settings, Clash Verge Rev can remain safely controlled from a browser while the API stays limited to your own Windows machine. Start with a local-only binding, confirm that status and proxy groups load correctly, and expand access only when there is a clear need and a private network path to protect it.