OpenAI Codex CLI With Clash Verge: Setup Guide For China

Why OpenAI Codex CLI Needs a Coherent Network Route in China

OpenAI Codex CLI is presented as a terminal tool, but its workflow is not limited to one request or one hostname. A normal session may involve installing the package, downloading dependencies, opening a browser-based sign-in flow, exchanging credentials, checking account state, and maintaining long-lived HTTPS connections for model responses. Each stage can behave differently on a developer network in China. A package registry may load slowly, the browser may complete authentication but the CLI may not receive the final result, or a short API request may succeed while a streaming response stalls after several seconds.

This is why installing Clash Verge and simply selecting a fast-looking node is not always enough. Clash evaluates connections according to the active mode, DNS behavior, rules, and the application’s own proxy support. Codex traffic may come from a terminal process, a browser callback, a package manager, and background helpers. If those components leave through different paths, the symptom is often misleading: a login window appears normal, yet the terminal reports an authentication error; npm reaches the registry, yet the CLI cannot contact its service; or the first prompt works while a larger response times out.

The practical objective is not to force every connection through an unfamiliar route forever. It is to create a predictable troubleshooting window in which package downloads, authentication, and API traffic use a compatible policy. Once the workflow is stable, you can narrow the rules and return domestic services to DIRECT where appropriate. This approach is easier to maintain than repeatedly changing nodes whenever Codex prints a generic network error.

Prepare Clash Verge Before Installing Codex CLI

Start with a maintained Clash Verge installation and a profile supplied by a provider you trust. The profile should load successfully, display proxy groups, and expose a local listener such as a mixed port. Do not begin by editing dozens of rules. First confirm that Clash Verge itself is healthy: the tray or window should show the core as running, the profile should have finished parsing, and the log view should not be filled with configuration errors. A broken YAML document can look exactly like a remote service outage when the real problem is that no listener started.

Record the local port shown under Clash Verge’s settings. Common examples include 7890, 7897, or another provider-defined value, but you should never copy a port from a tutorial without checking your own interface. The protocol matters too. A mixed port can accept both HTTP-style proxy requests and SOCKS5 connections, while an HTTP-only listener may reject a SOCKS URL and a SOCKS-only listener may not understand an HTTP proxy handshake.

Close competing VPN clients, older Clash forks, browser proxy extensions, and corporate tunnel agents during the first test. Two applications can both claim to be the system proxy while only one receives traffic. Similarly, a previously exported environment variable may point to a dead port even after you change Clash Verge’s listener. Establish one known baseline before adding TUN mode, custom DNS, or a second proxy layer.

You should also decide whether Codex needs terminal-only routing or whether the browser sign-in stage must use the same exit. For a first setup, consistency is usually more valuable than aggressive optimization. Letting Chromium authenticate through one route while the CLI uses another creates unnecessary variables, especially when a callback, token exchange, or device confirmation is involved.

Choose Global, Rule, or TUN Mode Deliberately

Clash Verge normally gives you a choice between a rule-oriented mode, global proxy mode, and sometimes a direct mode. The names and controls can vary by core and application version, so focus on the behavior rather than the label. Rule mode sends traffic according to the profile’s rule providers and final match. It is the best long-term choice when the profile correctly classifies the domains used by your development tools. Global mode sends most compatible traffic through the selected proxy group and is useful for a short diagnostic test. Direct mode is valuable as a control experiment, but it will not solve an unreachable external service.

A sensible sequence is to select one stable proxy group, enable global mode briefly, and test the smallest useful action. If Codex installation or sign-in becomes reliable in global mode, the node and local listener are probably functional. You can then switch back to rule mode and inspect which hostname was treated differently. If global mode fails in exactly the same way, changing YAML rules will not repair a dead node, an invalid subscription, a certificate problem, or a local port conflict.

TUN mode is a different layer. It captures traffic from applications that do not honor system proxy settings or shell variables, including some native clients and child processes. This can be convenient, but it introduces virtual-interface permissions, DNS interception, route precedence, and possible conflicts with other VPN software. Do not enable TUN merely because the terminal command looks stuck. Use it after you have tested explicit proxy variables and understand whether the Codex process actually bypasses them.

The following comparison helps frame the choice during setup:

Install Codex CLI and Configure the Terminal

Once Clash Verge is running, install Codex CLI using the package command documented by OpenAI for your platform. Keep the installation command separate from the first authentication test. This separation gives you a useful checkpoint: if the package cannot be downloaded, investigate the package manager and registry path before blaming account credentials. Use a supported Node.js version, inspect the package manager’s error output, and avoid repeatedly changing registries without recording the original value.

In a shell that supports standard proxy variables, point the process at the HTTP-compatible local listener. A typical temporary test looks like this:

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7890

Replace the port with the value shown in Clash Verge. On Windows PowerShell, the equivalent variables use $env:HTTP_PROXY, $env:HTTPS_PROXY, and $env:ALL_PROXY. Do not assume that every client library honors all three variables. Some Node packages prefer HTTPS_PROXY, some tools interpret ALL_PROXY differently, and some native processes ignore shell configuration completely. Set variables for the current terminal first rather than writing them permanently to your profile before you know which format works.

Test the listener with a harmless request before launching an interactive agent. For example, use a command-line HTTP client to request an official documentation page or another endpoint that your organization permits. Observe the Clash Verge connection log at the same time. A request that succeeds but produces no Clash log entry may have used a browser cache, a direct route, or a different proxy entirely. A request that appears in the log with a rejected connection gives you a much narrower place to investigate.

After installation, start Codex CLI according to its current official documentation and complete sign-in in the browser or terminal flow it presents. Keep the original terminal open. If a browser window appears, do not immediately switch browsers or add a proxy extension. First determine whether the CLI is waiting for a callback, whether the browser reached the authorization page, and whether Clash Verge logged the corresponding account or identity hostnames. A successful visual login is not proof that the terminal completed its token exchange.

Route Authentication, Package, and API Traffic Together

Rule-based routing works best when you think in traffic families rather than one guessed hostname. Codex may contact OpenAI account and API infrastructure, package registries, documentation hosts, telemetry endpoints, and redirect destinations. Exact hostnames can change as products evolve, so avoid copying an unverified list from a forum and treating it as permanent truth. Use the Clash Verge connection log during an installation or sign-in attempt to identify the actual domains, then classify only the domains you can verify.

For a temporary test, a dedicated policy group can be easier to reason about than a large general-purpose group. Give the group an unambiguous name, select one stable node, and route the observed OpenAI and related development endpoints through it. Keep local package mirrors and domestic services on DIRECT only after confirming that they do not participate in the failing transaction. A broad rule such as a generic suffix match can unintentionally capture unrelated services, while a rule placed below MATCH will never be reached.

DNS deserves equal attention. In rule mode, a hostname may resolve through a domestic resolver while its HTTPS connection uses a proxy, or fake-IP behavior may cause a tool to display an address that does not resemble the real service. These behaviors are not automatically wrong, but they complicate diagnosis. During the first successful baseline, avoid changing DNS mode and proxy mode at the same time. Record whether the failure occurs during name resolution, TCP connection, TLS negotiation, or the application’s response phase.

Do not route loopback callback addresses through a remote proxy. Browser-based authentication often depends on a local redirect such as 127.0.0.1 or localhost. If a rule or environment setting sends local callback traffic away from the machine, the browser can display “success” while the CLI waits indefinitely. Localhost, private network ranges, and the local Clash listener should remain reachable directly unless your organization has a specific reason to manage them differently.

Hands-On Test Plan in Clash Verge

Use a short, repeatable test instead of launching a large coding task immediately. The following sequence is designed to isolate the layers one at a time:

1. Check the core: Open Clash Verge and confirm that the selected profile is active, the core is running, and the intended proxy group has a usable node.
2. Check the listener: Verify the local mixed or HTTP port, then run a small permitted HTTP request with the same proxy variables that Codex will inherit.
3. Check package access: Install or update Codex CLI while watching the connection log. Separate registry errors from authentication errors and save the exact message.
4. Check browser sign-in: Start the Codex authentication flow without changing browsers. Confirm that both the authorization page and the local callback complete.
5. Check a small prompt: Submit a short request that produces a modest response. A small successful response proves more than a long prompt that fails after several minutes.
6. Check streaming stability: Repeat the request and watch whether the connection remains open. If short requests work but streaming fails, investigate idle timeouts, node quality, and competing tunnels rather than reinstalling the CLI.

Keep a simple record containing the Clash Verge mode, selected group, local port, shell variables, time of test, and the relevant log lines. Change one variable per test. For example, switch from rule mode to global mode without changing the node; then restore rule mode and change only the rule. This method turns “Codex is broken” into a comparison between observable states. It also makes it easier to explain the issue to a provider or an administrator without exposing access tokens.

Never paste API keys, OAuth codes, subscription URLs, or full authorization headers into logs, screenshots, issue trackers, or chat rooms. Mask query tokens and redact account identifiers before sharing diagnostics. A proxy log is useful because it shows domains, policies, and connection timing; it does not need to contain credentials to prove that a route failed.

Diagnose Common Codex CLI and Clash Verge Errors

If package installation reports a timeout, inspect the registry hostname and tarball destination rather than assuming the main API is unavailable. Package managers can use one host for metadata and another for the archive, so a partial download may indicate that only one leg is misrouted. If the error is a certificate or TLS message, check the system clock, local security software, and whether HTTPS interception is enabled. Do not disable certificate verification as a casual fix; it can hide a serious trust problem.

If the browser sign-in succeeds but Codex remains unauthenticated, inspect the callback first. Confirm that the terminal process is still running, that localhost is not being proxied remotely, and that the browser can reach the local redirect. Then compare the identity-related connection entries in Clash Verge with the route used by the CLI. Divergent exits can invalidate a session even when both individual pages load.

If authentication works but model requests fail, examine the API connection separately. A rule may match the account hostname correctly while sending the API hostname to DIRECT, a stale group, or a node with poor long-connection performance. Compare a short request with a streaming request. Repeated connection resets, long pauses between chunks, or failures only after a fixed duration often point to transport quality rather than an invalid prompt.

If Clash Verge shows no matching connection at all, the Codex process may not honor your environment variables. Check how the process was launched, whether a package manager created a child process with a clean environment, and whether TUN mode is required for that particular binary. On Windows, also check whether a terminal opened before the environment variables were changed. Restarting the shell can be more useful than reinstalling the package.

Finally, test without overlapping network tools. Corporate VPNs, endpoint security filters, transparent gateways, and browser extensions can alter DNS or TLS independently of Clash Verge. A clean test on an approved network gives you a meaningful baseline; a test performed through three stacked tunnels usually produces a log full of symptoms rather than a single cause.

Maintain a Stable Developer Workflow

Once Codex CLI works, resist the temptation to freeze every setting forever. Profiles, provider nodes, package dependencies, and vendor endpoints change. Export or back up the working Clash Verge profile, note the selected policy group, and make changes in small batches. When updating a rule provider, review the resulting matches for your development domains instead of assuming that a successful refresh means the policy is still appropriate.

Keep terminal configuration explicit. A project-specific launcher or documented shell command is easier to audit than a forgotten global variable that affects Git, package managers, browsers, and unrelated tools. When you finish a troubleshooting session, decide whether the variables should remain active. If not, unset them and return to your normal workflow. The same principle applies to TUN mode: enable it when an application genuinely needs capture, and disable it when explicit proxy settings already provide the required behavior.

Use a stable node for development sessions rather than selecting a new endpoint on every command. Authentication, package downloads, and streaming APIs benefit from consistent egress and predictable latency. If you need automatic failover, validate that the replacement nodes support long-lived connections and the required destinations; a group that wins a quick latency probe may still perform poorly during a sustained model response.

Compared with browser-only proxy extensions, Clash Verge gives you a clearer view of terminal traffic, policy matches, local listeners, and TUN capture, while lightweight one-purpose proxy tools often hide the route that a child process actually takes. Some older GUI clients also make profile inspection or rule debugging unnecessarily difficult. For Codex CLI on a China-based developer workstation, Clash V.CORE offers a more transparent foundation for consistent modes, observable connections, and controlled rule changes, so you can download Clash V.CORE and build the workflow around evidence instead of repeated guesswork.