OpenAI Codex CLI With Clash Verge: Setup Guide for Access

Understand the network path before changing settings

OpenAI Codex CLI brings AI-assisted coding into a terminal workflow. It can inspect a project, explain files, suggest edits, generate patches, and run selected development commands, but every request still depends on a reliable HTTPS connection. When access fails, the visible error may come from several different layers: the CLI authentication method, the operating system environment, Clash Verge’s local proxy listener, the selected proxy policy, DNS resolution, or the remote service itself.

Clash Verge is the graphical control layer. Its mihomo-compatible core reads the active YAML configuration, listens on local HTTP, SOCKS5, or mixed ports, resolves domains according to the configured DNS policy, and forwards traffic through the selected proxy group. Codex CLI is a separate terminal application. It does not automatically inherit every setting shown in Clash Verge, especially when the system proxy is disabled or when the CLI uses its own HTTP client.

A useful diagnostic model is:

• Authentication: Codex CLI must use a supported sign-in flow or API credential, depending on the release and account type you selected.
• Process environment: The terminal must be able to read the proxy variables or system proxy configuration.
• Local listener: Clash Verge must be running, with an active core and a reachable local port.
• Policy routing: The request must match a usable proxy group and a node that can reach the required service.
• TLS and response handling: The connection must complete certificate verification and return a response the CLI understands.

This separation prevents a common mistake: repeatedly changing nodes when the terminal is not using Clash Verge at all. It also prevents the opposite mistake, where the proxy works in a browser but the CLI is still trying to connect directly because its environment has not been configured.

Prepare Clash Verge and import a working profile

Install Clash Verge from the official download page, then launch it before configuring Codex CLI. If you already have a subscription profile, open the profile or configuration section and add the subscription URL supplied by your provider. Treat that URL like a password: it often contains a long token that can give access to your account or traffic service.

1. Open Clash Verge and add the subscription URL in the Profiles or configuration area.
2. Wait for the profile to download, then select the newly imported profile.
3. Confirm that the mihomo core starts without a YAML parsing error.
4. Open the proxy or dashboard view and select a usable policy group and node.
5. Enable the system proxy only after the core shows that it is running.
6. Test an ordinary HTTPS request before testing Codex CLI.

Do not assume that a downloaded profile is automatically active. Many clients distinguish between “profile imported,” “profile selected,” and “core running.” Check all three states. If the profile contains newer fields such as rule providers, TUN options, or mihomo-specific DNS settings, use a mihomo-compatible core rather than an archived classic Clash core.

Check the local proxy ports

Open Clash Verge’s settings and record the actual mixed port or separate HTTP and SOCKS5 ports. The port is configurable and may differ between installations. Common examples include 7890 and 7897, but the value shown in your client is authoritative. A typical local address is 127.0.0.1; do not replace it with the remote server address.

Never use the external controller port as a normal proxy port. The controller exposes management functions such as status, connections, and policy switching; it is not an HTTP forward proxy. If a controller secret is configured, keep it private and avoid publishing screenshots that reveal the address or secret.

mixed-port: 7897
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

The snippet above is only an example of the roles of these fields. Do not overwrite a provider-managed subscription with a hand-written file unless you understand how the provider’s rules, proxies, and policy groups are assembled.

Configure Codex CLI to use the local proxy

First test whether Codex CLI follows the system proxy. On Windows, enable the system proxy in Clash Verge and open a new PowerShell window. On macOS or Linux, enable the system proxy and start a new terminal session. A new process is important because environment variables and some application settings are read only when the process starts.

If the CLI still cannot connect, configure standard proxy environment variables for the current terminal session. Use the exact port recorded from Clash Verge:

# macOS or Linux
export HTTP_PROXY="http://127.0.0.1:7897"
export HTTPS_PROXY="http://127.0.0.1:7897"
export ALL_PROXY="http://127.0.0.1:7897"
export NO_PROXY="127.0.0.1,localhost"

# Verify that the command is visible
codex --version

On Windows PowerShell, the equivalent temporary configuration is:

$env:HTTP_PROXY = "http://127.0.0.1:7897"
$env:HTTPS_PROXY = "http://127.0.0.1:7897"
$env:ALL_PROXY = "http://127.0.0.1:7897"
$env:NO_PROXY = "127.0.0.1,localhost"

codex --version

Some HTTP libraries prefer lowercase variable names, while others check uppercase names. If uppercase variables have no effect, set both forms for the current session:

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"
export no_proxy="$NO_PROXY"

Do not permanently place a proxy variable in a shell profile until the temporary test works. A permanent value can cause unrelated commands, package managers, Git operations, or local development services to use a proxy unexpectedly. It can also create confusing failures when you are later connected to a network where the local Clash Verge port is not running.

Choose an authentication method without exposing credentials

Codex CLI releases may offer different authentication paths, such as an interactive account sign-in or an API credential supplied through the environment. Follow the authentication options shown by the version installed on your machine and the account plan you intend to use. Do not copy a token from a browser address bar, terminal history, screenshot, or shared configuration file.

If your organization supplies an API key, load it through the method documented for your Codex CLI release. Avoid placing the key directly in a command that will be saved in shell history. On macOS and Linux, a temporary environment assignment can still be recorded by some terminal tools or process monitors, so use the provider’s recommended credential store when available.

• Keep subscription URLs, API keys, and refresh tokens out of project files.
• Add local credential files to .gitignore before creating commits.
• Review shell history if a secret was pasted into a command line.
• Revoke and replace a credential immediately if it appears in a public log or repository.
• Do not send complete proxy URLs containing access tokens when asking for support.

Authentication errors and network errors can look similar in a terminal. A message about an expired sign-in, invalid credential, or insufficient permission should be handled in the account flow. A timeout, connection reset, or name-resolution error should be investigated through Clash Verge and the network path first.

Verify routing before starting a coding session

Before asking Codex CLI to inspect a repository, test the local proxy with a harmless HTTPS request. This separates a proxy problem from a Codex-specific problem. Replace the port below with the value shown in Clash Verge:

curl -I --connect-timeout 10 \
  -x http://127.0.0.1:7897 \
  https://example.com

A successful response proves that the local HTTP proxy accepted the request and that at least one route can reach the destination. It does not prove that every OpenAI service, authentication endpoint, or streaming connection will work. Check the Clash Verge connection log while running the command. You should see a new connection and the policy group or node selected for it.

For a more realistic HTTPS test, use the endpoint or domain supplied by the current Codex CLI documentation, rather than guessing a private service URL. Service domains and authentication flows can change, and testing an invented endpoint can produce a misleading 404 or policy result. The important observations are whether DNS succeeds, whether TLS completes, whether the request is routed through the intended group, and whether the response is returned without repeated resets.

After the proxy test, run a low-impact CLI command such as a version or help command, then perform authentication. Only after both steps succeed should you open a project and request an operation. Keep the first prompt small, for example asking Codex CLI to summarize one known source file. This makes it easier to distinguish connection failures from workspace permissions, command approval, or repository-specific problems.

Troubleshoot timeouts, TLS errors, and unstable sessions

When Codex CLI reports a timeout, first check whether a request appears in Clash Verge’s connection list. If there is no connection, the CLI probably is not using the proxy variables or the local port is wrong. If a connection appears and is immediately closed, inspect the selected node, the rule match, and the core log. If the connection remains pending, DNS resolution or the upstream route may be the issue.

For a 407 Proxy Authentication Required response, verify whether the local listener expects credentials. A normal loopback proxy commonly does not require them, but a custom configuration may. Do not add arbitrary credentials to the URL without confirming the listener settings. For 403 or 429 responses, the remote service or an upstream gateway rejected the request; changing local DNS alone will not resolve that response.

TLS errors require more care. Avoid disabling certificate verification as a quick fix. A wrong system clock, outdated certificate store, traffic interception software, or an unsuitable proxy node can all cause certificate failures. Check the operating system date and time, update the client and core through trusted sources, and test another node. If a corporate network uses an inspection certificate, follow the organization’s approved certificate installation process instead of ignoring verification.

Use TUN only when the terminal needs transparent routing

System proxy mode is usually enough when Codex CLI honors HTTP_PROXY, HTTPS_PROXY, or the operating system proxy. TUN mode is more appropriate when an application ignores proxy variables, uses non-HTTP traffic, performs its own networking, or must be covered together with other desktop applications. TUN requires additional permissions and changes routing and DNS behavior, so it adds another layer to troubleshoot.

Before enabling TUN, turn off duplicate VPN applications and confirm that no other client is already installing a virtual network interface. In Clash Verge, enable TUN according to the platform’s permission prompts, then verify that the core remains healthy and that ordinary websites still load. If DNS becomes unstable, compare the result with TUN disabled and inspect the configured DNS mode and fake-IP behavior. Do not enable strict routing merely because a connection is slow; understand the bypass and local-network consequences first.

• Use system proxy mode for a predictable first test.
• Use explicit terminal variables when the CLI does not inherit system settings.
• Use TUN when the application ignores both system proxy and environment variables.
• Exclude local development addresses such as localhost and 127.0.0.1 from proxying.
• Disable TUN and restore the system proxy state before uninstalling or replacing the client.

A stable Codex CLI setup is not defined by the largest number of enabled features. The practical target is a clearly identified Clash Verge profile, one active core, one known local proxy port, a tested policy group, and an authentication method that does not leak credentials. Once those pieces are verified independently, AI-assisted coding requests can run through the same predictable terminal environment as the rest of the development workflow.