调试技巧

环境变量

Hermes Agent 的调试行为主要由环境变量控制：

日志级别

# 开启详细日志（包含工具调用详情、API 请求/响应）
export HERMES_LOG_LEVEL=DEBUG

# 只看 warning 及以上
export HERMES_LOG_LEVEL=WARNING

Debug 模式

# 开启 debug 模式 — 输出更多内部状态
export HERMES_DEBUG=1

轨迹保存

# 保存完整的对话轨迹（JSON 格式）
export HERMES_SAVE_TRAJECTORIES=1

轨迹文件保存在 ~/.hermes/trajectories/ 目录下，每个会话一个 JSON 文件，包含：

• 所有消息（system/user/assistant/tool）
• 工具调用的参数和返回值
• API 调用的 token 使用量
• 时间戳和延迟信息

日志文件位置

~/.hermes/logs/
├── hermes.log              # 主日志
├── gateway.log             # 网关日志
├── mcp-<server>.log        # MCP 服务器日志
└── trajectory-<id>.json    # 对话轨迹

常用调试场景

工具调用不生效

1. 检查工具是否被注册：

   HERMES_DEBUG=1 hermes chat -q "list tools"

2. 检查工具的 check_fn 是否返回 True（可能缺少 API key 或依赖）

3. 查看日志中的 Tool not found 或 Tool unavailable 信息

上下文压缩问题

1. 开启 debug 日志查看压缩决策过程
2. 检查 context.engine 配置是否正确
3. 查看压缩前后的 token 数量对比

多平台消息问题

1. 检查平台适配器的连接状态：/status
2. 查看网关日志中的消息路由信息
3. 验证 SessionKey 的构建是否正确

模型调用失败

1. 确认 API key 已设置：hermes doctor
2. 查看 error_classifier 的分类结果
3. 检查是否触发了 rate limit

性能分析

Token 使用分析

使用 /usage 命令查看当前会话的 token 使用情况：

/usage

上下文大小检查

使用 /compress 手动触发压缩，观察压缩效果：

/compress

使用 insights 分析

/insights --days 7

查看过去 7 天的 API 调用量、token 消耗、模型使用分布等。