workbuddy调用自定义技能返回502错误，主因是后端服务未监听指定端口、绑定地址非0.0.0.0、防火墙拦截或端口被占用；需依次验证进程与端口、改host为0.0.0.0、关闭防火墙拦截、更换未占用端口。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在WorkBuddy中调用自定义技能时返回502错误，且已确认该技能依赖本地后端服务，则问题极可能源于后端服务未正常监听指定端口、端口被占用或网络策略拦截。以下是针对性排查与修复步骤：
一、验证后端服务进程是否运行并监听目标端口
该步骤用于确认自定义技能所依赖的本地HTTP服务（如Flask/FastAPI启动的服务）实际处于活动状态，并绑定到技能配置中声明的地址与端口。若进程未启动或监听地址不匹配，WorkBuddy发起的HTTP请求将被系统拒绝，触发502网关错误。
1、打开终端（Windows：命令提示符或PowerShell；macOS/Linux：终端），执行进程检查命令。
2、Windows用户输入：netstat -ano | findstr :[端口号]（将[端口号]替换为技能配置中填写的实际端口，例如8000）。
3、macOS/Linux用户输入：lsof -i :[端口号] 或 ss -tuln | grep :[端口号]。
4、若无任何输出，说明该端口未被任何进程监听；若有输出但PID对应进程非您的后端服务，请记录PID并使用任务管理器（Windows）或kill -9 [PID]（macOS/Linux）终止冲突进程。
二、检查后端服务绑定地址是否为0.0.0.0而非127.0.0.1
WorkBuddy作为独立客户端进程，默认通过localhost或127.0.0.1访问本地服务。若后端服务仅绑定127.0.0.1，在部分系统安全策略或容器化部署下可能出现回环通信异常；而绑定0.0.0.0可确保所有本地网络接口均可接收请求，兼容性更强。
1、定位后端服务启动脚本（如main.py、app.py或run.sh）。
2、查找类似app.run(host='127.0.0.1', port=8000)或uvicorn.run(..., host="127.0.0.1")的语句。
3、将host参数修改为"0.0.0.0"，例如改为app.run(host='0.0.0.0', port=8000)或uvicorn.run(..., host="0.0.0.0")。
4、保存文件，重启后端服务进程。
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
三、确认系统防火墙未拦截本地回环通信
部分企业环境或安全软件会启用高级网络过滤规则，即使针对127.0.0.1或0.0.0.0的本地连接也可能被误判并阻断，导致WorkBuddy无法建立TCP连接，从而收到上游无响应的502错误。
1、Windows用户进入“控制面板 > Windows Defender 防火墙 > 高级设置”，在“入站规则”中查找是否启用“Core Networking Diagnostics (ICMPv4-In)”或类似名称的规则；若存在，右键选择“禁用规则”。
2、临时关闭第三方安全软件（如360、火绒、McAfee）的网络防护模块。
3、macOS用户前往“系统设置 > 隐私与安全性 > 防火墙”，点击“防火墙选项”，取消勾选“阻止所有传入连接”；若已勾选，关闭后点击“确定”并重新启用防火墙。
4、重启WorkBuddy客户端与后端服务，再次测试技能调用。
四、验证端口是否被其他应用占用且未释放
当后端服务异常退出（如崩溃、强制终止）后，操作系统可能未及时回收端口资源，导致该端口处于TIME_WAIT或CLOSE_WAIT状态，新服务尝试绑定时失败，表面表现为“启动成功但无法访问”，WorkBuddy请求超时后返回502。
1、使用与步骤一相同的命令（netstat 或 lsof/ss）再次检查目标端口状态，关注State列是否显示TIME_WAIT或LISTEN但无对应有效PID。
2、Windows用户执行：netsh int ipv4 set dynamicport tcp start=10000 num=50000，扩大动态端口范围以降低冲突概率。
3、macOS/Linux用户执行：sudo sysctl -w net.inet.tcp.msl=1000（macOS）或sudo sysctl -w net.ipv4.tcp_fin_timeout=30（Linux），缩短端口回收等待时间。
4、修改自定义技能配置中的端口号为一个全新未使用端口（如8081、9001），同步更新后端服务启动参数，重启服务。
