Codex CLI With Clash Verge: Setup Guide For Reliable Access
Understand How Codex CLI Reaches the Network
Codex CLI brings AI-assisted development into the terminal, so its network behavior is different from opening an AI website in a browser. A browser may use the operating system proxy, a browser extension, or a built-in secure connection method. Codex CLI, by contrast, runs as a command-line process and usually depends on its own authentication flow, HTTPS requests, DNS resolution, and environment variables. If those components are not routed through the same Clash Verge instance, login may fail even when ordinary websites load normally.
The first step is to separate the application layer from the proxy layer. Codex CLI is responsible for reading its account or API configuration, sending requests, and displaying responses. Clash Verge provides the local HTTP, SOCKS5, mixed, or TUN entry point, then applies its selected mode, rules, proxy groups, and nodes. A successful connection requires both sides to be configured correctly: Codex CLI must send traffic to a reachable local listener, and Clash Verge must have a rule and an available proxy for the requested destinations.
Do not assume that enabling System Proxy in Clash Verge automatically covers every terminal command. System proxy settings are respected by many graphical applications, but command-line programs vary. Some read HTTP_PROXY and HTTPS_PROXY; some support only a command-line option; some use a language runtime or package manager with separate proxy settings; and some ignore proxies completely unless TUN mode is enabled. This is why testing the terminal path directly is more useful than repeatedly changing nodes.
Explicit proxy
Codex CLI or the shell is told to use a local address such as 127.0.0.1:7890. This is usually the easiest path to inspect and troubleshoot.
TUN mode
Clash Verge captures more system traffic at the network layer, including applications that do not understand HTTP or SOCKS proxy variables.
Rule mode
Clash evaluates rules from top to bottom and sends a matching request to a proxy group, DIRECT, or REJECT.
Prepare Clash Verge Before Importing a Profile
Install a current Clash Verge build that includes a maintained Mihomo-compatible core, then open the application and confirm that the core starts without an error. The exact menu names can differ between Clash Verge and Clash Verge Rev, and they may also change between releases. Look for sections named Profiles, Settings, General, Proxies, Logs, or Connections. The purpose is more important than the exact label: you need one active configuration, one local listener, and a visible runtime status.
Before adding a subscription, check whether another proxy application is already running. Two clients may compete for port 7890, 7891, or the system proxy switch. Close old Clash clients, VPN applications, terminal proxy wrappers, and other network tools temporarily. If a port is occupied, Clash Verge may choose another port, fail to start the core, or appear active while terminal commands continue to use the old listener.
Open the profile or configuration area and import the subscription URL provided by your service. Use the application’s supported import method instead of pasting a URL into an unrelated YAML field. After the profile downloads, select it and wait for the configuration to become active. Check that proxy groups contain usable nodes and that the group selected for general traffic is not empty.
A subscription URL is sensitive account information. Do not place it in public screenshots, shell history, issue reports, or shared configuration files. If the URL contains an access token, anyone who obtains it may be able to retrieve your configuration. For the same reason, avoid publishing API keys, authentication cookies, or complete logs that include request headers.
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
The example above illustrates a local-only mixed listener. It is not a universal configuration that should be copied without checking the active profile. allow-lan: false prevents other devices from using the listener through the LAN, which is a safer default for a single computer. If your imported profile uses separate listeners, record the actual HTTP and SOCKS5 ports shown by Clash Verge rather than relying on the example value.
Select a Profile, Mode, and Proxy Group
Once the profile is active, open the proxy page and identify the group that handles unmatched or general traffic. Many profiles use names such as PROXY, Proxy, GLOBAL, or a provider-specific label. The name itself has no special meaning. What matters is whether the group contains nodes, whether its current selection is available, and whether the rules actually direct Codex-related requests to that group.
Use Rule mode as the normal starting point
Rule mode is generally the most practical choice for development. It allows local services, private domains, package mirrors, and ordinary domestic traffic to remain direct while selected destinations use a proxy group. This reduces unnecessary latency and avoids sending credentials or internal development services through a remote node. However, a rule-based profile is only as good as its rule list. If the required API, authentication, or update domain is missing, the request may fall through to MATCH and use an unexpected policy.
Global mode can be useful as a short diagnostic test. If Codex CLI fails in Rule mode but works in Global mode, the local listener and selected node are probably functional, while the rule set or DNS behavior needs review. Do not leave Global mode enabled permanently without considering package registries, private repositories, local services, and sensitive traffic.
Direct mode bypasses proxy routing for ordinary requests. It is useful for confirming whether a destination is reachable without Clash, but it should not be mistaken for a fix. If authentication succeeds only after switching to Direct, the issue may be an unsuitable node, a bad rule, or a remote service that blocks the selected exit address.
Treat DNS and TUN as separate decisions
DNS can affect whether a hostname resolves to the expected address before the connection reaches the proxy. A profile may use fake-IP, redirection, or another DNS strategy, and different kernels support these options differently. If Codex CLI reports a name resolution error while a direct IP test behaves differently, inspect Clash Verge’s DNS status and logs instead of changing the API key.
TUN mode is helpful when Codex CLI, its authentication helper, or a subprocess does not honor proxy environment variables. It normally requires elevated permissions and may conflict with another VPN, security product, or virtual network adapter. Start with explicit proxy variables first because that path is easier to verify. Enable TUN only when the application cannot be configured to use the local listener, or when you need broader coverage for subprocesses and non-HTTP traffic.
Configure the Terminal Environment for Codex CLI
For a command-line program, the clearest first test is to set proxy variables in the same terminal session where Codex CLI will run. Use the protocol supported by the local listener. An HTTP or mixed port is commonly used with HTTP_PROXY and HTTPS_PROXY; a SOCKS5 listener can be exposed through ALL_PROXY if the particular application and its underlying libraries support it.
Windows PowerShell
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="http://127.0.0.1:7890"
$env:NO_PROXY="localhost,127.0.0.1,::1"
curl.exe -I https://example.com
PowerShell environment variables apply to processes started from that session. If Codex CLI is launched from a new terminal, an IDE task runner, or a separate integrated terminal, repeat the configuration there or configure the environment in that tool. Windows variable names are commonly written in uppercase for compatibility, although the exact case behavior depends on the program.
macOS and Linux shells
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,::1
curl -I https://example.com
Place persistent exports only in the shell startup file that your terminal actually loads, such as a profile or shell-specific configuration file. Avoid storing secrets in the same file. A proxy variable normally contains only the local Clash address, not an account token, but review the value before sharing command output.
Some tools interpret HTTPS_PROXY as the proxy used to reach an HTTPS destination, not as an instruction to create an HTTPS connection to the local proxy itself. Therefore http://127.0.0.1:7890 is often correct when the local mixed port accepts HTTP CONNECT. If a particular client documents a SOCKS URL, use the documented format, such as socks5://127.0.0.1:7891. Do not assume that every program supports every proxy scheme.
Before running Codex CLI, inspect whether old variables are already present:
env | grep -i proxy
On PowerShell, use:
Get-ChildItem Env: | Where-Object Name -match "PROXY"
Old values pointing to another port are a common cause of confusing results. Also check project-level environment files, IDE launch configurations, package-manager settings, and shell aliases. If a command uses a wrapper script, the wrapper may overwrite or remove the variables before starting Codex CLI.
Verify That Codex CLI Traffic Enters Clash Verge
Do not begin by testing a full coding task. Start with a short, repeatable network check. With Clash Verge running and the intended profile selected, execute a simple HTTPS request through the same terminal environment. The purpose is to check the local listener, TLS connection, DNS behavior, and general routing without involving account state or model usage.
curl -I https://example.com
Immediately open Clash Verge’s Connections or Logs view. A request that passes through the client should normally appear with its hostname or destination address, the matched rule, the selected policy, and the final proxy group or node. If the command succeeds but no connection appears, it may have used a different route, a cached connection, another proxy application, or a system-level tunnel. If it appears as DIRECT when you expected a proxy, inspect the rules and current mode.
A failed curl request can be classified by where it stops:
- Connection refused: the local port is not listening, the port number is wrong, or a firewall or security tool is blocking the local connection.
- Could not resolve host: DNS resolution failed before the request reached its destination. Review DNS mode, local resolver settings, and whether the shell is using another network tool.
- Connection timed out: the selected node, route, or remote destination may be unavailable. Compare another node or test the same request in Global mode.
- TLS or certificate errors: check system time, interception software, certificate configuration, and whether the request is being routed through an unexpected HTTPS proxy.
- HTTP 401 or 403: network connectivity may be working. The problem can instead be an invalid login, expired token, unsupported account flow, or an exit address rejected by the service.
After the basic request works, launch Codex CLI and watch the connection log during login or a small prompt. Look for all relevant destinations, not only the main API hostname. Authentication can involve browser handoff pages, device authorization endpoints, token services, telemetry endpoints, update checks, or package registries. A rule that covers one hostname may not cover the complete flow.
If the command starts a browser for authentication, remember that the browser and Codex CLI may use different proxy paths. Keep Clash Verge’s log visible and compare timestamps. The browser’s authorization page can succeed while the terminal’s callback, token exchange, or API request fails. In that situation, test the terminal separately and check whether the callback uses localhost. Add local addresses to NO_PROXY only when the authentication flow requires a direct local callback; do not exclude remote service domains accidentally.
Troubleshoot Login, API Requests, and Model Calls
Codex CLI may support more than one authentication path, such as an interactive account login or an API key supplied through the environment. These paths should not be diagnosed in exactly the same way. Interactive login may open a browser and wait for a local callback, while API-key usage may go directly from the CLI to an HTTPS endpoint. First identify which path is active, then verify that the credentials are present in the same process environment where the command runs.
When using an API key, do not paste it into the Clash profile, proxy URL, public terminal transcript, or article screenshot. Confirm that the variable name and authentication method match the Codex CLI documentation for the installed release. A missing or malformed key usually produces an authentication error after the network request has reached the service; it is not repaired by switching between HTTP and SOCKS ports.
When login repeatedly opens a browser but never completes, check four boundaries: the browser reaches the authorization page, the CLI remains running and listening for the callback, the local callback address is not being sent to a remote proxy, and the subsequent token exchange appears in Clash Verge’s log. A local callback should generally remain local. If TUN mode is enabled, verify that it does not redirect the callback into an unavailable route.
Model requests can fail even after login succeeds. The selected model may not be available to the account, the API endpoint may reject the request, the node may reset long-lived HTTPS connections, or a rule may send streaming traffic through an unsuitable route. Test a small prompt first, then a slightly longer request. If short responses work but generation stops midway, compare another node, inspect timeout settings, and check whether the terminal process reports a connection reset rather than an authentication failure.
For project commands, distinguish network problems from local project problems. A repository permission error, missing dependency, invalid working directory, or malformed instruction file can occur after the network connection has already succeeded. Use the Clash connection log, the CLI’s exit code, and the terminal error category together. Changing the proxy should not be the default response to an error that clearly refers to a local file or a model permission.
Use a clean terminal session
Close old terminals, start Clash Verge with one active profile, set only the required proxy variables, run a simple HTTPS check, then start Codex CLI. Record the active port, mode, proxy group, timestamp, and the first relevant log entry. This small record makes it much easier to compare a working node with a failing node.
Make the Setup Reliable for Daily Development
Once Codex CLI works, avoid changing several layers at once. Keep the profile name, local port, shell variables, and selected proxy group stable while you test updates. If the subscription refreshes automatically, check whether it replaces custom rules or changes the group names referenced by your overrides. A configuration that works today may fail after an update if the provider removes a node, renames a group, or changes the rule provider format.
Use a dedicated rule strategy for development traffic when your profile supports it. Keep local addresses, private repositories, internal package registries, and loopback callbacks direct where appropriate. Route the remote authentication and API destinations through a maintained proxy group. Avoid broad domain exclusions copied from an unknown configuration because an exclusion can silently bypass the route you are trying to verify.
Keep allow-lan: false unless another device genuinely needs the proxy. If LAN access is required, bind the listener carefully, use the operating system firewall, and avoid exposing an unauthenticated proxy to an untrusted network. The local port should not be treated as a secret-bearing public service. A nearby device that can use it may consume bandwidth, access destinations through your node, or create confusing connection records.
For stability, choose a node with consistent latency and reliable long-lived HTTPS connections rather than selecting only the lowest ping. A latency test may measure a small control request, while Codex CLI uses authentication, API streaming, and larger responses. Watch the connection log during a real but low-cost request. If the node frequently changes IP, resets streams, or triggers repeated TLS failures, select another node or group.
Finally, keep a fallback plan. Save the profile’s important customizations separately, remember the known-good local port, and know how to clear temporary proxy variables from a shell. On Windows PowerShell, closing the session removes session-only variables. On macOS and Linux, use unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY when you need to compare a direct connection. Comparing proxy and direct results is useful, but do not expose credentials while doing so.
Frequently Asked Questions
Does enabling Clash Verge System Proxy automatically proxy Codex CLI?
Not always. Codex CLI may not read the operating system proxy setting. Set HTTP_PROXY and HTTPS_PROXY for the terminal, use the CLI’s documented proxy option if available, or enable TUN mode when explicit proxy configuration is not supported. Confirm the result in the Clash Verge connection log.
Should I use an HTTP port, SOCKS5 port, or mixed port?
Use the protocol documented by the command-line client. A mixed port is convenient when it accepts HTTP and SOCKS requests through one local address. An HTTP proxy URL such as http://127.0.0.1:7890 is commonly used for HTTPS destinations through CONNECT, but not every application supports SOCKS or mixed protocols identically.
Why does login work but the first model request fail?
Login and model requests may use different domains, rules, or authentication states. Check whether the model endpoint appears in the log, whether the account can use the selected model, whether the API key is available to the current process, and whether the selected node supports stable streaming HTTPS connections.
When should I enable TUN mode?
Use explicit proxy variables first because they are easier to inspect. TUN mode is appropriate when Codex CLI or one of its subprocesses ignores proxy variables, or when broader application coverage is required. It needs additional permissions and can conflict with VPN software, firewall rules, or other virtual adapters.