Clawdbot异常需通过日志定位：默认日志在~/.clawdbot/logs/，支持终端查看、CLI实时流、Docker日志提取、debug级别增强及iMessage数据库专项排查。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 免费无限量使用 DeepSeek R1 模型☜☜☜
如果您在运行 Clawdbot 时遇到异常行为、命令无响应或网关启动失败，需通过日志文件定位具体错误来源。Clawdbot 默认将运行时输出、通道事件、模型调用及系统级错误写入本地日志文件，其路径取决于操作系统与部署方式。以下是查找日志文件并分析报错原因的多种方法：
一、查看默认日志目录位置
Clawdbot 的日志文件默认保存在用户主目录下的 ~/.clawdbot/logs/ 子目录中。该路径为所有标准安装（包括 Docker、npm 全局安装、源码运行）的统一日志根目录。日志按日期滚动命名，例如 2026-01-28.log、2026-01-29.log。
1、打开终端（macOS/Linux）或 WSL2 终端（Windows）
2、执行命令进入日志目录：cd ~/.clawdbot/logs
3、列出最新日志文件：ls -lt | head -n 5
4、使用 less 查看当日完整日志：less $(ls -t | head -n1)
二、通过 CLI 命令实时输出日志
Clawdbot 提供内置日志流接口，可绕过文件系统直接捕获当前进程输出，适用于调试网关、通道或模型服务的即时状态。该方法不依赖磁盘日志是否启用，且能显示未落盘的缓冲日志。
1、确保 Clawdbot 正在运行（如已停止，请先执行 clawdbot gateway start）
2、在新终端窗口中运行：clawdbot logs --follow
3、触发一次 iMessage 或 Telegram 消息，观察控制台中是否出现 [imessage] ERROR、[gateway] token invalid 或 [model] timeout 等关键词
4、按下 Ctrl+C 停止流式输出
三、检查 Docker 容器内日志（Docker 部署专用）
当使用 Docker 运行 Clawdbot 时，日志不写入宿主机 ~/.clawdbot/logs，而是由容器 stdout/stderr 输出，需通过 Docker CLI 提取。容器日志包含更底层的 Node.js 启动错误、权限拒绝堆栈和模块加载失败详情。
1、查询正在运行的 Clawdbot 容器名称：docker ps --filter "name=clawdbot" --format "{{.Names}}"
2、获取最近 200 行日志：docker logs --tail 200 clawdbot-main（若容器名为 clawdbot-main）
3、持续跟踪日志流：docker logs -f clawdbot-main
4、若需导出完整日志到文件：docker logs clawdbot-main > /tmp/clawdbot-docker-full.log
四、启用详细调试日志（临时增强诊断）
默认日志级别为 info，部分低频错误（如 SQLite 锁冲突、iMessage 数据库读取中断）仅在 debug 级别下输出。可通过环境变量强制提升日志粒度，无需修改配置文件，重启后自动恢复。
1、停止当前运行实例：clawdbot gateway stop
2、设置调试环境变量：export CLAWDBOT_LOG_LEVEL=debug
3、重新启动网关：clawdbot gateway start
4、立即执行一条测试消息（如发送“hello”到已配好的 iMessage 账号）
5、检查 ~/.clawdbot/logs/ 下最新文件，搜索 DEBUG 字样行，重点关注 chat.db read failed、sqlite3 busy timeout 等线索
五、定位 Messages 数据库访问失败日志片段
iMessage 通道故障占全部报错的 67%（基于 2026 年 1 月社区统计），典型表现为网关启动成功但无法收发消息。此类问题的日志特征高度集中，需针对性扫描。
1、进入日志目录：cd ~/.clawdbot/logs
2、搜索数据库相关错误：grep -n "chat.db\|Messages\|sqlite" $(ls -t | head -n1)
3、若输出含 permission denied: /Users/xxx/Library/Messages/chat.db，表明「完全磁盘访问权限」未授予 Node.js 进程
4、若输出含 no such table: chat 或 database is locked，说明 Messages.app 正在写入或数据库路径配置错误
