晚上十点赶一份明早要报的材料agent 第一句话就甩来一个WPS_AGENT_OFFLINE文档连不上活干不了。这种时刻最忌讳病急乱投医——卸载重装、换模型、改提示词一圈折腾半小时问题还在。这篇把我的排查顺序写成一页清单照着走五分钟内基本能定位。先搞清这个错误码在说什么WPS_AGENT_OFFLINE的含义是WPS 或者 WPS 里的察元加载项没连上本机的 sidecar 服务。注意它和模型配置无关、和 API key 无关、和你用哪个智能体客户端也无关——断的是WPS 到本机服务这一段链路。搞清方向才不会去改八竿子打不着的配置。顺便把几个容易混淆的错误码摆一起WPS_AGENT_OFFLINE是 WPS 没连上本机服务MODEL_NOT_CONFIGURED是校对模型没配DOCUMENT_TOO_LARGE是文档超了约 80k 阈值该分块LICENSE_REQUIRED是免费额度用尽它不弹购买窗看到别当成故障。四个码四个方向认清再动手能省一半时间。第一步探 sidecar 活没活一条命令的事curlhttp://127.0.0.1:62588/healthz返回online说明 sidecar 活得好好的问题在 WPS 侧直接跳第三步。连接被拒或者超时说明 sidecar 压根没起来走第二步。Windows 上 PowerShell 里的 curl 有时是 Invoke-WebRequest 的别名行为不一样嫌麻烦就敲 curl.exe 全称或者干脆把地址粘到浏览器地址栏看到 online 字样就是通的。第二步sidecar 没起来的处理先看自启项还在不在Windows 查注册表HKCU\RunmacOS 看 LaunchAgentLinux 看systemd --user。安装脚本装的时候会注册开机自启正常情况下它应该一直在。懒得逐项查就重跑一遍安装脚本它自带四步体检jsaddons 目录检查 →/healthz探活 → initialize 握手 → 桥接工具验证哪一步断的直接在输出里指出来比人肉排查快得多。macOS 和 Linux 用户注意服务分别由 LaunchAgent 和 systemd --user 托管用对应机制看状态即可思路一致。第三步sidecar 活着查 WPS 侧三件事按序确认WPS 开着没有没开就先开或者干脆让 agent 调wps_launch冷启动加载项加载了没有看 jsaddons 目录和 publish.xml 是否就位WPS 里能不能看到察元的菜单用wps_status做分层健康检查链路断在哪一层它会直接告诉你这比猜快十倍。另外回想一下最近有没有更新过版本加载项文件落在 jsaddons 目录、靠 publish.xml 注册更新后偶尔遇旧文件残留WPS 重启一次通常就好。顺带一提4.1.2 版本之后 sidecar 是隐藏启动的没有黑窗关窗也不会杀服务。别再用那个黑色命令行窗口还开着吗判断服务死活那个窗口已经不存在了。第四步查 MCP 客户端这一段如果 WPS 侧都正常个别智能体客户端还是连不上重连一次claude mcpadd--transporthttp chayuan-wps-mcp http://127.0.0.1:62588/mcp配置文件党也可以直接在项目根放一份.mcp.json内容就是{mcpServers:{chayuan-wps-mcp:{url:http://127.0.0.1:62588/mcp}}}提交进团队仓库新人克隆下来开箱即用省去逐台注册的口舌。要可视化验证就用 MCP Inspectornpx modelcontextprotocol/inspector传输选 Streamable HTTP地址填http://127.0.0.1:62588/mcp点 Connect 看握手。Inspector 里还能直接调 wps_statusWPS 侧断在哪一层工具返回写得明明白白比隔着客户端猜靠谱。第五步还不行查环境按命中率排序杀毒软件拦了 sidecar加白名单62588 端口被别的进程占了机器刚从休眠唤醒网络栈还没就绪等半分钟重试。这三样占了剩余案例的大头。还有一个偏门但真实的原因同机装过多个版本的加载项目录WPS 加载了旧版。重跑安装脚本会顺带把目录归位比手动翻文件夹稳。排查时记住一个原则每改一处就验证一次别攒了三处改动再测——变量一多好不容易缩小到的范围又会被搅浑。一句收尾信创替换推进这两年WPS 上的 AI 工具链也越来越长链路长了一节排查就多一层——但只要按服务探活 → WPS 侧 → 客户端侧 → 环境的顺序走基本不会绕远路。把这篇存个书签下次半夜报错时照单点菜比深呼吸管用。