Hermes Agent运行日志查看方法与详细步骤

掌握Hermes Agent日志查看方法是高效排查运行问题的关键。其日志系统主要分为五类：一、控制台实时输出日志；二、存储在~/.hermes/sessions/目录下的结构化JSON会话日志；三、记录于~/.hermes/state.db中的SQLite元数据库；四、用于安全审计的~/.hermes/audit.log文件；五、通过RotatingFileHandler配置的轮转归档日志。

当您启动Hermes Agent后，如果遇到服务无响应、任务执行异常或功能表现不符合预期的情况，该如何快速定位问题？直接查看其运行日志是最高效的故障排查方法。

然而，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查询，您可以高效地获取会话的生命周期概况和统计信息，无需遍历大量JSON文件。

常用查询示例：

打开数据库：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日志

最后一类属于自定义配置日志。如果您在run_agent.py或gateway/run.py等启动脚本中配置了RotatingFileHandler，则运行时日志会根据您预设的文件大小或时间周期进行轮转归档，并写入指定路径。这种配置适用于需要长期运行并保留历史日志的生产环境。

定位与查看此类日志的步骤：

首先，需要确定日志文件的实际存储位置。可通过以下命令搜索配置：grep -r "RotatingFileHandler" ~/.hermes/ --include="*.py" -A 3，重点关注filename=参数指定的路径。

假设找到的路径为logs/hermes-agent.log（此为相对路径，通常基于配置文件的目录），请确保目录存在：mkdir -p ~/.hermes/logs。

查看当前主日志文件的最新50行内容：tail -n 50 ~/.hermes/logs/hermes-agent.log。

列出所有轮转生成的历史日志文件：ls -lt ~/.hermes/logs/hermes-agent.log.*。

检查最近一个归档日志中是否存在错误（假设归档文件为gzip压缩格式）：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。

综上所述，这便是Hermes Agent五大类运行日志的完整查看指南。遇到问题时，请根据症状选择合适的日志源进行排查。清晰的日志记录是定位与解决系统问题的首要依据。