Set up Codex CLI with KeepKite

This guide covers three things: importing your KeepKite subscription, routing Codex traffic through it, and verifying connectivity. It takes about five minutes.

Already set up and suddenly can't connect? Go straight to Troubleshooting.

Before you start#

• An active KeepKite plan (your subscription link is on the Subscription page of the console)
• A proxy client that can import Clash / Mihomo subscriptions:
  • macOS / Windows / Linux: Clash Verge Rev, Mihomo Party, or similar
  • iOS: Shadowrocket, Stash
  • Android: FlClash, Clash Meta for Android
• Codex CLI installed:

npm install -g @openai/codex
# or, on macOS with Homebrew
brew install --cask codex
codex --version

Step 1: Import your subscription#

1. Sign in to the KeepKite console and click Copy subscription link on the Subscription page.
2. In your proxy client, open Profiles / Subscriptions, paste the link and import it.
3. Select the new profile and update it; you should see the node list.
4. Prefer nodes where Codex shows "Reachable" on the status page — for example Japan, Singapore or US routes.

Your subscription link works like a password. Don't share it; you can reset it in the console if it leaks.

Step 2: Route Codex through KeepKite#

There are two ways. TUN mode is recommended.

Option A: TUN mode (recommended)#

TUN mode captures traffic at the system level, so Codex CLI, the VS Code extension and the browser sign-in callback all go through the proxy without extra configuration.

• Clash Verge Rev: Settings → turn on TUN (virtual network adapter) mode. The first time, it asks you to install a helper service.
• Set the proxy mode to Rule so KeepKite's rules route OpenAI domains through the proxy.

Open a new terminal and run codex.

Option B: HTTPS_PROXY environment variables#

When TUN isn't an option (a managed work laptop, a remote server over SSH), set proxy variables for the terminal only. Codex CLI honours the standard HTTPS_PROXY / HTTP_PROXY / NO_PROXY variables.

Find the mixed port in your client's settings. Clash Verge Rev defaults to 7897; some clients use 7890.

macOS / Linux (bash, zsh):

export HTTPS_PROXY=http://127.0.0.1:7897
export HTTP_PROXY=http://127.0.0.1:7897
export NO_PROXY=localhost,127.0.0.1,::1
codex

Append these lines to ~/.zshrc or ~/.bashrc to make them permanent.

Windows PowerShell:

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

Keep localhost in NO_PROXY. When you sign in with ChatGPT, codex login receives a browser callback on a local port (such as localhost:1455). If that request is sent to the proxy, sign-in hangs.

TUN or environment variables?#

Situation	Use
Personal machine, set it once and forget it	TUN mode
Codex extension in VS Code / Cursor	TUN mode
Only one terminal should use the proxy	Environment variables
Work laptop where you can't install a virtual adapter	Environment variables
Remote Linux server	Environment variables (with SSH -R port forwarding, or a client on the server)

Step 3: Sign in and verify#

codex login        # sign in with your ChatGPT account in the browser
codex "Describe this repository in one sentence"

Then run the KeepKite check script:

curl -fsSL https://app.keepkite.com/check.sh | bash

It checks the terminal's proxy settings and whether the Codex and Claude endpoints are reachable. If everything passes, you're ready to code.

Prefer to read scripts before running them?

curl -fsSL https://app.keepkite.com/check.sh -o keepkite-check.sh
less keepkite-check.sh
bash keepkite-check.sh

IDE extensions#

For the Codex extension in VS Code or Cursor, TUN mode is all you need. If you can only use a system proxy, add this to the editor's settings:

{
  "http.proxy": "http://127.0.0.1:7897",
  "http.proxySupport": "override"
}

Quit the editor completely and restart it.

Common issues#

stream disconnected before completion or timeouts? Usually an unstable node. Switch to one marked "Reachable" on the status page, then see Troubleshooting.

unsupported_country_region_territory? The request didn't go through the proxy, or it left from an unsupported region. Check that TUN or the variables are active, and switch nodes.

Sign-in page keeps spinning? Make sure NO_PROXY contains localhost,127.0.0.1, or use TUN mode.