当前服务稳定，卡在“加载技能市场”或报网络错误，主因是本地网络未就绪：需依次排查dns解析、代理配置、端口占用及ssl劫持问题。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
WorkBuddy 启动卡在「正在加载技能市场」或登录时报 Network Error、Failed to fetch，基本可以确定是本地网络环境未就绪，而非服务端问题——当前（2026年4月13日）WorkBuddy 服务状态稳定，官方健康页 https://workbuddy.qq.com/status 持续显示绿色。
检查 DNS 解析是否被污染
DNS 失败是最隐蔽的断连原因：WorkBuddy 需要解析 workbuddy.qq.com、claw.workbuddy.qq.com 和模型 CDN 域名，若返回非腾讯云 IP（如 127.0.0.1、私有网段或境外地址），请求会静默失败。
- Windows 执行：
nslookup workbuddy.qq.com，确认结果含100.或182.开头的 IP - macOS/Linux 执行：
dig +short workbuddy.qq.com，排除返回空或超时 - 若异常，临时修改
hosts文件（Windows 路径：C:\Windows\System32\drivers\etc\hosts；macOS/Linux：/etc/hosts），添加一行：100.100.100.100 workbuddy.qq.com - 改完后清系统 DNS 缓存：
ipconfig /flushdns（Win）或sudo dscacheutil -flushcache（macOS）
验证代理配置是否冲突
WorkBuddy 不读取浏览器代理，只认系统级环境变量。若你设过 HTTP_PROXY 或 HTTPS_PROXY，但代理已失效或不支持 WebSocket，Claw 通道和模型拉取会直接中断。
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
- Windows 终端运行：
echo %HTTP_PROXY%，若输出非空，且你不确定代理是否可用，立即执行：set HTTP_PROXY= && set HTTPS_PROXY= - macOS/Linux 终端运行：
echo $HTTP_PROXY，若非空，执行：unset HTTP_PROXY HTTPS_PROXY - 企业网络强制使用代理？必须确保该代理允许访问以下域名与端口：
*.qq.com:443、*.tencent.com:443、localhost:3001（本地 MCP Server） - 杀毒软件或防火墙（如火绒、360、Windows Defender 实时防护）常劫持 TLS 流量，导致 SSL 握手失败——临时关闭再试
确认本地端口未被占用或拦截
WorkBuddy 启动时需监听 3001（MCP Server）、3002（Claw 网关）两个本地端口。若被其他进程占用，或被企业防火墙策略阻断，会导致技能加载失败、远程控制失联。
- Windows 查端口占用：
netstat -ano | findstr :3001，记下 PID，再用tasklist | findstr "PID"查进程名；常见冲突进程：node.exe、java.exe、旧版 Electron 应用 - macOS/Linux 查端口：
lsof -i :3001，若有结果，用kill -9 PID强制释放 - Windows 防火墙例外：确保「允许应用通过 Windows 防火墙」列表中勾选了 WorkBuddy，并同时启用「专用」和「公用」网络
- Linux 用户注意：
/tmp目录需可写，否则claw运行时 socket 文件无法创建，表现为connect ECONNREFUSED 127.0.0.1:3002
绕过 SSL 劫持软件直连
部分企业安全软件（如深信服、奇安信、腾讯电脑管家企业版）会注入根证书并重写 HTTPS 流量，WorkBuddy 的证书校验会拒绝此类连接，错误日志中常出现 ERR_SSL_PROTOCOL_ERROR 或 self signed certificate in certificate chain。
- 最简验证方式：关闭所有安全类软件的「HTTPS 扫描」「网页防护」「SSL 拦截」模块，重启 WorkBuddy
- macOS 用户额外检查「系统设置 → 隐私与安全性 → 安全性」中是否有未知证书被信任，移除可疑项
- Windows 用户打开「证书管理器」（
certmgr.msc），在「受信任的根证书颁发机构」里查找非微软/腾讯/GlobalSign 的自签名证书，右键→「删除」 - 此问题不会影响浏览器访问，但会彻底阻断 WorkBuddy 的后台服务初始化
真正容易被忽略的是：WorkBuddy 的网络检测逻辑不依赖 ping，而是发起真实 HTTPS 请求并等待响应头。所以即使 ping workbuddy.qq.com 通，DNS 或 TLS 层出问题照样失败。建议按顺序做 DNS → 代理 → 端口 → SSL 四步排查，不要跳步。
