openclaw agent故障排查需按五步实操：一、实时跟踪日志流；二、json+json结构化过滤；三、聚焦warn/error级日志；四、分离application与session日志；五、先执行openclaw doctor验证基础环境。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在运行OpenClaw时发现Agent行为异常、任务卡死或响应缺失，则很可能是由底层调用链中的错误日志线索未被及时识别所致。以下是快速定位Agent运行故障的实操方法：
一、实时跟踪最新日志流
该方法用于捕获刚发生的异常行为，适用于问题复现后立即介入的场景，可同步输出Application主日志及每个会话的关键事件摘要（如工具调用失败、模型响应超时等）。
1、在终端中执行：openclaw logs --follow
2、观察输出中是否出现以ERROR或FATAL开头的行
3、若发现某次会话 ID 后紧随tool execution timeout，说明对应 Skill 执行卡死，需进一步检查该技能的网络依赖或超时配置
二、结构化过滤错误日志（JSON + jq）
当默认日志混杂大量 INFO 级信息时，将日志转为 JSON 格式并借助 jq 工具精准提取关键字段，可大幅提升排查效率，尤其适合批量分析历史异常模式。
1、执行命令获取结构化日志流：openclaw logs --json
2、仅筛选 ERROR 级别日志：openclaw logs --json | jq 'select(.level == "ERROR")'
3、进一步定位含特定关键词的错误：openclaw logs --json | jq 'select(.message | contains("connection refused"))'
三、聚焦警告与错误级别日志
该方式跳过冗余的调试与常规信息，直接呈现系统已识别的风险信号，适用于高频率刷屏场景下的快速人工扫视。
1、运行过滤命令：openclaw logs --level warn
本次更新实现飞书插件 npm 独立分发，新增 Ollama 本地模型配置及 openclaw 命令别名。引入 SQLite 持久化队列，支持断点续传。全面集成飞书、钉钉、企业微信及 QQ 官方渠道，优化阿里云百炼模型选择。修复多 Agent 路由、定时任务校验及配对授权等关键问题，提升系统稳定性与兼容性。
2、重点查看输出中是否包含Gateway offline、session queue full或model fallback triggered
3、若连续出现rate limit exceeded，需核查当前所用模型 API 的配额状态
四、分离查看Application与Session日志
OpenClaw日志分为两类：Application日志反映系统运行状态，Session日志记录每个Agent会话的完整交互细节。混淆二者将导致误判根源。
1、查看最新Application日志：tail -n 100 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log
2、定位指定Agent的Session日志路径：ls -t ~/.openclaw/agents/*/sessions/*.jsonl | head -n 1
3、读取该Session日志并筛选失败动作：jq 'select(.status == "failed")' [session_path]
五、结合doctor命令进行上下文验证
doctor命令可主动检测OpenClaw运行所依赖的基础条件，包括Docker守护进程状态、关键端口占用、Gateway服务连通性、配置文件语法有效性等，是启动任何深度排查前的必选动作。
1、执行基础诊断：openclaw doctor
2、若诊断报告中提示port 8080 is occupied by another process，需立即执行：netstat -tuln | grep 8080定位冲突进程
3、若提示config syntax error in /home/user/.openclaw/openclaw.json，使用JSON5校验器验证语法完整性
