Network & Proxy

• A hanging request, Connection timed out, Connection reset, or a DNS failure (e.g. a getaddrinfo error) usually means the network cannot reach KOPRouter directly — configure a proxy as described below.
• An HTTP status such as 401 / 402 / 429 / 404 means the network is fine and the problem is the API key, balance, rate limit, or model — see the FAQs.

Option 1: System-wide VPN / proxy (simplest)

Enable a system-level VPN or proxy in “global / TUN mode” so that all processes route through the proxy automatically — no per-tool configuration needed.

• macOS: Clients such as Clash, Surge, or Shadowrocket — enable “Set as system proxy” or “Enhanced mode / TUN”.
• Windows: Clients such as Clash for Windows, V2RayN, or Nekoray — enable “System proxy” or “TUN mode”.
• Linux: Enable TUN mode, or use tools like proxychains.

Once enabled, no tool needs to be changed. If global mode interferes with other network access, use Option 2 below to configure only the tools you need.

Option 2: Put the proxy in the tool’s config (recommended)

Set a proxy only for the tools that need to reach KOPRouter. Compared with environment variables, writing the proxy into the tool’s config file or UI settings is more intuitive and easier to undo.

Claude Code

Add it to the env block of ~/.claude/settings.json (if the file already has an env, append inside it):

{
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:7890",
    "HTTP_PROXY": "http://127.0.0.1:7890"
  }
}

OpenClaw

Write it to ~/.openclaw/openclaw.json, or set it with a command:

openclaw config set proxy.proxyUrl http://127.0.0.1:7890

This is equivalent to adding "proxy": { "proxyUrl": "http://127.0.0.1:7890" } to openclaw.json. Note that OpenClaw does not read the HTTP_PROXY / HTTPS_PROXY environment variables — it only supports proxy.proxyUrl.

Cherry Studio / Cursor / WorkBuddy (GUI apps)

Enter the HTTP proxy address (e.g. http://127.0.0.1:7890) under the app’s “Settings → Network / Proxy”, or enable the system proxy (Option 1 above). These desktop apps generally have a “Proxy” or “Network” section in their settings.

Tools that only support environment variables

Codex CLI, OpenAI SDK, and LangChain have no proxy setting in their config files, so they can only be configured via environment variables — see Option 3 below.

Option 3: Set the proxy via environment variables

Use this only for tools that have no config-file proxy setting (such as Codex CLI, OpenAI SDK, and LangChain), or as a fallback.

The 7890 below is just an example port — use your own proxy client’s actual listening port.

macOS / Linux (command-line tools)

Add the following to your shell startup file, and it is loaded automatically in every new terminal:

• macOS (zsh is the default shell): write to ~/.zshrc
• Linux (most distros default to bash): write to ~/.bashrc

export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
# If your client is a SOCKS5 proxy, add this line too (only some tools need it):
export ALL_PROXY="socks5://127.0.0.1:7891"

After writing, run source ~/.zshrc (or source ~/.bashrc) to apply it immediately.

Windows (command-line tools)

PowerShell (temporary, current window only):

$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY  = "http://127.0.0.1:7890"

Permanent (works in CMD or PowerShell; reopen the terminal afterwards):

setx HTTPS_PROXY "http://127.0.0.1:7890"
setx HTTP_PROXY  "http://127.0.0.1:7890"

You can also open “System Properties → Advanced → Environment Variables” and add HTTPS_PROXY and HTTP_PROXY as user variables in the GUI.

Per-tool proxy quick reference

curl -x http://127.0.0.1:7890 https://koprouter.kopglobal.com/v1/models -H "Authorization: Bearer sk-..."