Hermes Agent日志查看全攻略：从新手到专家的实用技巧与排查指南
Hermes Agent的日志系统分为五个关键部分，用于精准定位问题：一、控制台实时输出；二、位于~/.hermes/sessions/目录下的结构化JSON会话日志；三、存储于~/.hermes/state.db的SQLite元数据数据库；四、~/.hermes/audit.log审计日志；五、由RotatingFileHandler配置管理的轮转日志文件。
当Hermes Agent启动后响应异常或任务执行结果不符预期时，直接检查其运行日志是最高效的故障排查方法。
其日志系统按用途和格式进行了细致划分，分布在不同的位置。掌握各类日志的定位与解读方法，是进行有效问题诊断的基础。以下将详细解析这五类日志的查看技巧。
一、查看控制台实时输出日志
最直接的诊断方式是观察启动时的终端控制台输出。若启动命令未重定向输出，所有INFO及以上级别的日志将实时打印到屏幕，其中包含任务调度、工具调用及HTTP请求等核心操作记录，是快速验证服务状态与响应是否正常的首选途径。
排查步骤如下：
首先，确认Hermes Agent是否在前台运行。直接观察终端窗口是否有持续滚动、并带有INFO或DEBUG标识的日志行。
若进程已转入后台，可使用ps aux | grep run_agent.py命令获取其进程ID（PID），随后通过lsof -p [PID] -a -d 1 -o检查其标准输出（stdout）是否仍关联有效终端。
需注意，若启动时使用了类似> /dev/null 2>&1的命令将输出丢弃，则控制台将无任何显示。此时应转向后续介绍的文件日志进行排查。
二、读取结构化会话JSON日志
每次与Hermes Agent的交互均会生成一个独立的JSON文件，归档于~/.hermes/sessions/目录。这种结构化格式清晰记录了时间戳、事件类型、完整输入输出及潜在错误详情，是追溯单次会话全貌、进行深度问题复现的关键数据源。
查看方法：
第一步，进入日志目录：cd ~/.hermes/sessions/。
第二步，列出最新的5个会话文件，快速了解近期活动：ls -t *.json | head -5。
第三步，如需详细审查最新会话的完整内容，可使用jq工具格式化输出并分页浏览：jq '.' $(ls -t *.json | head -1) | less。
第四步，若需快速提取该会话中的所有错误记录，可使用命令：jq -r 'select(.error != null) | "\(.timestamp) \(.event_type): \(.error)"' $(ls -t *.json | head -1)。
三、查询SQLite会话元数据库
JSON文件适合单会话分析，但跨会话的全局检索效率较低。为此，Hermes Agent将所有会话的基础元数据（如会话ID、创建时间、更新时间、状态等）持久化存储在SQLite数据库~/.hermes/state.db中。通过SQL查询，可高效获取会话生命周期概览，无需遍历大量文件。
常用查询示例：
打开数据库连接：sqlite3 ~/.hermes/state.db。
查看所有数据表：.tables。
查询最近10个已完成的会话：SELECT id, created_at, updated_at, status FROM sessions WHERE status = 'completed' ORDER BY updated_at DESC LIMIT 10;。
关联查询特定会话（假设ID为SESSION_ID_HERE）所调用的工具详情：SELECT t.tool_name, t.status, t.duration_ms FROM tool_calls t JOIN sessions s ON t.session_id = s.id WHERE s.id = 'SESSION_ID_HERE' ORDER BY t.created_at;。
四、检查审计日志audit.log
所有涉及安全敏感的操作，如新技能安装、权限变更、访问拒绝等，均会记录于~/.hermes/audit.log。此文件为按时间追加的纯文本日志，主要用于合规性审计与安全风险识别。
审计日志查阅方法：
首先验证文件存在且非空：test -s ~/.hermes/audit.log && echo "audit.log is present and not empty" || echo "audit.log missing or empty"。
查看最新的20条审计记录：tail -20 ~/.hermes/audit.log。
筛选失败或拒绝类安全事件：grep -E "(deny|fail|reject|unauthorized)" ~/.hermes/audit.log | tail -15。
按小时统计拒绝操作频次，识别异常模式：awk '{print substr($1, 1, 13)}' ~/.hermes/audit.log | grep -v "^$" | sort | uniq -c | sort -nr | head -5。
五、读取配置指定的RotatingFileHandler日志
此类日志属于高级配置项。若在 定位与查看步骤： 首先，确定日志文件的实际存储位置。通过以下命令搜索配置： 假设找到的路径为相对路径 查看当前主日志文件的最新50行： 列出所有按序号或日期轮转生成的历史日志文件： 检查最近一个归档日志中的错误或异常（假设归档为gzip压缩格式）： 掌握以上五类日志的查看方法，即可系统化地定位Hermes Agent的运行问题。清晰的日志记录是故障排查中最可靠的线索来源。run_agent.py或gateway/run.py中配置了RotatingFileHandler
grep -r "RotatingFileHandler" ~/.hermes/ --include="*.py" -A 3，重点关注filename=参数的值。logs/hermes-agent.log（通常基于配置所在目录），则需确保目录存在：mkdir -p ~/.hermes/logs。tail -n 50 ~/.hermes/logs/hermes-agent.log。ls -lt ~/.hermes/logs/hermes-agent.log.*。zcat ~/.hermes/logs/hermes-agent.log.1.gz 2>/dev/null | grep -i "error\|exception" | tail -10 || grep -i "error\|exception" ~/.hermes/logs/hermes-agent.log.1 2>/dev/null | tail -10。