网络与代理配置

• 请求卡住、Connection timed out、Connection reset、DNS 解析失败（如 getaddrinfo 报错）——大概率是网络无法直连 KOPRouter，请按本页配置代理。
• 返回 401 / 402 / 429 / 404 等 HTTP 状态码——说明网络已通，问题在 API Key、余额、限流或模型，请参考「常见问题」。

方案一：系统级 VPN / 代理（最省事）

在系统层开启 VPN 或代理的「全局 / TUN 模式」，让所有进程的流量自动走代理，无需再单独配置任何一个工具。

• macOS：Clash、Surge、Shadowrocket 等客户端，开启「设置为系统代理」或「增强模式 / TUN」。
• Windows：Clash for Windows、V2RayN、Nekoray 等客户端，开启「系统代理」或「TUN 模式」。
• Linux：开启 TUN 模式，或配合 proxychains 等工具使用。

开启后无需改动任何工具的配置。若全局模式会影响其他网络访问，请改用下方「方案二」，只对需要的工具单独配置。

方案二：把代理写进工具的配置（推荐）

只对需要访问 KOPRouter 的工具设置代理。相比设置环境变量，把代理直接写进该工具的配置文件或界面设置更直观，也更容易改回来。

Claude Code

写进 ~/.claude/settings.json 的 env 块即可（若文件里已有 env，在其内部追加）：

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

OpenClaw

写进 ~/.openclaw/openclaw.json，或用命令设置：

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

等价于在 openclaw.json 中加入 "proxy": { "proxyUrl": "http://127.0.0.1:7890" }。注意 OpenClaw 不读取 HTTP_PROXY / HTTPS_PROXY 环境变量，只能通过 proxy.proxyUrl 配置。

Cherry Studio / Cursor / WorkBuddy（图形界面）

在应用的「设置 → 网络 / 代理」里填写 HTTP 代理地址（例如 http://127.0.0.1:7890），或直接开启系统代理（即上面的「方案一」）。这几个桌面应用通常在设置里都有「代理」或「网络」一栏。

仅支持环境变量的工具

Codex CLI、OpenAI SDK、LangChain 等工具没有配置文件里的代理项，只能通过环境变量设置，见下方「方案三」。

方案三：通过环境变量设置代理

仅用于没有配置文件代理项的工具（如 Codex CLI、OpenAI SDK、LangChain），或作为兜底手段。

下面的 7890 只是示例端口，请换成你自己的代理客户端实际监听端口。

macOS / Linux（命令行工具）

把下面的内容写入终端启动文件后，重开终端即可自动加载：

• macOS（默认 Shell 为 zsh）：写入 ~/.zshrc
• Linux（多数发行版默认 Shell 为 bash）：写入 ~/.bashrc

export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
# 若客户端是 SOCKS5 代理，可再加一行（部分工具才需要）：
export ALL_PROXY="socks5://127.0.0.1:7891"

写入后执行 source ~/.zshrc（或 source ~/.bashrc）立即生效。

Windows（命令行工具）

PowerShell（仅当前窗口临时生效）：

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

永久生效（CMD 或 PowerShell 均可，需重开终端）：

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

也可以打开「系统属性 → 高级 → 环境变量」，在「用户变量」里以图形界面新增 HTTPS_PROXY 与 HTTP_PROXY。

各工具代理配置速查

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