explaingit

sirfetch-d/codex-proxy

Analysis updated 2026-06-24

★ 35ShellAudience · developerComplexity · 2/5LicenseSetup · easy

TLDR

macOS shell script that launches the OpenAI Codex desktop app with HTTP and SOCKS proxy variables set, so only Codex traffic routes through Clash.

Mindmap

mindmap
  root((codex-proxy))
    Inputs
      Codex app path
      Clash listener port
      No proxy hosts
    Outputs
      Proxied Codex process
      Log file
    Use Cases
      Route Codex via Clash
      Fix WebSocket reconnect
      Avoid global TUN mode
    Tech Stack
      Shell
      macOS
      Clash
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Route only the Codex desktop app through a Clash proxy without affecting other apps

USE CASE 2

Fix WebSocket reconnect loops in Codex when system proxy misses non-HTTP traffic

USE CASE 3

Avoid enabling Clash TUN mode globally on macOS

What is it built with?

ShellmacOSClash

How does it compare?

sirfetch-d/codex-proxy1061700625/github_vpsganimjeong/harness-for-codex
Stars353831
LanguageShellShellShell
Setup difficultyeasymoderateeasy
Complexity2/52/52/5
Audiencedeveloperops devopsdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · easy Time to first run · 5min

Needs a Clash-compatible client already running locally on port 7890.

MIT license, use, modify, and redistribute freely as long as you keep the copyright notice.

In plain English

codex-proxy is a small macOS shell script that launches OpenAI's Codex desktop app with a proxy configuration applied, so that all of Codex's network traffic, including WebSocket connections, flows through a local Clash proxy. Clash is a popular proxy client used in mainland China and elsewhere to route traffic through custom rules and remote servers. The motivation is specific. On macOS with Clash running, system-level proxy settings only catch HTTP traffic by default. WebSocket connections do not go through the system proxy unless Clash's TUN mode is enabled. TUN mode creates a virtual network interface that captures all traffic for the whole machine, but it is global, so it affects every app, not just Codex. The Codex desktop app uses WebSocket for two things: the remote-connection feature that lets the ChatGPT mobile app talk to the desktop, and its preferred low-latency channel to OpenAI's backend. When WebSocket cannot reach OpenAI, the README notes that Codex shows Reconnecting 1/5 through 5/5, waiting about 15 seconds per retry, before falling back to plain HTTP. The cumulative wait can reach 75 seconds or more. codex-proxy sidesteps the global TUN approach. It launches Codex.app with HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY environment variables set to point at the Clash listener (default 127.0.0.1:7890). Because these environment variables are inherited only by the Codex process, only Codex's traffic goes through the proxy. Every other GUI app on the machine keeps its original network configuration. Usage is five subcommands: codex-proxy start launches the app with proxy variables set, after first killing any existing Codex process so there is no leftover non-proxied instance, and stop, restart, status, and log do what they say. Logs are written to ~/Library/Logs/codex-proxy.log. Configuration is through environment variables you can put in your .zshrc: CODEX_APP for a custom app path, CODEX_HTTP_PROXY, CODEX_ALL_PROXY for a SOCKS5 endpoint, and CODEX_NO_PROXY for hosts that should bypass the proxy. The prerequisites are macOS, any Clash-compatible client like Clash, Clash Verge, or ClashX, and the default Clash port 7890. The license is MIT.

Copy-paste prompts

Prompt 1
Install codex-proxy on macOS and start the Codex app routed through my local Clash on port 7890
Prompt 2
Set CODEX_ALL_PROXY in my zshrc to use a SOCKS5 endpoint with codex-proxy
Prompt 3
Tail the codex-proxy log and check whether Codex is using the proxy correctly
Prompt 4
Adapt codex-proxy to point at a Clash Verge instance on a different port

Frequently asked questions

What is codex-proxy?

macOS shell script that launches the OpenAI Codex desktop app with HTTP and SOCKS proxy variables set, so only Codex traffic routes through Clash.

What language is codex-proxy written in?

Mainly Shell. The stack also includes Shell, macOS, Clash.

What license does codex-proxy use?

MIT license, use, modify, and redistribute freely as long as you keep the copyright notice.

How hard is codex-proxy to set up?

Setup difficulty is rated easy, with roughly 5min to a first successful run.

Who is codex-proxy for?

Mainly developer.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.

Alternatives & similar repos