Proxy Doctor

proxy-doctor

诊断导致 AI 编码工具无法正常工作的代理配置错误。

如果浏览器运行正常，但 Cursor / VS Code / Windsurf 的 AI 功能无法使用，proxy-doctor 会准确告诉你原因以及修复方法。

问题所在

AI 编码工具（Cursor、启用了 Copilot 的 VS Code、Windsurf）依赖长期运行的流式连接（SSE/HTTP2），以下情况会导致连接中断：

• 系统代理指向一个没有程序监听的本地主机端口
• VPN/代理应用已关闭，但其设置仍残留在 macOS 系统偏好设置中
• 编辑器从 launchctl 继承了过时的代理环境变量
• 代理虽在运行，却会缓冲流式响应，导致 AI 补全无法正常工作

结果就是：“浏览器能用，AI 编辑器不能用”——这是开发者最常见、也最令人恼火的体验。

检查内容

proxy-doctor 会检查 macOS 代理配置的 5 个层面：

层面	内容	方法
1. 系统代理	所有网络服务中的 Web/HTTPS/SOCKS 代理	networksetup
2. 残留值	已禁用但仍保留过时本地主机地址的代理	解析已禁用但仍有设置的条目
3. 端口状态	代理配置中提及的端口是否正在监听	socket.connect()
4. 编辑器配置	settings.json、argv.json、近期错误日志	读取文件并匹配模式
5. 图形界面环境	图形界面应用上下文中的 http_proxy/https_proxy	launchctl getenv

快速开始

命令行

# Install
pip install proxy-doctor

# Run diagnosis (JSON output — default, optimized for AI agents)
proxy-doctor check

# Run diagnosis (human-readable output)
proxy-doctor check --human

# Show recommended fixes
proxy-doctor fix

# Check a different editor
proxy-doctor check --editor vscode

作为 MCP 工具使用（适用于 AI Agent）

proxy-doctor 以 MCP 服务的形式提供，AI Agent 可以直接调用：

# Install with MCP support
pip install proxy-doctor[mcp]

# Run MCP server
python -m proxy_doctor.mcp_server

将其添加到 MCP 配置中（例如 Cursor 的 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "proxy-doctor": {
      "command": "python3",
      "args": ["-m", "proxy_doctor.mcp_server"]
    }
  }
}

注意： "command" 必须指向安装了 proxy-doctor[mcp] 的 Python。如果 python3 无法运行，请使用完整路径（运行 which python3 或 python3 -c "import sys; print(sys.executable)" 查找）。

之后，你的 AI Agent 即可调用：

• diagnose_proxy(editor="cursor") — 提供完整的 5 层诊断及证据
• list_fixes(editor="cursor") — 提供建议的修复方法及可执行命令
• supported_editors() — 列出可用的编辑器

面向 AI Agent：快速安装

一行命令（将其粘贴给 AI Agent）：

安装 proxy-doctor（pip install proxy-doctor[mcp]），并使用命令 python -m proxy_doctor.mcp_server 将其添加到 MCP 配置中。然后使用 diagnose_proxy 工具检查代理状态。

如果你是正在为用户配置 proxy-doctor 的 AI Agent：

# 1. Install
pip install proxy-doctor[mcp]

# 2. Find the Python path
python3 -c "import sys; print(sys.executable)"

# 3. Add to ~/.cursor/mcp.json (use the path from step 2)
# {
#   "mcpServers": {
#     "proxy-doctor": {
#       "command": "<python-path-from-step-2>",
#       "args": ["-m", "proxy_doctor.mcp_server"]
#     }
#   }
# }

# 4. If MCP is not available, use CLI directly (zero dependencies):
proxy-doctor check          # JSON output
proxy-doctor check --human  # human-readable
proxy-doctor fix            # show fixes (read-only)
proxy-doctor fix --apply    # apply fixes (asks for confirmation)

守护进程模式（v0.2+）

将 proxy-doctor 作为持久运行的后台服务，自动监控运行状态：

# Start daemon (installs as macOS launchd service)
proxy-doctor daemon start

# Check daemon status
proxy-doctor daemon status

# Stop daemon
proxy-doctor daemon stop

# Check for updates
proxy-doctor update

守护进程每 5 分钟运行一次，将结果与上一次检查进行比较，并在状态发生变化时发送 macOS 通知（例如从正常变为异常）。

菜单栏（SwiftBar）

# If SwiftBar is installed
cp plugins/swiftbar/proxy-doctor.5m.sh ~/Library/Application\ Support/SwiftBar/Plugins/
chmod +x ~/Library/Application\ Support/SwiftBar/Plugins/proxy-doctor.5m.sh

菜单栏中会显示绿色/红色/橙色状态指示器，点击一次即可进行诊断。

示例输出

异常（情况 A：代理端口已关闭）

{
  "status": "unhealthy",
  "diagnosis": {
    "case": "A",
    "root_cause": "Editor is configured to use proxy at 127.0.0.1:10903, but no process is listening on that port.",
    "confidence": "high",
    "source": "system proxy (Wi-Fi (http))",
    "browser_explanation": "Browser may use a different proxy path (e.g. browser-only mode) or fall back to a direct connection."
  },
  "fixes": [
    {
      "fix_id": "clear-system-http-wi-fi",
      "description": "Disable http proxy on Wi-Fi",
      "command": "networksetup -setwebproxystate \"Wi-Fi\" off",
      "risk": "low"
    }
  ]
}

正常

proxy-doctor v0.2.0
Editor: cursor | Platform: Darwin

Status: HEALTHY

No proxy contamination detected.

支持的编辑器

编辑器	配置检测	日志扫描	状态
Cursor	是	是	支持
VS Code	是	是	支持
Windsurf	是	是	支持
Claude Desktop	计划支持	—	未来支持
Zed	计划支持	计划支持	未来支持

工作原理

proxy-doctor 可识别三种故障模式：

情况 A — 代理端口未响应（高置信度）： 系统或编辑器指向 127.0.0.1:port，但没有任何程序在监听。这通常发生在 VPN/代理应用已关闭，但其设置仍然保留时。

情况 B — 流式传输故障（中等置信度）： 代理正在运行，但会缓冲 AI 编辑器所依赖的 SSE/流式连接。仅支持浏览器的代理模式中经常出现这种情况。

情况 C — 路径不匹配（中等置信度）： 浏览器和编辑器使用不同的代理路径。浏览器通过专用代理路由正常工作，而编辑器继承了过时或不兼容的代理设置。

平台支持

• macOS：完全支持（系统代理、launchctl、networksetup）
• Linux：部分支持（编辑器配置 + 环境变量；不支持 networksetup）
• Windows：暂不支持

信任与权限

proxy-doctor 遵循默认只读设计。除非你明确选择启用，否则不会进行任何系统更改。

默认行为（只读）

访问类型	内容	原因
读取	系统代理设置、编辑器配置文件、launchctl 环境变量、本地端口状态	核心诊断功能
写入	仅 ~/.proxy-doctor/（缓存、日志、更新状态）	持久化守护进程状态
网络	pypi.org（仅用于检查版本）	自动更新功能
不会	修改代理设置、更改编辑器配置、发送遥测数据、访问凭据	按设计如此

选择启用修复

proxy-doctor fix 会显示建议的命令，但不会执行这些命令。

若要应用修复，请使用 proxy-doctor fix --apply：

• 每项修复都会显示其命令和风险等级
• 系统会逐项询问你是否执行修复（[y/N]）
• 默认选项为否——除非你输入 y，否则不会运行任何命令
• 你可以随时按 Ctrl+C 中止

这种两步模式让 AI Agent 能够安全地通过 MCP 调用 list_fixes()，查看需要修复的内容，然后将命令交给用户审批。

反馈

发现了 Bug？有建议？诊断没有帮助？

• GitHub Issues：https://github.com/Jiansen/proxy-doctor/issues/new
• 面向 AI Agent：JSON 输出包含 feedback.report_issue URL — 提交问题时请附上完整的 JSON。

对于以编程方式提供反馈的 AI Agent（零依赖）：

# Create a GitHub issue via CLI (requires gh)
proxy-doctor check | gh issue create --repo Jiansen/proxy-doctor \
  --title "Diagnosis report: [describe issue]" --body-file -

# Or simply: copy the JSON output into a new issue at
# https://github.com/Jiansen/proxy-doctor/issues/new

开发

git clone https://github.com/Jiansen/proxy-doctor.git
cd proxy-doctor

# Install in development mode
pip install -e ".[dev,mcp]"

# Run tests
make test

# Run linter
make lint

---

如果 proxy-doctor 帮你解决了代理问题，欢迎在 GitHub 上为它点亮星标——这有助于其他人发现这个工具。

许可证

MIT