“agent服务未连接”说明本地agent.exe进程未运行或通信中断，需检查任务管理器中agent.exe是否存在、18789端口是否监听、sc query workbuddyagent是否返回state: 4 running，并排除防火墙拦截与dns解析失败。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
WorkBuddy客户端显示“Agent服务未连接”，说明本地后台代理进程未运行或通信链路中断，此时Claw通道、本地MCP Server、模型加载等功能全部失效，必须立即恢复Agent进程存活与网络可达性。
确认Agent进程是否真实运行
很多用户误以为任务栏图标存在即代表Agent在运行，其实它只是UI进程，真正干活的是后台的agent.exe（Windows）/agent（macOS/Linux）——这个进程可能已崩溃退出，但UI毫无提示。
打开任务管理器 → 切换到「详细信息」页签 → 在搜索框输入agent.exe；若无任何结果，说明进程已死亡。
更可靠的验证方式是查端口：WorkBuddy Agent默认监听18789端口，Windows执行netstat -ano | findstr :18789，若无输出，即确认服务未启动。
检查Agent服务注册与运行状态
Windows系统下，Agent必须以Windows服务形式托管，否则远程重启、用户登出后必然断连。直接双击agent.exe启动是无效的，它会几秒后静默退出。
以管理员身份运行PowerShell，执行：sc query WorkBuddyAgent。
若返回STATE: 4 RUNNING，说明服务存在且正常；若为STOPPED、QUERY_FAILED或提示“[SC] EnumQueryServicesStatus:OpenService FAILED 1060”，则服务未注册成功或路径错误。
【binPath路径中含空格却未加转义引号会导致sc create静默截断，例如"C:\Program Files\WorkBuddy\agent.exe"必须写成"\"C:\Program Files\WorkBuddy\agent.exe\""】
手动启动Agent服务并验证连通性
第一步：确保服务已注册，再执行启动命令：sc start WorkBuddyAgent。
第二步：等待5秒，立即检查日志——进入%LOCALAPPDATA%\WorkBuddy\agent\logs\，打开最新日期的log文件，查找包含“gateway connected”或“claw server started”的行。
第三步：终端执行curl -v http://127.0.0.1:18789/ping（Windows可用PowerShell内置Invoke-WebRequest替代），返回HTTP 200且body为{"status":"ok"}才算真正就绪。
如果curl报错Connection refused，说明服务虽启动但监听地址配置错误，需进入Claw设置页将监听地址从127.0.0.1改为0.0.0.0。
排除防火墙与杀软拦截
Windows Defender防火墙默认阻止未知程序的出站连接，而Agent必须主动连接workbuddy.codebuddy.cn，被拦后日志只卡在“connecting to gateway…”无后续。
方法一（快速验证）：临时关闭防火墙，执行netsh advfirewall set allprofiles state off，再重启WorkBuddy Agent服务，看是否恢复。
方法二（长期方案）：打开「高级安全 Windows Defender 防火墙」→ 左侧选「出站规则」→ 右侧「新建规则」→ 程序 → 浏览定位到C:\Program Files\WorkBuddy\agent.exe → 允许连接 → 完成。
国产杀软如360、腾讯电脑管家常深度hook网络调用，即使加了白名单也可能拦截；右键杀软图标 → 「退出防护」后测试，可快速定位是否为其所致。
验证DNS与网络可达性
Agent连接失败未必是服务没起，也可能是根本解析不了目标域名。WorkBuddy依赖workbuddy.codebuddy.cn进行认证握手，若DNS污染或本地hosts劫持，就会表现为“服务未连接”。
在CMD中执行：nslookup workbuddy.codebuddy.cn。
若返回*** Can't find workbuddy.codebuddy.cn: No response from server，或IP不是腾讯云段（如100.x、182.x开头），说明DNS异常。
临时修复：用记事本以管理员身份打开C:\Windows\System32\drivers\etc\hosts，末尾添加一行100.100.100.100 workbuddy.codebuddy.cn，保存后执行ipconfig /flushdns。
