How To Set Up External Controller In Clash Verge Rev On Windows
Understand What the External Controller Does
Clash Verge Rev uses a proxy core to accept local traffic, resolve domains, match rules, and connect to proxy nodes. The external controller is a separate HTTP API exposed by that core. It allows a compatible Web dashboard or management tool to read runtime information and send commands, such as changing the active proxy group, viewing current connections, checking traffic statistics, or inspecting the loaded configuration.
This controller is not the same thing as the HTTP proxy, SOCKS proxy, mixed port, or TUN interface. A proxy port carries application traffic through Clash. The external controller port carries management requests to the Clash API. For example, a browser or terminal may use 7890 as a local mixed proxy, while a dashboard connects to 127.0.0.1:9090 as the controller API. Mixing these two ports is one of the most common reasons a dashboard appears unable to connect.
On Windows, the controller normally listens on the local machine. The address 127.0.0.1, also called localhost, means that only programs running on the same computer can reach the API. This is the safest starting point because it does not expose control functions to other devices on the network. An address such as 0.0.0.0:9090 may allow connections from the local network, but it also increases the risk of unauthorized access if the port is not protected by a strong secret and suitable firewall rules.
In Clash-compatible YAML, the basic settings look like this:
external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-secret"
The first line defines the address and port used by the API. The second line defines the authentication secret required by most external dashboards. These values do not select a proxy node and do not change the routing mode. They only control how management software connects to the running core.
Clash Verge Rev may display these settings through its graphical interface instead of requiring direct YAML editing. The exact wording can differ between releases and between the Mihomo and legacy core profiles, so treat menu names as functional descriptions rather than relying on one fixed screenshot. Before editing anything, confirm which profile is active and which core is running.
Prepare Clash Verge Rev and Choose Safe Values
Start Clash Verge Rev on Windows and make sure a configuration is selected and running. If the profile has not been loaded, the controller may not start even when the field is present in a saved configuration. Check the profile list, select the configuration you normally use, and activate it. The system proxy switch is not required for the controller itself, but starting the core makes it possible to test the API.
Open the application settings and look for a section named Settings, General, Core, or External Controller. In some builds, the option is under the Mihomo core settings; in others, it is exposed through the configuration editor or an advanced settings panel. If you cannot find a dedicated field, search the active YAML for external-controller and secret. Do not add duplicate keys at different levels because the active parser may reject the configuration or use a value different from the one you expect.
For a local Windows setup, use the following values first:
| Setting | Recommended value | Purpose |
|---|---|---|
| Controller address | 127.0.0.1 |
Accept management requests from the same Windows computer |
| Controller port | 9090 |
Expose the Clash API on a commonly unused local port |
| Secret | A unique random string | Authenticate dashboard and API requests |
| LAN exposure | Disabled initially | Prevent other devices from reaching the management API |
Port 9090 is only an example and is not guaranteed to be free. If another program already occupies it, choose another local port such as 9091 or 19090. Avoid changing the port repeatedly while troubleshooting because every dashboard URL and API test must use the current value. A port above 1024 is generally convenient for a desktop application, but availability matters more than the number itself.
Create a secret that is long enough to prevent guessing and does not contain accidental YAML syntax. A random string of at least 24 characters is a practical choice. If you enter the value in YAML, quote it when it contains punctuation, spaces, a colon, a hash sign, or characters that could be interpreted by the parser. Keep the secret private: anyone who can authenticate to the controller may be able to change proxy groups, inspect connections, or access other runtime information.
After saving the setting, apply or reload the configuration according to the button shown by Clash Verge Rev. Some changes require a core restart. If the application provides separate actions such as Reload, Restart Core, and Restart App, begin with a configuration reload, then restart the core if the port does not become available. A full application restart is useful when an older core process may still be holding the previous port.
Verify the API on Windows Before Adding a Dashboard
Test the controller directly before configuring a Web dashboard. This separates a Clash configuration problem from a dashboard URL or authentication problem. Open Windows PowerShell and send a request to the local API. The endpoint /version is a convenient first check because it normally returns information about the running core without requiring a complicated request body.
$headers = @{ Authorization = "Bearer replace-with-your-secret" }
Invoke-RestMethod -Uri "http://127.0.0.1:9090/version" -Headers $headers
Replace the port and secret with the values actually configured in Clash Verge Rev. A successful response should contain JSON with version information. Depending on the core and release, the response may include fields such as meta, premium, or a version string. The exact field names are less important than receiving a valid HTTP response from the expected local port.
You can also use curl.exe in PowerShell. Calling curl.exe explicitly avoids confusion with PowerShell aliases on older Windows versions:
curl.exe -i ^
-H "Authorization: Bearer replace-with-your-secret" ^
http://127.0.0.1:9090/version
In PowerShell, the caret character is commonly used as a line-continuation character only in Command Prompt syntax. If the multiline form behaves unexpectedly in your shell, place the command on one line or use the PowerShell example above. A typical successful result begins with an HTTP status such as 200 OK, followed by a JSON response.
To test whether the port is listening independently of authentication, run:
Test-NetConnection 127.0.0.1 -Port 9090
When TcpTestSucceeded is True, Windows can reach a process on that port. This does not prove that the secret is correct, but it confirms that the address and port are reachable. When it is False, focus on the active core, port conflicts, configuration loading, and whether Clash Verge Rev was restarted after the change.
Windows can also show which process owns a port:
netstat -ano | findstr :9090
tasklist /FI "PID eq 1234"
Replace 1234 with the PID shown by netstat. If the port belongs to another application, either stop that application when appropriate or select a different controller port for Clash Verge Rev. If no process is listed, the API is not listening on that address at the moment of the test.
Do not test the controller through the system proxy while diagnosing it. Use the direct localhost URL. If the system proxy is enabled and a tool sends localhost traffic through that proxy, the request may take an unnecessary route and produce misleading results. Local API checks should target 127.0.0.1 directly.
Connect a Web Dashboard with the Correct API Details
Once the direct API test works, open the Web dashboard you intend to use. The dashboard may be bundled into a client, opened as a local page, or provided as a separate management interface. Select the connection or backend setting and enter the controller information rather than the proxy information.
| Dashboard field | Value for this example | Common mistake |
|---|---|---|
| API host or address | 127.0.0.1 |
Entering the proxy server address instead of the local Clash address |
| API port | 9090 |
Using the mixed port, such as 7890 |
| API base URL | http://127.0.0.1:9090 |
Adding an incorrect path or using HTTPS when TLS is not configured |
| Secret or token | The exact configured secret | Including the words Bearer when the dashboard adds them automatically |
Some dashboards ask for a complete address such as http://127.0.0.1:9090. Others split the host and port into separate fields. Follow the format requested by the interface. If a dashboard asks for a token, enter the secret itself unless its documentation explicitly requires an authorization header. Many dashboards generate the header Authorization: Bearer your-secret automatically.
Do not use https:// for a default local controller unless HTTPS has been configured separately. The standard external controller is usually an HTTP API bound to localhost. Adding HTTPS to a plain HTTP listener causes a protocol mismatch, often reported as a failed connection or a TLS error.
After saving the connection, refresh the dashboard and check a low-risk read-only view such as the version, configuration summary, proxy list, or traffic panel. If the dashboard displays the active groups and current connections, the controller connection is working. Changing a proxy group is a write operation, so perform it only after confirming that the dashboard is connected to the intended Clash Verge Rev instance and not to another local client.
If several Clash clients or core processes are installed on Windows, verify the identity of the connected instance. Two programs can use different proxy ports but accidentally share an expected controller port, or a stale background process can continue answering requests. Compare the version response, active configuration, and Clash Verge Rev log with the dashboard display before assuming that a command was sent to the correct process.
Troubleshoot Failed Connections and Authentication
When the dashboard cannot connect, return to the three-layer test: configuration, listener, and authentication. First confirm that the active configuration contains the intended controller address and port. Then confirm that Windows reports the port as listening. Finally test the API with the exact secret. This sequence avoids changing several variables at once.
Connection refused or no response
A refused connection usually means that no process is listening at the selected address and port. Check whether the core is running and whether the profile was successfully loaded. Inspect the Clash Verge Rev log for YAML parsing errors, a port binding failure, or a message indicating that the core exited. If the configuration uses external-controller: 127.0.0.1:9090, test the same address rather than the computer’s LAN IP.
If the port is occupied, choose another port and reload the core. If the application reports that the configuration is invalid, check indentation, duplicate keys, quotation marks, and whether the setting was placed in the top-level configuration. A valid example has both keys aligned at the same level:
external-controller: 127.0.0.1:9091
secret: "a-long-unique-secret"
Authentication failed
An authentication failure means that the request reached the API but did not provide the expected secret. Copy the secret carefully, including uppercase and lowercase characters. Check for an accidental leading or trailing space, and determine whether the dashboard expects a raw token or a complete authorization value. After changing the secret, reload or restart the core and update the dashboard entry at the same time.
Do not confuse the controller secret with a subscription password, node password, or proxy server credential. These credentials belong to different parts of the configuration. A proxy node may connect successfully while the controller rejects the dashboard, and changing a node password will not fix a controller authentication error.
Remote device cannot connect
If the dashboard runs on another device, 127.0.0.1 points to that other device, not to the Windows computer running Clash Verge Rev. Remote management requires the controller to bind to an address reachable from the remote device, such as the Windows machine’s private LAN address or an appropriately restricted interface. It may also require a Windows Defender Firewall inbound rule for the selected port.
Remote access should not be enabled casually. Use a strong secret, restrict the firewall rule to a trusted private network or specific source addresses, and avoid exposing the controller directly to the public internet. If remote control is not necessary, keep the binding on 127.0.0.1 and use a dashboard running on the same computer.
Dashboard loads but data is incomplete
A dashboard can reach the controller while still showing missing panels or unsupported controls. This can happen when the dashboard expects a different API version, when the running core is not Mihomo, or when the selected client exposes only part of the API. Check the core version shown by /version, update the dashboard when appropriate, and avoid assuming that every Clash-compatible interface supports every Mihomo feature.
Finally, check whether Windows has more than one Clash-related process, whether a VPN or security product is intercepting local HTTP requests, and whether the browser has cached an old dashboard configuration. Close unused clients, repeat the direct PowerShell test, and reconnect the dashboard using the current host, port, and secret. A stable setup should use one clearly identified core, one controller port, a private secret, and a dashboard connection that matches those values exactly.