Skip to main content
Glama
deeneskoruzh
Jiansen

proxy-doctor

by Jiansen
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

诊断破坏 AI 编码工具的代理配置错误。

当你的浏览器工作正常，但 Cursor / VS Code / Windsurf AI 功能失效时 — proxy-doctor 会准确告诉你原因以及如何修复。

问题

AI 编码工具（Cursor、带有 Copilot 的 VS Code、Windsurf）依赖于长期存在的流式连接（SSE/HTTP2），当以下情况发生时，这些连接会中断：

  • 你的系统代理指向一个没有服务在监听的本地主机端口

  • VPN/代理应用已关闭，但其设置仍残留在 macOS 系统偏好设置中

  • 你的编辑器从 launchctl 继承了过时的代理环境变量

  • 代理正在运行，但缓冲了流式响应，破坏了 AI 补全功能

结果：“浏览器可以工作，AI 编辑器不行” — 这是最普遍且令人沮丧的开发者体验。

Related MCP server: Inksnow MCP Proxy

检查内容

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

层面

检查内容

方式

1. 系统代理

所有网络服务上的 Web/HTTPS/SOCKS 代理

networksetup

2. 残留值

已禁用但包含过时本地主机地址的代理

解析已禁用但已设置的条目

3. 端口健康

引用的代理端口是否实际在监听

socket.connect()

4. 编辑器配置

settings.json、argv.json、最近的错误日志

文件读取 + 模式匹配

5. GUI 环境

GUI 应用上下文中的 http_proxy/https_proxy 变量

launchctl getenv

快速开始

CLI

# 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 代理）

proxy-doctor 附带一个 MCP 服务器，AI 代理可以直接调用：

# 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 代理随后可以调用：

  • diagnose_proxy(editor="cursor") — 包含证据的完整 5 层面诊断

  • list_fixes(editor="cursor") — 包含可执行命令的推荐修复方案

  • supported_editors() — 列出可用的编辑器

针对 AI 代理：快速安装

一行命令（将其粘贴给你的 AI 代理）：

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

如果你是一个 AI 代理，正在为你的用户设置 proxy-doctor：

# 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:端口 但没有任何服务在监听。当 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 代理可以通过 MCP 安全地调用 list_fixes() 来查看需要修复的内容，然后将命令呈现给用户批准。

反馈

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

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

# 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 上给它一个星标 — 这有助于其他人发现这个工具。

在 GitHub 上点星

许可证

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers