“网络连接失败”表明tcp或tls握手未建立，需底层排查：先验证dns解析是否污染（检查workbuddy.qq.com等域名是否返回腾讯云ip），再清除http_proxy/https_proxy环境变量冲突，接着确认3001/3002端口未被占用或防火墙拦截，最后排除杀毒软件tls劫持。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
WorkBuddy模型报错提示“网络连接失败”，说明客户端在发起请求时未能建立到目标服务端点的完整TCP连接或TLS握手失败，不是模型响应慢或超时，而是根本未发出有效请求——此时重试、换模型、清缓存都无效，必须从网络链路底层排查。
确认DNS解析是否被污染
WorkBuddy需解析workbuddy.qq.com、claw.workbuddy.qq.com、workbuddy.codebuddy.cn三个核心域名。若DNS返回127.0.0.1、192.168.x.x、境外IP或空响应，请求会静默失败，界面只显示“网络连接失败”。
Windows用户打开命令提示符，执行：nslookup workbuddy.qq.com，检查结果中是否含100.或182.开头的腾讯云IP段；macOS/Linux用户执行：dig +short workbuddy.qq.com，若无输出或返回异常IP，即为DNS污染。
临时修复：编辑hosts文件（Windows路径C:\Windows\System32\drivers\etc\hosts，macOS/Linux路径/etc/hosts），添加一行：100.100.100.100 workbuddy.qq.com，保存后运行ipconfig /flushdns（Win）或sudo dscacheutil -flushcache（macOS）清缓存。
检查系统级代理与环境变量冲突
WorkBuddy不读取浏览器代理，但会继承系统环境变量HTTP_PROXY和HTTPS_PROXY。若变量已设置但代理不可用，所有出站请求都会卡死在CONNECT阶段，直接触发“网络连接失败”。
方法一：临时清除变量
Windows终端执行：set HTTP_PROXY= && set HTTPS_PROXY=；macOS/Linux终端执行：unset HTTP_PROXY HTTPS_PROXY。
方法二：验证代理有效性
执行curl -v https://workbuddy.qq.com，观察是否卡在* Connected to ...之后无后续；若卡住，说明代理不通，必须停用或更换。
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
【注意】企业网络强制使用代理时，必须确保该代理明确允许访问*.qq.com:443、*.tencent.com:443、localhost:3001（本地MCP Server）这三个地址和端口，缺一不可。
验证本地端口是否被占用或拦截
WorkBuddy启动时需监听3001（MCP Server）、3002（Claw网关）两个本地端口。若被其他进程占用，或被防火墙策略阻断，会导致技能加载失败、远程控制失联，并统一报“网络连接失败”。
第一步：查端口占用
Windows执行：netstat -ano | findstr :3001，记下PID；再用tasklist | findstr "PID"查进程名；常见冲突进程：node.exe、java.exe、旧版Electron应用。
第二步：释放端口
若确认冲突，执行taskkill /F /PID PID号强制结束；macOS/Linux执行：lsof -i :3001 → kill -9 PID。
第三步：放行防火墙
Windows Defender防火墙中新建入站规则，针对TCP端口3001、3002设为“允许连接”，配置文件勾选“域”“专用”“公用”全部选项。
排除杀毒软件深度拦截
火绒、360、腾讯电脑管家等国产杀软常劫持TLS流量并重签证书，导致WorkBuddy与服务端SSL握手失败——现象是ping通、nslookup正常，但请求始终无响应，日志停留在“connecting to gateway…”。
临时关闭杀软防护模块测试：右键杀软系统托盘图标 → 「退出防护」或「暂停实时保护」；若关闭后恢复正常，说明是深度hook导致，需在杀软白名单中添加C:\Program Files\WorkBuddy\workbuddy.exe及agent.exe，并禁用“网络流量扫描”功能。
