需进入底层调试环节，方法包括：一、启用DEBUG日志与HERMES_DEBUG=true；二、用pdb/ipdb在技能函数首行设断点；三、注入logging.info快照+psutil监控内存；四、VS Code远程调试配置launch.json；五、mitmproxy拦截LLM/工具API通信。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在开发或定制Hermes Agent时遇到代码执行异常、技能未触发、工具调用失败或日志无输出等问题，说明需要进入底层调试环节。以下是针对Hermes Agent的多种代码级调试方法，覆盖本地CLI、Python运行时、日志追踪与交互式诊断场景。
一、启用详细日志与结构化调试输出
该方法通过提升日志级别捕获完整执行链路，适用于定位技能加载失败、工具注册异常、模型响应中断等流程性问题。Hermes Agent默认使用structlog和rich进行日志渲染，支持动态调整输出粒度。
1、在项目根目录下确认存在.env文件，若不存在则运行./setup-hermes.sh或hermes init生成基础配置。
2、编辑.env文件，添加或修改以下两行：
LOG_LEVEL=DEBUG
HERMES_DEBUG=true
3、重启Agent进程：执行hermes --debug（CLI模式）或hermes run --debug（后台服务模式）。
4、观察终端输出中以[DEBUG]标记的模块初始化、skill_load、tool_call、memory_access等事件流，重点关注Failed to load skill、Tool not found、LLM response empty类报错。
二、在Python环境中启动交互式调试器（pdb/ipdb）
该方法适用于需逐行跟踪Python函数逻辑、检查变量状态、验证技能函数签名或调试自定义工具实现的场景。Hermes Agent核心由Python 3.11驱动，所有技能模块均以标准Python函数形式注册，可直接接入调试器。
1、定位目标Python文件，例如自定义技能位于skills/my_analysis.py，其主函数为run(query: str) -> str。
2、在函数体第一行插入断点语句：import pdb; pdb.set_trace()（或安装ipdb后使用import ipdb; ipdb.set_trace()）。
3、确保当前shell处于Hermes虚拟环境内：source venv/bin/activate（Linux/macOS）或venv\Scripts\activate.ps1（Windows PowerShell）。
4、触发该技能：在CLI中输入明确匹配该skill的指令，例如分析这份日志文件的内容，或通过hermes skill run my_analysis --query "test"直调。
5、终端将暂停并进入(Pdb)交互界面，可使用n（单步）、s（步入）、p variable_name（打印变量）、c（继续）等命令进行深度追踪。
三、注入实时日志钩子并捕获内存快照
该方法用于诊断异步任务卡死、PTY会话无响应、Honcho记忆加载延迟等难以复现的运行时问题。通过在关键路径插入logging.info(f"[SNAPSHOT] {locals()}")并配合psutil获取进程资源状态，可快速锁定内存泄漏或阻塞点。
1、在venv中安装调试依赖：pip install psutil。
2、打开hermes/agent/core.py，找到execute_skill函数，在入口处添加：
import logging, psutil; logging.info(f"[SNAPSHOT] PID={psutil.Process().pid}, MEM=%.2fMB", psutil.Process().memory_info().rss / 1024 / 1024)
3、在同文件中搜索self.memory.load_context调用位置，在其前后各插入一行日志，记录耗时与返回长度：
logging.debug("[MEMORY LOAD START]")
ctx = self.memory.load_context(...); logging.debug(f"[MEMORY LOAD DONE] len={len(ctx) if ctx else 0}")
4、保存文件后，清除缓存并重启：rm -rf .hermes_cache/ && hermes --debug。
5、重现问题时，检查日志中是否出现长时间无[MEMORY LOAD DONE]输出、或MEM值持续攀升超过500MB，即可确认为内存或I/O阻塞。
四、使用VS Code远程调试Hermes Agent进程
该方法提供图形化断点管理、变量监视、调用栈可视化能力，适合复杂技能链调试及多模块协同问题分析。Hermes Agent支持标准Python调试协议，无需额外插件即可对接VS Code的Debug Python File配置。
1、在VS Code中打开Hermes Agent项目根目录，确保已安装Python扩展。
2、创建.vscode/launch.json，填入以下配置：
{ "version": "0.2.0", "configurations": [ { "name": "Debug Hermes CLI", "type": "python", "request": "launch", "module": "hermes.cli", "console": "integratedTerminal", "justMyCode": false } ] }
3、在目标Python文件（如skills/web_search.py）中设置断点，点击左侧行号边栏。
4、按Ctrl+Shift+D切换到调试视图，选择Debug Hermes CLI，点击绿色三角形启动。
5、当CLI启动并等待输入时，在终端中键入触发对应技能的指令，执行流将自动停在断点处，可查看局部变量、调用堆栈、表达式求值。
五、注入HTTP调试代理捕获LLM与工具API通信
该方法专用于排查大模型响应超时、工具API返回格式错误、网关转发失败等外部依赖问题。通过在uvicorn或httpx层拦截HTTP请求/响应原始字节，可比日志更早发现序列化异常或认证头缺失。
1、安装mitmproxy：pip install mitmproxy。
2、启动代理监听：mitmproxy --mode reverse:http://localhost:8000 --port 8080（假设Hermes内置LLM网关运行于8000端口）。
3、修改.env中LLM相关配置，将OPENAI_BASE_URL或ANTHROPIC_BASE_URL改为http://localhost:8080。
4、启动Hermes：hermes --debug，并在mitmproxy界面中观察每条请求的Request Headers、Response Body与HTTP Status。
5、若发现401 Unauthorized，检查OPENAI_API_KEY是否被截断；若Response Body为空但状态为200，说明下游服务返回了空JSON，需检查模型供应商接口变更。
