How To Enable External Controller In Mihomo Party On Windows

What the External Controller Does

Mihomo Party is a Windows interface for the mihomo core. The interface manages profiles, proxy groups, modes, logs, and system proxy settings, while the core performs the actual routing work. The external controller is the HTTP API exposed by that core. A compatible dashboard can connect to this API and read runtime information or send commands without replacing Mihomo Party itself.

Once the controller is enabled, a dashboard can usually display the active profile, current proxy mode, proxy-group selections, connection records, traffic statistics, memory usage, and core status. Depending on the dashboard and the permissions exposed by the API, it may also switch a proxy group, change the global mode, close a connection, or reload the configuration. This is useful when the dashboard offers a clearer view than the built-in client, or when several devices need to inspect one running mihomo instance.

The controller is not the same thing as the Windows system proxy. The system proxy tells applications where to send HTTP or SOCKS traffic. The external controller is a management interface for mihomo. It normally listens on an address and port such as 127.0.0.1:9090, and dashboard requests are sent to that API address. Turning on the Windows proxy does not automatically enable the controller, and enabling the controller does not automatically route browser traffic.

Before You Configure Mihomo Party

Start with a current Mihomo Party build that includes the mihomo kernel and an accessible controller setting. The exact wording of the menu can change between releases, because Mihomo Party separates its application settings from the YAML profile loaded by the core. On one build the option may be shown as External Controller; on another it may appear under a general, core, advanced, or API section. The important fields are the controller address, the API secret, and sometimes an external UI or CORS setting.

• Keep Mihomo Party running. The API is provided by the active mihomo process, so a dashboard cannot connect after the client and core have both exited.
• Load a working profile first. An empty profile can still expose an API, but it gives the dashboard no useful proxies or groups to display.
• Record the listening address and port. A typical local value is 127.0.0.1:9090. Do not assume that every build uses port 9090; another application may already occupy it.
• Prepare a secret. Use at least 24 random characters. Avoid spaces, quotation marks, and characters that the dashboard may interpret as part of a URL.
• Choose a dashboard that supports mihomo or Clash-compatible APIs. The dashboard must know the controller URL and the secret. A normal web page cannot manage mihomo merely because both programs are open on the same computer.

Before changing anything, check whether port 9090 is already in use. Open Windows Terminal or PowerShell and run:

Get-NetTCPConnection -LocalPort 9090 -ErrorAction SilentlyContinue

If the command returns an existing listener, select another unused port, such as 9091, in Mihomo Party. A port conflict often looks like an authentication problem because the client fails to start the intended API listener while another process responds on the same port.

Find the Controller Setting in Mihomo Party

Open Mihomo Party on Windows and look through its settings rather than editing a downloaded subscription file immediately. A provider may overwrite profile content during an update, and manually adding a top-level API field to a remote subscription is often the wrong place to make a local desktop change.

1. Launch Mihomo Party and confirm that a profile is selected and the mihomo core is running. If the client has a core status indicator, wait until it reports that the core is ready.
2. Open the application settings. Depending on the release, this may be a gear icon, a settings entry in the side navigation, or a menu item in the tray interface.
3. Search for a section named External Controller, Controller, API, Core, or Advanced. Do not confuse this with the Windows system proxy switch or the TUN switch.
4. Enable the controller and set the address to 127.0.0.1:9090. If that port is unavailable, choose a different local port and use the same value in the dashboard.
5. Enter a strong secret, save the settings, and restart the core if Mihomo Party displays a restart or reload button. Some settings are applied only after the active profile is reloaded.
6. Open the dashboard connection page and enter the controller URL, normally http://127.0.0.1:9090, together with the exact secret. Save the dashboard profile and test the connection.

Some Mihomo Party versions expose the controller through a generated configuration editor instead of a separate switch. In that case, the equivalent YAML is placed at the top level of the active mihomo configuration, alongside keys such as mixed-port, mode, and dns:

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

The indentation and position matter. These are top-level keys, not children of proxy-groups, rules, or dns. If the profile is assembled from providers, use Mihomo Party's local override or patch mechanism when available. Editing the provider's original URL is less reliable because the next update may erase the change.

Connect a Dashboard and Verify It

After saving the controller settings, test the API in layers. First confirm that mihomo is listening, then confirm authentication, and only after that troubleshoot the dashboard. This order prevents a dashboard's generic “connection failed” message from hiding a port, secret, or browser issue.

Step 1: Verify the Windows Listener

Open PowerShell and check the port selected in Mihomo Party:

Test-NetConnection 127.0.0.1 -Port 9090

A successful result includes TcpTestSucceeded : True. If it is false, inspect the Mihomo Party core log, confirm that the controller setting was saved, and check whether the selected port is occupied. If the setting is enabled but no listener appears, reload the profile or restart the core before changing the dashboard.

Step 2: Verify Authentication

The API normally requires the secret in an authorization header. For a local test, PowerShell can request the version endpoint. Replace the placeholder with the secret configured in Mihomo Party:

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

A successful response should contain version information from the running mihomo core. Do not paste the real secret into screenshots, support tickets, or public logs. If the response is an unauthorized error, compare the secret character by character and check that the dashboard is connecting to the same port. A blank secret in the dashboard is not equivalent to a disabled secret on the core.

Step 3: Add the Dashboard Profile

In the dashboard, create a new connection and enter the local API URL, such as http://127.0.0.1:9090. Enter the secret in the dedicated authentication field, not as an extra path segment. If the dashboard asks for a controller address without a protocol, follow its format; some interfaces expect 127.0.0.1:9090, while others require the complete http:// URL.

Once connected, check that the dashboard can read the active configuration and proxy groups. Select a harmless group change, wait for the status to update, and confirm the same selection in Mihomo Party. Avoid testing by repeatedly changing modes or terminating connections, because those actions can interrupt active downloads or meetings.

Step 4: Test an Integrated Web Dashboard

If the dashboard is served by mihomo rather than installed as a standalone Windows application, the configuration may also need an external-ui directory. A representative configuration looks like this:

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

The directory must exist where the running core expects it, and the dashboard's files must be available there. The exact path depends on Mihomo Party's working directory and its profile storage rules, so use the path shown by the client rather than copying a path from another operating system. If the API works but the integrated page is empty, the controller is probably fine and the issue is the UI directory, a missing dashboard asset, or a browser cache.

Secure the External Controller on Windows

The safest configuration for a dashboard running on the same PC is a loopback listener, a non-default local port if convenient, and a strong secret. A different port is not a replacement for authentication, but it reduces accidental collisions and avoids assuming that every local service uses the same endpoint. The secret remains the main access control.

Do not bind the controller to a public interface just to make a dashboard connect. If the dashboard is on another device, first decide whether LAN control is actually necessary. If it is, bind to the computer's private LAN address or a controlled interface where the client supports that choice, keep the mihomo secret enabled, and configure Windows Firewall for the private network profile only. Never create a broad inbound rule for all profiles and all remote addresses without a specific reason.

Remote administration over the internet is a different design problem. The controller is an HTTP management API, not a hardened public web service. Port forwarding on a home router can expose profile information and control functions to scanners and unauthorized users. Prefer a private network path, a trusted VPN, or a local dashboard. Even with a secret, exposing management endpoints directly is unnecessary risk.

• Use 127.0.0.1 for local dashboards.
• Use a long, unique secret that is not reused for the subscription account, Windows login, or another service.
• Use HTTP only on the local machine or a trusted private path. Do not assume that HTTP is encrypted when it crosses a shared network.
• Remove old dashboard profiles from browsers or applications if they store the controller secret in local settings.
• After changing the secret, reconnect every dashboard and verify that an old saved connection no longer works.

Common Problems and Practical Fixes

The External Controller Option Is Missing

Confirm that the running build actually uses mihomo rather than an older or incompatible core. Also check whether the settings page is showing application preferences while the controller belongs to the active profile. Upgrade through the official download channel when appropriate, then restart Mihomo Party and inspect the core information page. A profile provider cannot add API support if the bundled core does not expose it.

The Port Is Open but the Dashboard Cannot Connect

Compare three values: the address configured in Mihomo Party, the URL entered in the dashboard, and the address shown by Get-NetTCPConnection. localhost, 127.0.0.1, and an IPv6 loopback address may not be treated identically by every dashboard. Start with http://127.0.0.1:9090 and use the exact port displayed by the client.

The Browser Shows a CORS Error

A browser dashboard loaded from a different origin may be blocked even when the API itself is healthy. This is a browser security rule, not necessarily a mihomo routing failure. Prefer a dashboard served through the configured external-ui, or use the dashboard's documented CORS option if Mihomo Party exposes one. Do not solve a local CORS problem by allowing every origin permanently on a network-facing controller.

Settings Disappear After a Profile Update

This usually means the change was made inside a provider-managed profile. Move the controller fields to Mihomo Party's local settings or local override layer, then reload the profile and confirm that the generated configuration still contains the expected values. Keep a copy of the local override, but do not publish the secret in a shared configuration file.

External Controller FAQ

A Safe Working Configuration

For most Windows users, the practical setup is simple: run Mihomo Party with a loaded mihomo profile, enable external-controller: 127.0.0.1:9090, configure a unique secret, and connect a local dashboard with the matching URL and token. Verify the listener with PowerShell, verify authentication through the API, and then test a read-only dashboard view before changing proxy groups.

If the dashboard is not connecting, troubleshoot in order: core status, port, address, secret, browser origin, and finally the dashboard's compatibility. Keeping the controller on localhost avoids most firewall and exposure problems. When a LAN listener is required, treat it as a deliberate network-service decision rather than a quick workaround.