Why terminal traffic behaves differently from browser traffic
A browser can appear perfectly healthy while a development tool cannot fetch a dependency, clone a repository, or contact an API. That mismatch is not necessarily a bad proxy node. Browsers often use operating-system proxy settings, browser-specific proxy extensions, or their own DNS behavior. Command-line programs are less consistent: one may read HTTPS_PROXY, another may use a library that ignores it, and a third may start a helper process with a different environment. A successful browser test therefore proves only that one application has a working route—not that every process in your development workflow does.
Clash TUN mode addresses this gap by creating a virtual network interface and routing eligible IP traffic through the Clash core. Instead of asking every application to understand an HTTP or SOCKS proxy, TUN can capture connections from tools that do not offer proxy settings at all. This can be useful for Git over HTTPS, package managers, language runtimes, container clients, and other terminal programs, provided the operating system route and Clash rules allow those connections to be handled.
TUN is not a promise that every request automatically uses the same proxy. Clash still applies DNS behavior, routing rules, process permissions, and outbound group selection. A request to a private Git server may correctly remain direct, while a public package registry follows a proxy group. The useful mental model is that TUN makes more application traffic visible to Clash; your rules and system configuration still decide what happens to it.
This guide focuses on diagnosing and routing developer traffic, not bypassing employer controls or vendor restrictions. If you are new to the tunnel itself, first review the Clash TUN mode deep dive. For rule ordering and matching behavior, see Clash rule routing best practices.
Prepare Clash TUN mode for a development workstation
Start with a working Clash profile and a known-good proxy group. Confirm that the profile loads without YAML errors, the group contains an available outbound, and ordinary proxy traffic succeeds before introducing TUN. If the proxy itself is unhealthy, tunnel capture adds another layer to troubleshoot without fixing the underlying connection. Also note which applications currently control system proxy settings; an old VPN, network filter, or second Clash client can leave routes or DNS configuration behind.
In a maintained Mihomo-based client, find the TUN or virtual interface controls and enable the feature using the client’s supported workflow. Depending on the operating system and client, this may require administrator approval, a helper service, or permission to install a network extension. Approve only the prompt associated with the client you intentionally installed. A toggle that appears enabled in the interface does not, by itself, establish that the virtual interface is active or that the default route points through it.
- Save a baseline. Record the current system proxy state, active VPNs, DNS configuration, and any custom routes. If the workstation is managed, ask the administrator before changing these settings.
- Enable TUN using the client interface. Choose the stack and DNS options supported by your client and operating system. Avoid changing several advanced options at once; one controlled change is easier to verify and reverse.
- Confirm permissions and interface status. Look for a connected or running state in the client, and check the operating system’s network interface list if the client exposes that information. Permission errors, missing helper services, or a competing filter can prevent traffic capture.
- Test one destination at a time. Start with a simple HTTPS request, then test Git or a package manager. Keep the Clash connection log open and compare the destination, matched rule, and selected outbound with the command’s result.
- Check private-network reachability. Verify that local development services, company resources, and other destinations that should stay on the LAN remain reachable. Adjust policy only when you understand why a route is being captured.
The exact labels vary across Clash Verge, Clash Verge Rev, Mihomo, and other clients, so avoid copying a toggle path from a different operating system or release. Some clients expose TUN options in a settings panel; others place them beside system proxy controls. Prefer the application’s documented configuration and status indicators over an old screenshot. If your client reports that it needs elevated permissions, close other network tools first and retry through its normal authorization flow rather than launching random helper binaries.
DNS deserves separate attention. A command can fail before it opens an HTTPS connection if the hostname resolves incorrectly, resolves to an address that does not match the expected routing path, or is intercepted by another resolver. Compare the hostname shown in the Clash log with the name used by the tool, and check whether the profile’s DNS mode is consistent with its TUN settings. Avoid adding broad DNS or IP rules as a first reaction: a narrow exception can solve one service while a broad exception silently changes routing for many unrelated destinations.
Choose TUN, environment variables, or application settings
TUN and explicit proxy configuration solve overlapping but different problems. Environment variables such as HTTPS_PROXY and ALL_PROXY can be convenient for tools that honor them. They make the intended proxy visible in a shell session and can be scoped to a single command or project. However, support differs by program, protocol, and version. A tool may honor the variable for HTTPS downloads but not for SSH, a subprocess, or a request made by its background service.
TUN operates below those application-specific preferences. It can capture eligible connections even when a program has no proxy option, but that broad reach also means the route is less obvious from the command line. When a command fails, you may need to inspect the Clash connection log and operating-system networking state rather than looking only for a proxy variable. TUN can also interact with local networks, virtual machines, container bridges, and other VPN software, so it benefits from careful, incremental testing.
A practical choice depends on the tool and the scope of the problem. Use a tool’s native proxy setting when you need a clear, per-application configuration and the tool supports the required protocol. Use environment variables when a process reliably honors them and you want a temporary shell-level test. Consider TUN when several unrelated programs need consistent network capture or when a command-line client does not support proxy settings. These methods can coexist, but avoid configuring conflicting routes without documenting which layer should take precedence.
| Method | Useful when | What to verify |
|---|---|---|
| Application proxy setting | The program supports a proxy directly and needs a predictable, narrow configuration. | Whether the setting covers downloads, API calls, subprocesses, and the protocols you use. |
| Shell environment variable | You want a quick test or a temporary proxy for tools known to honor the variable. | Variable scope, proxy scheme, authentication handling, and whether child processes inherit it. |
| Clash TUN mode | Multiple applications need capture, or a tool has no usable proxy configuration. | Interface status, permissions, DNS, matched rules, local-network reachability, and outbound choice. |
Do not treat a successful request through one method as proof that another is configured correctly. For example, a shell variable may make curl work even while a Git operation uses a different transport. Conversely, TUN may capture a request even when no proxy variable is present. During diagnosis, record which method is active and change only one layer at a time. That discipline prevents a misleading test in which a tool succeeds through an inherited environment variable while the TUN route you intended to validate is not being used at all.
Verify Git, SSH, Homebrew, pip, and Docker separately
Git over HTTPS and SSH
Git operations can use HTTPS or SSH, and those transports should be tested independently. An HTTPS clone normally connects to the Git hosting service over TLS, but authentication helpers, large-file extensions, and redirects may introduce additional requests. Check the Clash log while testing a small repository operation, then compare the matched rule and outbound with the destination hostname. A successful page load in a browser is not enough to validate Git’s request path or credentials.
SSH is different: it generally uses its own TCP connection rather than an HTTP proxy. If your profile and operating environment support routing that connection through TUN, inspect the connection log and confirm that the SSH destination and port are handled as expected. Some hosting providers offer SSH over an alternate port, but do not change ports or install wrappers until you have confirmed your organization permits the method and the server supports it. A refused connection, an authentication failure, and a route timeout are different problems; use verbose client output to identify which stage fails.
Homebrew and pip
Homebrew operations may contact a package repository, download a bottle from a separate host, and fetch source code from another location. The initial metadata request can succeed while the actual artifact download fails because each hostname is evaluated independently. Watch the connection log through a complete install or update, note every destination that stalls, and check whether redirects lead to a domain your rules do not cover. Avoid adding one catch-all rule just because a single mirror is slow; first establish which host is responsible.
Python package installation has a similar split between index metadata and package files. A pip command may reach the configured index but fail when retrieving a wheel from a storage or CDN hostname. Test the index and the download phase separately, and confirm that a corporate package mirror or project-specific index is not being overridden. If a request succeeds with a shell proxy variable but fails without it, that is evidence about the tool’s proxy handling—not proof that TUN is broken.
Docker and background services
Docker is especially easy to misdiagnose because the command you type may communicate with a daemon that performs network work separately. Depending on the operating system and installation, the daemon may run inside a managed virtual machine, a background service, or a container environment with its own routes. TUN on the host does not guarantee that every daemon-originated request follows the same path as a host terminal process. Check whether the failed operation is an image pull, a build-stage download, or a request made by an application inside the container; each may originate from a different network namespace.
Begin with a small image pull and inspect Clash logs during the request. If no corresponding connection appears, determine whether the daemon’s traffic is outside the host’s captured path before changing rules. If connections appear but fail, compare their destinations and outbounds with a successful host request. Build-time downloads can also use cached layers, so repeat a controlled test only when you understand whether the result came from the network or the cache. Keep daemon proxy configuration and container-level environment settings distinct in your notes.
Troubleshoot common failures and answer frequent questions
If the terminal cannot connect and the Clash log shows no matching connection, start with capture and routing rather than rewriting domain rules. Confirm that TUN is actually running, that the application has the needed operating-system permissions, and that the failing process is on the host rather than inside a VM or separate network namespace. Check for competing VPN clients, endpoint security filters, and stale routes. If a connection appears in the log, inspect its matched rule, selected outbound, DNS result, and final error before deciding which setting to change.
If the command reaches a host but receives an authentication or authorization error, the network path may already be working. Verify credentials, access tokens, SSH keys, repository permissions, and the account selected by the tool. If only downloads fail after metadata succeeds, follow the redirect chain and identify the artifact host. If short requests work but long transfers stall, look at connection stability, timeouts, and the selected outbound rather than assuming that DNS is the cause.
A clean diagnostic sequence is more useful than switching clients or editing a large rule set at random. Close competing tunnel software, reproduce one failure, note the exact command and timestamp, then correlate it with the Clash log. Change one setting, repeat the same test, and record whether the destination, matched rule, or outbound changed. When troubleshooting a managed workstation, share these observations with the network administrator instead of attempting to defeat a policy or disable required security controls.
Frequently asked questions
Do I still need HTTPS_PROXY when TUN is enabled? Not always. TUN can capture eligible traffic without an application proxy variable, but a tool may still use its own proxy configuration or bypass the expected route. Test the specific command and check the connection log before removing an existing setting.
Why does browser access work while Git or pip fails? The browser may use system proxy settings that the terminal program ignores. The command may also contact different hosts for authentication, metadata, or file downloads. Compare the actual destination and route for each application rather than treating “the website opens” as a universal connectivity test.
Can TUN automatically proxy Docker image pulls? Not in every setup. Docker’s daemon may run in a VM, service, or separate network environment, so its traffic may not share the host shell’s route. Check the daemon architecture and look for the image registry connection in Clash logs before changing the profile.
Should I route every development hostname through one proxy group? Usually not as a starting point. Keep local and private destinations consistent with your network policy, and use explicit rules for services that require a particular route. Review rule order and logs so a broad catch-all does not override a more specific decision.
Compared with per-tool proxy wrappers, which can require separate setup for Git, Python, Node, and background services, Clash TUN offers a more consistent capture point—but it still requires sound rules, permissions, and verification. Some lightweight clients expose fewer diagnostics, while a Mihomo-based Clash V.CORE workflow can make profile selection and connection inspection easier to manage as your toolchain grows. If you want to test terminal routing with a maintained Clash client, download Clash V.CORE and begin with one reproducible CLI request before expanding the setup to the rest of your development environment.