必须立即定位本地日志文件：网关版日志路径为~/.openclaw/logs/，macOS安全监控版路径不同；error.log是唯一记录ERROR级异常的主文件，可用tail -f实时跟踪或openclaw logs命令结构化过滤。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当AionClaw任务执行失败、界面卡在“处理中”、定时任务突然中断或数字专家无响应时，必须立刻定位日志源头——它不显示在控制台，也不弹窗提示，错误信息默认沉入本地文件系统，且不同失败类型对应不同日志文件。
确认AionClaw当前部署方式
先判断你用的是哪类安装包：打开AionClaw客户端 → 点击右上角「设置」→ 查看「版本信息」栏末尾是否含「-security」字样。含则为 macOS 安全监控版，日志路径与网关版不同；不含则为标准网关版，日志默认写入项目根目录或 【~/.openclaw/logs/】。
若通过官网下载的桌面安装包（非源码启动），绝大多数情况属于网关版，无需关心 npm 或 python 启动路径，直接跳到下一步。
快速定位并打开 error.log 文件
第一步：打开访达（Finder）→ 按 Cmd+Shift+G → 输入 【~/.openclaw/logs/】 → 回车
第二步：若目录存在但为空，说明服务尚未写入日志，需先触发一次失败任务（例如在「自动化」模块新建一个调用不存在技能的任务并运行）
第三步：双击打开 error.log —— 这是唯一记录 ERROR 级异常的主文件，包含堆栈、时间戳、触发模块名（如 skill_email_fetcher）、Agent ID 和完整错误消息。不要打开 agent.log 或 gateway.log 做初步排查，它们不记录任务执行失败的根因。
终端中实时跟踪最新错误
方法一：基础监听（推荐新手）
打开终端 → 执行：tail -f ~/.openclaw/logs/error.log
这一步操作起来很简单，直接回车即可看到最新错误流，任务失败瞬间就会刷出带 [ERR] 前缀的行。
方法二：结构化过滤（适合排查历史问题）
执行：openclaw logs --json | jq 'select(.level == "ERROR")'
注意：此命令要求已全局安装 openclaw CLI 工具，若报 command not found，请改用方法一。
方法三：按关键词抓取（定位特定故障）
例如任务卡死在模型调用环节，可执行：openclaw logs --json | jq 'select(.message | contains("timeout") or .message | contains("model"))'
从日志内容反推常见失败原因
看到 【"Skill 'web_search' returned empty result after 3 retries"】 → 外部 API 不可达或配额耗尽，立即检查 TaoToken 控制台剩余额度；
看到 【"Failed to access ~/.openclaw/config.yaml: Permission denied"】 → 当前用户对配置目录无读写权限，需执行 chmod -R 755 ~/.openclaw；
看到 "Memory store init failed: database is locked" → 多个 AionClaw 实例同时运行，关闭所有窗口后重启客户端；
看到 "Gateway offline" 或 "session queue full" → 服务进程已崩溃，需在终端执行 openclaw gateway restart 恢复。
