Clash Nyanpasu First-Time Setup: Installation, Initial Configuration, and Common Issues

Before You Install: Client, Core, and Configuration

Clash Nyanpasu is a desktop GUI client. An open window only confirms that the interface is running; network requests also require an active proxy core, a valid configuration, and a traffic entry point connected to the core. For your first setup, follow this order: install → import a configuration → start the core → test the proxy manually → enable the system proxy. Leave TUN off for now.

• Client: Manages profiles, the settings interface, logs, and system integration.
• Core: Reads the configuration and handles connections. mihomo is often referred to as the Clash Meta core; available options depend on the client release.
• Profile: A local configuration or remote subscription entry. Configurations usually include proxies, proxy groups, DNS, and routing rules.
• Proxy entry point: For example, a local HTTP/SOCKS listening port or a TUN virtual network interface. Each entry point handles traffic differently.

Install on Windows, macOS, and Linux

Windows: Check Your System Architecture and Permissions

1. Open Settings → System → About and check System type. Choose the matching x64 or ARM64 build; the Windows 11 label alone does not tell you which architecture you have.
2. Choose a package from the current release on the download page. Install and launch it normally, and note the full text of any missing-dependency or Windows security warnings.
3. For the first launch, use a standard user account to import a configuration and test the local port. Install a service or grant permissions only if you need service mode or TUN and the client prompts you to do so.
4. If you see a WebView2 error, check the runtime requirements in the instructions for your release. For offline devices, prepare a runtime installer for the correct architecture. Don’t mistake an interface dependency error for a subscription problem.

Check the Windows system proxy under Settings → Network & internet → Proxy. During testing, don’t run two clients that both change the system proxy: the one that writes its settings last may overwrite the other client’s address and port.

macOS: Check Your Chip, Then Review Security Alerts

1. Open the Apple menu → About This Mac and check Chip or Processor. Choose the matching ARM64 build for Apple silicon or the x64 build for an Intel Mac. Use the download page to confirm whether a universal build is available.
2. If you downloaded a disk image, open it and copy the app to Applications. Launch it from there rather than running it from the mounted image long-term.
3. If macOS blocks the app from opening, first verify its source and compatibility. Then follow the options actually shown under System Settings → Privacy & Security. Don’t disable system-wide security just to run one app.
4. Grant permissions only for features you intend to use. A regular local proxy listener and system proxy do not require you to approve every network extension or Keychain request.

On recent macOS versions, check proxy status under System Settings → Network → your current network service → Details → Proxies. The labels may vary slightly by version. If an authorization dialog keeps appearing, note the requester and what it is asking for before deciding whether it relates to service installation, network settings, or credential access.

Linux: Choose the Right Package, Architecture, and Desktop Environment

Run uname -m to check your architecture: x86_64 usually means x64, and aarch64 means ARM64. Then choose an installation method based on your distribution and the files available in the current release. Installing a package through your package manager and running an AppImage are different approaches; don’t mix their commands.

• Distribution package: Install it with your system package manager and review the dependency resolution output. If a GUI runtime library is missing, install the dependency identified by the error.
• AppImage: Make the file executable first. If the log reports a FUSE issue, follow the instructions for your distribution and build. Don’t work around it by routinely running the graphical app as root.
• Desktop system proxy: GNOME, KDE, and terminal apps handle proxy settings differently. Even if the client says the system proxy is enabled, check whether the target app actually uses it.

If the Linux desktop app launches without opening a window, start the installed executable from a terminal and keep the output. Missing shared libraries, an unavailable display session, and a core configuration error occur at different layers; start with the earliest clear error.

Import a Configuration: Start with a Working Profile

On the client’s Profiles page, add a local YAML file or remote subscription. Wait for the import to finish, then set that profile as active. Button labels vary by release—such as “Configuration,” “Profiles,” or similar—but the goal is to create and activate a profile, not just save a link in a text field.

1. Make sure your subscription provider supports Clash YAML or a format recognized by the current core. A link opening in a browser doesn’t mean its response is ready to import.
2. Check that the downloaded content is actually a configuration. A sign-in page, expired-subscription notice, HTML error page, or list of proxies without configuration details can cause parsing errors or leave proxy groups missing.
3. After activating the configuration, check the logs for YAML parsing errors, startup failures caused by unknown fields, or rules that reference nonexistent targets.
4. Open the Proxies or proxy groups page and confirm that selectable proxies are available. If a group contains only DIRECT, inspect the configuration instead of repeatedly toggling the system proxy.

A subscription URL may contain an access token. Redact URL query parameters, proxy passwords, and controller secrets before sharing screenshots, asking for help, or copying logs. Remote subscriptions replace the original content when updated; whether local edits persist depends on the client’s configuration handling. For long-term customization, use an override method supported by your release.

Core and Ports: Check the Values Actually in Use

For a first installation, use the core bundled with your client release. If you need mihomo-specific fields, first confirm that the running core and its version support them. After switching cores, reload the configuration and check the new process’s startup log. Selecting a core in the interface does not prove that it started successfully.

This YAML snippet illustrates how the fields relate; it is not a complete subscription with proxies and rules. Don’t replace your entire configuration with it. Client overrides may change the final values, so check the active configuration and logs.

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info

Keep the control interface separate from the traffic entry point. For example, a configuration might set the control interface to 127.0.0.1:9090; this address manages the core and does not forward web requests. Don’t bind the control interface to all network interfaces unless you have appropriate access controls in place.

Test Connectivity: Manual Proxy, System Proxy, and TUN

Step 1: Test the Port with an Explicit Proxy

Choose a working proxy group and proxy first, then send a single request explicitly through the local proxy. The command below uses a standard HTTPS example domain. A successful response confirms only that this request completed—not that every site, protocol, or app is covered. On Windows, use curl.exe to avoid PowerShell environments where an alias with the same name can affect how arguments are parsed.

# Windows PowerShell
curl.exe -I --proxy http://127.0.0.1:7890 --connect-timeout 10 https://example.com

# macOS / Linux
curl -I --proxy http://127.0.0.1:7890 --connect-timeout 10 https://example.com

If the connection to 127.0.0.1 fails, check the port and process first. If the proxy connection is established but then times out, use the logs to investigate the proxy connection, TLS, DNS, and rule result. An HTTP error status doesn’t mean the local proxy failed; distinguish connectivity from the response returned by the destination site.

Step 2: Enable the System Proxy and Check Connections

Once the explicit proxy test passes, enable the client’s system proxy. Restart the test app or open a new connection, then check the client’s connection list for the destination domain, matched rule, and final policy. The system proxy affects only apps that follow system settings. Existing connections, some terminal tools, and apps that manage their own networking may not be affected by the toggle.

The HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY environment variables can also change how terminal requests are routed. When troubleshooting one program, check its own proxy settings and environment variables before assuming the system proxy is broken.

Step 3: Enable TUN Only If Needed

TUN uses a virtual network interface and routing to capture traffic, which can help when the system proxy doesn’t cover a particular use case. It often requires extra permissions or service support and involves DNS, routing, and interface selection. If a regular browser test hasn’t passed yet, leave TUN off so proxy and routing issues don’t get mixed together.

• Turn off other VPNs or TUN clients first to avoid conflicting routes and DNS interception.
• Follow the current release’s prompts to install the service or grant permissions, then check the logs to confirm that the virtual interface was created.
• Test regular websites, local network addresses, and the apps you need to route. Don’t rely only on whether the TUN toggle is on.
• If all network access stops, turn TUN off first and confirm that connectivity returns. Then check routing and DNS settings rather than layering on more changes.

Troubleshoot Startup Failures and Port Conflicts

The Window Won’t Open: Check the Interface Layer First

First, check the installer’s architecture, supported OS versions, and installation path. On Windows, review dependency warnings; on macOS, check security alerts; on Linux, inspect terminal output. The core hasn’t reached the listening stage yet, so changing subscription rules usually won’t fix an interface startup failure. If behavior changed after an upgrade, keep a backup of the original configuration and note the client version and when the error occurred.

The Window Opens, but the Core Fails: Check the First Error

If the log shows address already in use or an error involving bind, identify whether the conflict is with the proxy port, DNS listening port, or control interface. The commands below check the example proxy port 7890; replace it with the number shown in your error.

# Windows PowerShell: find the listening process PID
Get-NetTCPConnection -LocalPort 7890 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess

# macOS: find the TCP listener
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux: check listening sockets; process details may require extra permissions
ss -ltnp 'sport = :7890'

1. Use the PID to identify the process. Prefer closing a duplicate instance of the client normally; don’t terminate an unknown system process.
2. If both programs need to run, change one proxy listener to an unused port, such as 7891.
3. After changing the port, update the system proxy, browser, and terminal’s explicit proxy address, then reload the configuration.
4. Check the listening status again, then repeat the connection test. Don’t change only the value shown in the interface while leaving the active configuration untouched.

If the log reports a YAML line number, indentation, or proxy group name error, fix the configuration first. YAML uses spaces for indentation, and fields at the same level must align. Policy names referenced by rules must match existing group names. See the YAML configuration reference for field details.

The Client Starts, but You Can’t Connect: Check Each Link

Check in this order: is the app using the proxy → is the local port listening → which policy matched the rule → can the proxy connect → is DNS working? A single latency test can’t represent the entire connection path. In rule mode, a request may match DIRECT and bypass the proxy you selected manually.

What to Keep After Initial Setup

• Record versions and settings: Client version, core version, active profile name, proxy port, and whether TUN is enabled.
• Check what happens on exit: Quit the client normally and confirm that the system proxy is restored. If an unexpected exit leaves a proxy address behind, turn it off manually in your system network settings, then test connectivity.
• Enable startup on login last: First quit and relaunch the client, then verify connectivity. Enable startup on login only after that, to avoid repeatedly hitting the same error after signing in.
• Protect configuration backups: Exported configurations may contain subscription tokens and proxy credentials. Store them only in a trusted location; don’t post complete profiles in public forums.

A successful first setup doesn’t mean every toggle is on. It means the active configuration loads, the proxy entry point is listening, and you can confirm how the target app’s requests are routed. Keep a verified baseline configuration, then add custom rules, overrides, or TUN settings one at a time to make troubleshooting and rollback easier.