1. 项目概述当你的AI编程助手突然“失聪”你有没有遇到过这种场景浏览器上网一切正常GitHub、Stack Overflow 刷得飞起但当你回到 Cursor 或者 VS Code满怀期待地敲下几行注释等着 Copilot 或者 Windsurf 给你续写代码时那个熟悉的智能建议却迟迟不出现状态栏只留下一个不断旋转的加载图标或者干脆弹出一个“网络连接错误”的提示。你刷新、重启编辑器、甚至重启电脑问题依旧。这种“浏览器能用AI编辑器罢工”的割裂感是当下很多开发者尤其是深度依赖 AI 编程工具的 macOS 用户最常遇到也最令人抓狂的问题之一。问题的根源十有八九出在“代理配置”这个老生常谈却又无比隐蔽的环节上。AI 编程工具如 Cursor、VS Code Copilot、Windsurf与普通网页浏览有着本质区别它们依赖的是 Server-Sent Events 或 HTTP/2 这类长连接、流式传输协议来实时接收 AI 的代码补全。而许多网络代理软件特别是那些提供“浏览器专用”模式的或者你之前用过但已关闭的 VPN会在系统层面留下一些“僵尸”配置。这些配置指向一个本地的端口比如127.0.0.1:7890但那个端口上早已没有程序在监听。你的浏览器可能通过其他路径绕开了这个无效配置但严格遵守系统设置的编辑器却一头撞了上去导致流式连接根本无法建立。手动排查这个问题无异于大海捞针你需要检查 macOS 系统偏好设置里的网络代理、各种环境变量http_proxy,https_proxy,all_proxy、编辑器的配置文件settings.json,argv.json还要用lsof或netstat命令查看端口监听状态。这个过程繁琐、易错且对新手极不友好。proxy-doctor就是为了终结这种混乱而生的。它是一个专为 macOS 设计的命令行诊断工具能像经验丰富的网络工程师一样层层剖析你系统中所有可能与代理相关的配置精准定位导致 AI 工具失效的“罪魁祸首”并给出清晰、可执行的修复建议。2. 核心设计思路五层诊断模型proxy-doctor的设计哲学是“全面扫描精准打击”。它没有采用简单的单一检查而是构建了一个五层诊断模型从上到下、从系统到应用逐层排查可能的污染源。这个模型是其高效和准确的核心。2.1 第一层系统代理设置这是最表层也是影响范围最广的一层。macOS 允许为每个网络服务如 Wi-Fi、以太网单独设置 Web、HTTPS 和 SOCKS 代理。这些设置通常由 VPN 或代理软件在启动/关闭时自动修改。proxy-doctor通过调用networksetup命令来获取这些配置。注意很多代理软件在退出时并不会干净地清除这些系统设置。这就是“僵尸代理”最常见的来源。proxy-doctor不仅会检查已启用的代理还会特别关注那些被标记为“关闭”但依然保留了地址和端口的条目因为它们可能被其他应用读取。2.2 第二层残留的环境变量在 macOS 上环境变量的传递路径比 Linux 更复杂。通过终端Terminal启动的应用会继承 Shell 中的环境变量如你在~/.zshrc中设置的export https_proxy...。但是像 Cursor、VS Code 这类通常从 Dock 或 Spotlight 启动的 GUI 应用它们的环境变量是由launchd管理的。proxy-doctor会使用launchctl getenv命令来检查当前 GUI 上下文中的http_proxy、https_proxy等变量。这解释了为什么你在终端里curl一个网址能走代理但编辑器里却不行——两者所处的环境根本不同。2.3 第三层端口健康检查这是确认问题的关键一步。就算前两层发现系统或环境变量指向了127.0.0.1:8080如果这个端口上根本没有进程在监听那么这个配置就是无效的。proxy-doctor会尝试用 Python 的socket模块去连接这些被配置的地址和端口。如果连接失败即Connection refused它就能以“高置信度”判定此处存在一个“死代理端口”这是导致连接失败的铁证。2.4 第四层编辑器专属配置不同的编辑器有自己的配置优先级。以 VS Code/Cursor 为例它们会按顺序读取工作区级别的settings.json用户级别的settings.json通过--proxy-server命令行参数传入的配置记录在argv.json中proxy-doctor会直接读取这些 JSON 文件解析其中的http.proxy、https.proxy或proxy相关设置。同时它还会扫描编辑器最近的日志文件如 Cursor 的logs/main.log寻找与网络、代理相关的错误信息为诊断提供旁证。2.5 第五层流式传输兼容性推断这是最棘手的一层。有时代理是存在的端口也是通的但 AI 补全仍然失败。这通常是因为该代理例如某些软件的“全局代理”模式对 SSE/HTTP2 长连接的支持不佳或者存在缓冲行为破坏了流式传输。proxy-doctor目前主要通过“模式匹配”和“排除法”来给出“中等置信度”的判断。例如如果系统代理指向一个已知的、常用于网页浏览的代理地址如127.0.0.1:7890而浏览器工作正常但编辑器失败结合日志中的流式错误就可以推断可能是 Case B流式传输被破坏。通过这五层模型的交叉验证proxy-doctor能将模糊的“用不了”转化为具体的诊断案例Case A, B, C并给出针对性的修复方案。3. 安装与基础使用指南proxy-doctor的安装极其简单它就是一个纯粹的 Python 包没有复杂的原生依赖。这保证了它在绝大多数 macOS 环境下的可移植性。3.1 安装步骤打开你的终端Terminal 或 iTerm2执行以下命令即可完成安装。建议使用pipx进行全局安装这样可以避免与你的项目虚拟环境产生冲突也便于后续更新。# 首先安装 pipx如果你还没有的话 brew install pipx pipx ensurepath # 使用 pipx 安装 proxy-doctor pipx install proxy-doctor # 或者使用常规 pip 安装安装在当前用户环境 pip install --user proxy-doctor安装完成后直接在终端输入proxy-doctor如果看到帮助信息就说明安装成功。pipx安装的版本命令在任何路径下都可用这是最推荐的方式。3.2 核心诊断命令安装后最基本的操作就是运行诊断。proxy-doctor默认以 JSON 格式输出这种结构化的数据非常适合被其他脚本或 AI 工具后面会讲到解析。# 默认诊断输出 JSON proxy-doctor check # 如果你想直接看人类可读的总结加上 --human 参数 proxy-doctor check --human # 默认检查的是 Cursor 编辑器你也可以指定其他支持的编辑器 proxy-doctor check --editor vscode proxy-doctor check --editor windsurf当你运行proxy-doctor check --human后一个典型的“不健康”诊断输出可能如下所示proxy-doctor v0.2.0 Editor: cursor | Platform: Darwin Status: UNHEALTHY (Case A) Root Cause: System HTTP proxy for service Wi-Fi is set to 127.0.0.1:10903, but no process is listening on that port. This is a common residue after quitting a VPN/proxy application. Evidence: - Layer 1 (System Proxy): Found active HTTP proxy on Wi-Fi: 127.0.0.1:10903. - Layer 3 (Port Health): Connection to 127.0.0.1:10903 failed (Connection refused). - Layer 4 (Editor Config): Cursors argv.json contains --proxy-serverhttp://127.0.0.1:10903. Explanation: Your browser may bypass this setting (e.g., using a dedicated proxy extension), but Cursor inherits it and fails to connect.这个输出清晰地告诉你问题出在 Wi-Fi 的网络代理设置上它指向了一个已经不存在的本地端口。同时Cursor 编辑器也通过命令行参数继承了这个错误的配置。3.3 查看与应用修复方案诊断之后下一步就是修复。proxy-doctor秉承“默认只读操作需确认”的安全原则。# 查看针对当前诊断结果推荐的修复命令只显示不执行 proxy-doctor fix运行proxy-doctor fix后你会看到一个修复列表每一条都包含描述、具体的终端命令和风险等级低、中、高。例如针对上面的 Case A它可能会给出Recommended Fixes (apply with caution): 1) [Fix ID: clear-system-http-wi-fi] Description: Disable the stale HTTP proxy setting for Wi-Fi. Command: sudo networksetup -setwebproxystate Wi-Fi off Risk: LOW - This only turns off a non-functional proxy setting. Note: Requires administrator password. 2) [Fix ID: remove-cursor-proxy-arg] Description: Remove the proxy server argument from Cursors argv.json. Command: rm -f ~/Library/Application\ Support/Cursor/argv.json Risk: MEDIUM - This will also remove any other custom command-line arguments for Cursor.重要proxy-doctor fix命令本身是绝对安全的它只是打印出命令。要实际执行修复你必须显式地使用--apply参数。# 交互式应用修复强烈推荐使用此方式 proxy-doctor fix --apply当你加上--apply后proxy-doctor会进入交互模式。它会逐条展示修复建议并询问你是否执行 ([y/N])。默认选项是N否。你只有输入y并回车它才会执行对应的命令。在这个过程中你可以随时按CtrlC中止整个流程。这种设计彻底杜绝了自动化脚本误操作的可能性让你对每一步修改都拥有完全的控制权。4. 进阶集成作为 MCP 工具赋能 AI Agentproxy-doctor不仅仅是一个命令行工具它的一个革命性特性是作为MCP (Model Context Protocol) 服务器运行。MCP 是一种让 AI 大模型如 Claude、Cursor 内置的 AI安全、结构化地调用外部工具的标准协议。这意味着你可以让 AI 助手自己来诊断和解决它的网络问题4.1 安装 MCP 服务器功能首先你需要安装包含 MCP 依赖的版本pip install proxy-doctor[mcp] # 如果使用 pipx pipx inject proxy-doctor proxy-doctor[mcp]4.2 配置 AI 编辑器以使用 MCP这里以 Cursor 编辑器为例。你需要编辑 Cursor 的 MCP 配置文件。创建或编辑配置文件~/.cursor/mcp.json。将以下配置添加到文件中。最关键的一步是找到正确的 Python 解释器路径。{ mcpServers: { proxy-doctor: { command: /usr/local/bin/python3, // 注意这需要替换成你的实际路径 args: [-m, proxy_doctor.mcp_server] } } }如何找到正确的command路径在终端中运行# 方法一使用 which 命令 which python3 # 方法二使用 Python 自身查询更可靠 python3 -c import sys; print(sys.executable)将打印出的路径例如/opt/homebrew/bin/python3或/Users/yourname/.pyenv/shims/python3替换掉上面配置中的/usr/local/bin/python3。4.3 在 AI 对话中直接调用配置完成后重启 Cursor。现在当你与 Cursor 的 AI 对话时如果遇到网络或代理问题你可以直接对它说“我的代码补全功能好像连不上了你能用 proxy-doctor 工具诊断一下吗”Cursor AI 在后台会通过 MCP 协议调用proxy-doctor的diagnose_proxy工具。它不仅能得到完整的 JSON 诊断报告还能调用list_fixes工具获取修复建议并以清晰的对话形式呈现给你例如“我检查了你的系统发现一个常见问题Case A。你的 Wi-Fi 网络设置中残留了一个指向127.0.0.1:10903的 HTTP 代理但这个端口没有程序在监听。这可能是你之前关闭了某个代理软件后留下的。建议的修复方法是运行命令sudo networksetup -setwebproxystate Wi-Fi off。你需要我帮你执行这个命令吗还是你更愿意自己手动在终端运行”这种模式的巨大优势在于AI 助手从一个“问题本身”变成了“解决问题的伙伴”。用户无需了解复杂的命令行甚至不需要知道proxy-doctor这个工具的存在就能在对话中完成诊断和修复。这极大地降低了使用门槛也是proxy-doctor项目前瞻性的体现。5. 后台守护与状态监控对于需要长期、稳定使用 AI 编程工具的用户偶尔运行一次诊断可能不够。网络环境可能会变化例如在公司和家庭网络间切换代理软件自动启停。proxy-doctor从 v0.2.0 版本开始引入了守护进程Daemon模式提供了持续的健康监控能力。5.1 守护进程的运作机制守护进程本质上是一个安装在 macOSlaunchd系统服务管理器下的后台任务。它的工作流程是安装服务当你启动守护进程时proxy-doctor会在~/Library/LaunchAgents/目录下创建一个.plist文件将其注册为一个按计划运行的用户级服务。定期检查默认每 5 分钟该服务会静默地执行一次proxy-doctor check。状态对比与通知服务会将本次检查结果与上一次的结果进行比较。如果代理的健康状态发生了变化例如从“健康”变为“不健康”或者故障案例类型改变了它会立即发送一个原生的 macOS 桌面通知提醒你网络环境有变。本地缓存所有的检查结果和状态都缓存在本地目录~/.proxy-doctor/下不会上传任何数据到网络。5.2 守护进程的管理命令管理守护进程非常简单通过几个子命令即可完成。# 启动守护进程会请求必要的权限 proxy-doctor daemon start # 查看守护进程的当前状态运行中、检查频率、上次检查结果 proxy-doctor daemon status # 停止守护进程 proxy-doctor daemon stop # 手动触发一次立即检查不等待定时任务 proxy-doctor daemon run-now启动守护进程后你可以完全忘记它。当你的 AI 编辑器因为代理问题突然失效时一个及时的 macOS 通知会弹出来告诉你“代理状态已变为不健康 (Case A)”让你能第一时间意识到问题所在而不是盲目地重启编辑器或电脑。5.3 菜单栏快速监控 (SwiftBar)对于喜欢视觉化反馈的用户proxy-doctor还提供了一个 SwiftBar 插件。SwiftBar 是一个轻量级的 macOS 菜单栏工具可以运行脚本并显示其输出。安装 SwiftBar通过brew install swiftbar或从官网下载安装。安装插件将proxy-doctor项目中的插件脚本复制到 SwiftBar 的插件目录。# 假设你已经将项目克隆到本地 cp /path/to/proxy-doctor/plugins/swiftbar/proxy-doctor.5m.sh ~/Library/Application\ Support/SwiftBar/Plugins/ chmod x ~/Library/Application\ Support/SwiftBar/Plugins/proxy-doctor.5m.sh效果SwiftBar 会每 5 分钟运行一次该脚本。脚本会调用proxy-doctor check然后在菜单栏显示一个图标。绿色勾号代理状态健康。红色叉号代理状态不健康。橙色叹号状态未知或检查出错。 点击该图标可以直接看到简明的诊断摘要并有一个“Run Full Diagnosis”的选项点击后会在终端中打开并运行proxy-doctor check --human。这个插件为喜欢“一眼知状态”的用户提供了极大的便利将复杂的诊断结果浓缩成了一个简单的状态指示灯。6. 故障排查与常见问题实录即使工具设计得再完善在实际使用中也可能遇到各种边界情况。以下是我在长期使用和测试中积累的一些常见问题与解决技巧。6.1 诊断结果与预期不符问题运行proxy-doctor check显示“健康”但 Cursor 的 AI 补全仍然无法工作。排查思路确认编辑器确保你诊断的编辑器和你正在使用的编辑器是同一个。用--editor参数明确指定。检查特定项目配置proxy-doctor主要检查用户级和全局编辑器配置。如果你在某个项目的.vscode/settings.json里设置了代理它可能不会被扫描到。手动检查该项目文件夹下的配置文件。更复杂的网络环境有些公司网络会使用 PAC 脚本或复杂的认证代理。proxy-doctor对 PAC 脚本的解析能力有限。此时可以尝试在编辑器中明确设置为“无代理”http.proxy: 或使用直接连接模式看是否能绕过。查看详细日志使用proxy-doctor check不加--human输出完整的 JSON查看evidence字段下的每一个细节。也许问题出在某个未被默认编辑器配置覆盖的深层环境变量里。6.2 修复命令执行失败问题使用proxy-doctor fix --apply时某个修复命令执行失败例如sudo命令密码输入错误或被拒绝。应对策略proxy-doctor的交互式修复是逐条进行的。如果某条命令失败它会打印错误信息然后继续询问下一条。你可以选择跳过失败的这条。对于需要sudo权限的命令如修改系统网络设置请确保你有管理员密码并在提示时正确输入。最安全的方式是不直接应用自动修复而是手动执行。运行proxy-doctor fix将显示的命令一条条复制到终端中手动执行。这样你能更清楚地看到每一步的输出遇到错误也能更好地处理。6.3 MCP 服务器连接失败问题在 Cursor 中配置了 MCP但 AI 助手说无法连接到proxy-doctor工具。排查步骤路径验证再次确认~/.cursor/mcp.json中的command路径绝对正确。使用python3 -c import sys; print(sys.executable)命令确保输出的路径与配置文件中完全一致包括大小写。模块验证在终端中用配置文件中指定的 Python 解释器路径手动运行 MCP 服务器模块看是否报错。/your/actual/python/path -m proxy_doctor.mcp_server如果提示“No module named proxy_doctor”说明这个 Python 环境里没有安装proxy-doctor[mcp]。你需要在这个特定的 Python 环境下重新安装或者修改配置文件指向另一个已安装的 Python 路径。查看 Cursor 日志Cursor 通常会在其日志中记录 MCP 服务器的启动错误。日志文件位置通常在~/Library/Logs/Cursor/或~/.cursor/logs/目录下。查看最新的日志文件搜索“proxy-doctor”或“MCP”关键词能找到具体的错误信息。6.4 与其他网络工具的兼容性问题我同时使用了 ClashX、Surge 等高级网络工具proxy-doctor会干扰它们吗解答完全不会。proxy-doctor是一个纯粹的诊断和只读工具除非你明确使用--apply。它不会修改任何活跃的代理设置。它的作用是帮你理清哪些是“僵尸配置”哪些是正在生效的配置。如果你正在使用 ClashX 的“全局”或“规则”模式并且 AI 工具工作正常那么proxy-doctor的诊断结果很可能是“健康”。如果 AI 工具不工作它可能会帮你发现是不是 ClashX 的“增强模式”在系统层面留下了某些配置而 AI 编辑器错误地引用了它们。7. 安全模型与隐私考量在当今时代一个需要读取系统网络配置和编辑器文件的工具必须将安全和隐私放在首位。proxy-doctor在这方面做了非常清晰和保守的设计。7.1 默认只读零网络传输这是其安全模型的基石。下表概括了它的数据访问边界操作类型访问内容目的数据去向读取系统代理设置 (networksetup)、环境变量 (launchctl)、编辑器配置文件 (settings.json,argv.json, 日志文件)核心诊断功能仅本地处理生成诊断报告后即丢弃原始数据。读取本地网络端口 (通过socket.connect)检查端口监听状态纯本地连接不对外发起任何网络请求。写入~/.proxy-doctor/目录缓存守护进程状态、上次检查结果、更新信息仅限本地磁盘用于实现守护进程的差分通知和更新检查。网络pypi.org仅限proxy-doctor update命令检查新版本。可选的版本更新检查不传输任何诊断数据。绝不访问网络流量内容、密码、密钥、浏览器历史、个人文档。设计上禁止。不相关且无此功能。7.2 审慎的修复应用流程proxy-doctor fix --apply的设计充分体现了“知情同意”原则逐条确认每个修复命令都会单独提示给你反悔的机会。默认拒绝默认选项是N(No)你必须主动输入y才能继续。风险提示每个命令都标注了风险等级低/中/高并附有简单的说明让你明白这个操作具体会做什么。随时中止你可以随时按下CtrlC来中止整个修复流程之前已经执行的命令不会回滚但未执行的命令会全部停止。这种设计使得proxy-doctor即使被集成到 AI Agent 中也能保证安全。AI 可以建议修复但最终的执行权牢牢掌握在用户手中。7.3 开源透明整个项目的代码在 GitHub 上完全公开。这意味着任何有疑虑的开发者都可以审查其源代码确认它没有进行任何恶意操作。这种透明度是建立信任的最佳方式。如果你对某个诊断逻辑或命令有疑问直接去查看相关的 Python 模块如diagnose.py,fixes.py便能一目了然。