English | 中文
Auto-inherit system proxy for CLI tools across Windows, macOS, and Linux — solves "system proxy is on but CLI tools can't reach the internet" for opencode, Claude Code, npm, Go, pip, and more.
System proxy settings (set via OS network preferences) only work for browsers and a few native applications.
CLI tools like Node.js, Go, and Python don't read system proxy settings — they only respect HTTP_PROXY / HTTPS_PROXY environment variables.
| Tool | System proxy on | Can connect? |
|---|---|---|
| Browser / curl | ✅ | ✅ |
| opencode / Claude Code | ❌ doesn't read OS proxy | ❌ |
| npm / yarn / pip | ❌ doesn't read OS proxy | ❌ |
ProxyHeredit runs automatically on every terminal launch:
- Windows: Reads system proxy from registry
HKCU:\...\Internet Settings - macOS: Reads system proxy via
scutil --proxy - Linux: Reads system proxy via GNOME
gsettingsor KDEkreadconfig5 - Injects proxy address into
HTTP_PROXY/HTTPS_PROXY/NO_PROXYfor the current session - Automatically follows when proxy is disabled or port changes — zero maintenance
OS System Proxy ──→ profile.ps1 / profile.sh ──→ HTTP_PROXY / HTTPS_PROXY
(on every terminal launch) (visible to CLI tools)
The proxy is injected into the current terminal session and every CLI tool launched from it (opencode, Claude Code, npm, pip, …). ProxyHeredit deliberately does not write permanent environment variables — those would freeze the proxy at install time and leak a stale address to non-terminal processes. GUI apps or processes started outside a terminal (Explorer/Dock-launched apps, background services) won't inherit it; point those at the OS system proxy or use TUN mode instead.
# Run from the project directory
.\install.ps1# Run from the project directory
chmod +x install.sh
./install.shInstall will prompt for a GitHub token if none is configured. This avoids GitHub API rate limiting (60 → 5000 requests/hour) for tools like opencode.
Create a token at github.com/settings/tokens (no scopes needed).
.\install.ps1
# ── Enter GitHub Token (blank to skip): ghp_xxxx./install.sh
# ── Enter GitHub Token (blank to skip): ghp_xxxxThe token is appended to your shell rc file (~/.zshrc, ~/.bashrc, or PowerShell $PROFILE). To change it, run uninstall.sh / uninstall.ps1 first (or remove the existing token line), then re-run install.
# Check if env vars are injected
$env:HTTP_PROXY
$env:HTTPS_PROXY
# Test proxy connectivity
curl.exe -s -o NUL -w "HTTP %{http_code} (%{time_total}s)" https://www.google.com
# Expected: HTTP 302 (0.3s)# Check if env vars are injected
echo "$HTTP_PROXY"
echo "$HTTPS_PROXY"
# Test proxy connectivity
curl -s -o /dev/null -w "HTTP %{http_code} (%{time_total}s)" https://www.google.com
# Expected: HTTP 302 (0.3s)Verify opencode works through proxy:
opencode.\uninstall.ps1Manual:
# Remove ProxyHeredit from $PROFILE, then:
[System.Environment]::SetEnvironmentVariable("HTTP_PROXY", $null, "User")
[System.Environment]::SetEnvironmentVariable("HTTPS_PROXY", $null, "User")
[System.Environment]::SetEnvironmentVariable("NO_PROXY", $null, "User")./uninstall.shAny tool that reads HTTP_PROXY / HTTPS_PROXY works automatically. Supports all platforms:
- opencode — AI coding assistant
- Claude Code — Anthropic official CLI
- npm / yarn / pnpm — Node.js package managers
- Go —
go get,go mod download - pip — Python package manager
- curl / wget — HTTP clients
- Docker — when
HTTP_PROXYis configured
ProxyHeredit/
├── README.md # This file
├── profile.ps1 # PowerShell profile script (Windows)
├── profile.sh # Shell profile script (macOS / Linux)
├── install.ps1 # Windows installer
├── install.sh # macOS / Linux installer
├── uninstall.ps1 # Windows uninstaller
└── uninstall.sh # macOS / Linux uninstaller
MIT
让 CLI 工具自动继承系统代理设置——支持 Windows、macOS、Linux，解决 opencode、Claude Code、npm、Go、pip 等工具"有系统代理但走不通"的问题。
系统代理设置（通过 OS 网络偏好设置配置）只对浏览器和部分原生应用生效。
Node.js、Go、Python 等 CLI 工具不读取系统代理设置，它们只认 HTTP_PROXY / HTTPS_PROXY 环境变量。
| 工具 | 系统代理已开 | 能否联网 |
|---|---|---|
| 浏览器 / curl | ✅ | ✅ |
| opencode / Claude Code | ❌ 不读取系统代理 | ❌ |
| npm / yarn / pip | ❌ 不读取系统代理 | ❌ |
ProxyHeredit 在每次终端启动时自动执行：
- Windows: 读取注册表
HKCU:\...\Internet Settings - macOS: 通过
scutil --proxy读取系统代理 - Linux: 通过 GNOME
gsettings或 KDEkreadconfig5读取系统代理 - 将代理地址注入当前会话的
HTTP_PROXY/HTTPS_PROXY/NO_PROXY环境变量 - 代理关闭或端口变化时自动跟随，零维护
系统代理 ──→ profile.ps1 / profile.sh ──→ HTTP_PROXY / HTTPS_PROXY
(每次终端启动) (对 CLI 工具可见)
代理只会注入到当前终端会话及其中启动的 CLI 工具（opencode、Claude Code、npm、pip…）。ProxyHeredit 刻意不写永久环境变量——那会把代理冻结在安装时刻，并向非终端进程泄漏过期地址。GUI 程序或终端外启动的进程（资源管理器/Dock 启动、后台服务）不会继承它；这类程序请走系统代理或 TUN 模式。
.\install.ps1chmod +x install.sh
./install.sh安装时会询问是否配置 GitHub Token，用于避免 GitHub API 限流（60 → 5000 次/小时），让 opencode 等工具免于 403 错误。
在 github.com/settings/tokens 创建（无需勾选任何权限）：
./install.sh
# ── Enter GitHub Token (blank to skip): ghp_xxxxToken 会写入 shell 配置文件（~/.zshrc、~/.bashrc 或 PowerShell $PROFILE）。若要更换，请先运行 uninstall.sh / uninstall.ps1（或手动删除旧行），再重新运行安装脚本。
$env:HTTP_PROXY
$env:HTTPS_PROXY
curl.exe -s -o NUL -w "HTTP %{http_code} (%{time_total}s)" https://www.google.comecho "$HTTP_PROXY"
echo "$HTTPS_PROXY"
curl -s -o /dev/null -w "HTTP %{http_code} (%{time_total}s)" https://www.google.com验证 opencode：
opencode.\uninstall.ps1./uninstall.sh所有读取 HTTP_PROXY / HTTPS_PROXY 环境变量的工具都自动生效，包括但不限于：
- opencode — AI 编程助手
- Claude Code — Anthropic 官方 CLI
- npm / yarn / pnpm — Node.js 包管理器
- Go —
go get,go mod download - pip — Python 包管理器
- curl / wget — HTTP 客户端
- Docker — 当配置了
HTTP_PROXY时
ProxyHeredit/
├── README.md # 本文件
├── profile.ps1 # PowerShell 配置脚本 (Windows)
├── profile.sh # Shell 配置脚本 (macOS / Linux)
├── install.ps1 # Windows 安装脚本
├── install.sh # macOS / Linux 安装脚本
├── uninstall.ps1 # Windows 卸载脚本
└── uninstall.sh # macOS / Linux 卸载脚本
MIT