OpenClaw日志排查需按五步操作：一、实时跟踪日志流；二、JSON+json结构化过滤；三、聚焦warn/error级日志；四、运行doctor诊断环境；五、查看原始.jsonl会话文件。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用 OpenClaw 过程中遇到功能异常、响应延迟或任务中断，但控制台未显示明确报错，问题很可能隐藏在日志细节中。以下是针对 OpenClaw 日志进行高效定位与分析的具体操作方法：
一、实时跟踪最新日志流
该方法用于捕获刚发生的异常行为，适用于问题复现后立即介入的场景，可同步输出应用主日志及每个会话的关键事件摘要（如工具调用失败、模型响应超时等）。
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
为 OpenClaw 创建可直接分流的 GitHub issue 草稿，用于报告代理缓慢、损坏、无响应、工具匮乏、性能下降或“不够智能”等问题。使用 ...
2、重点查看输出中是否包含 Gateway offline、session queue full 或 model fallback triggered
3、若连续出现 rate limit exceeded，需核查当前所用模型 API 的配额状态
四、自动诊断常见配置与环境问题
doctor 命令会主动检测 OpenClaw 运行所依赖的基础条件，包括 Docker 守护进程状态、关键端口占用、Gateway 服务连通性、配置文件语法有效性等，是启动任何深度排查前的必选动作。
1、执行基础诊断：openclaw doctor
2、若诊断报告中提示 port 8080 is occupied by another process，需立即执行 netstat -tuln | grep 8080 定位冲突进程
3、添加 --fix 参数尝试自动修复：openclaw doctor --fix（仅对权限缺失、缺失配置项等可逆问题生效）
五、查看完整会话级原始日志文件
命令行日志可能被截断或未记录底层异常堆栈，此时需访问磁盘上的原始 .jsonl 文件，其按会话粒度存储完整调用链、工具输入/输出、模型请求原始 payload 及完整 error stacktrace，是定位“黑盒”问题的最终依据。
1、进入会话日志目录：cd ~/.openclaw/agents/main/sessions/
2、列出最近创建的会话文件：ls -t *.jsonl | head -n 5
3、查看指定会话的最后 20 条记录：tail -n 20 20260312_142833_abcd1234.jsonl
4、搜索该文件中是否存在 "error": true 字段或非空 "exception" 字段值
