hermes doctor 诊断

hermes doctor 是 Hermes Agent 内置的自动诊断工具，能够快速检测你的安装环境、配置、网络连接等是否正常。当你遇到问题时，这应该是你运行的第一个命令。

基本用法

# 运行完整诊断
hermes doctor

# 只检查特定模块
hermes doctor --check llm        # 只检查 LLM 连接
hermes doctor --check gateway    # 只检查网关配置
hermes doctor --check system     # 只检查系统环境

诊断结果解读

hermes doctor 会逐项检查你的环境并显示结果：

🔍 Hermes Agent Doctor
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Python 版本: 3.11.5 (满足要求)
✅ Hermes Agent 版本: v0.13.0
✅ 配置文件存在: ~/.hermes/config.yaml
✅ LLM 连接正常: openrouter/anthropic/claude-sonnet-4-20250514
✅ 记忆系统正常: ~/.hermes/memory/
✅ 技能目录正常: ~/.hermes/skills/
✅ 网关配置: 未配置 (如需使用消息平台，请运行 hermes gateway)
✅ 磁盘空间充足: 45GB 可用

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
诊断完成: 7/7 项通过 ✅

如果某项检测失败，你会看到 ❌ 和具体的错误描述：

❌ Python 版本: 3.9.7 (需要 3.10+)
   建议: 升级 Python 到 3.10 或更高版本

❌ LLM 连接失败: Authentication failed
   建议: 运行 hermes model 重新配置 API Key

检查项目详解

系统环境检查

检查项	说明
Python 版本	确认 Python ≥ 3.10
Hermes 版本	确认已安装且版本号正确
磁盘空间	确认有足够空间存储记忆和日志
系统依赖	检查 git、curl 等必要工具是否可用
文件权限	检查 `~/.hermes/` 目录的读写权限

配置检查

检查项	说明
配置文件存在	`~/.hermes/config.yaml` 是否存在
配置格式正确	YAML 语法是否有效
API Key 已设置	LLM API Key 是否已配置
模型标识符有效	配置的模型 ID 是否存在

LLM 连接检查

检查项	说明
API 连通性	能否访问提供商的 API 端点
认证成功	API Key 是否有效
模型可用	配置的模型是否可以调用
响应速度	测试请求的延迟

记忆系统检查

检查项	说明
记忆目录存在	`~/.hermes/memory/` 是否可用
记忆文件可读	已有的记忆文件是否可以正常读取
记忆文件可写	能否正常写入新的记忆

技能系统检查

检查项	说明
技能目录存在	`~/.hermes/skills/` 是否可用
捆绑技能已播种	内置技能是否已正确复制
技能加载正常	技能能否被正常发现和加载

网关检查（如已配置）

检查项	说明
网关配置正确	各平台配置是否完整
Bot Token 有效	Telegram/Discord 等 Token 是否可用
网络可达	能否连接到消息平台 API

高级选项

# 输出 JSON 格式（适合脚本处理）
hermes doctor --format json

# 输出详细日志
hermes doctor --verbose

# 跳过网络检查（离线环境）
hermes doctor --offline

# 只输出失败项
hermes doctor --only-failures

# 指定检查超时时间
hermes doctor --timeout 30

JSON 输出示例

{
  "version": "0.13.0",
  "timestamp": "2026-05-28T12:00:00Z",
  "checks": {
    "python_version": {"status": "pass", "value": "3.11.5"},
    "llm_connection": {"status": "pass", "provider": "openrouter"},
    "memory_system": {"status": "pass"},
    "skills_system": {"status": "pass"},
    "gateway_config": {"status": "warn", "message": "未配置网关"}
  },
  "summary": {"total": 7, "passed": 6, "failed": 0, "warnings": 1}
}

常见诊断结果与修复

Python 版本不满足

# 升级 Python（Ubuntu）
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.11 python3.11-venv

# 升级 Python（macOS）
brew install [email protected]

配置文件缺失

# 自动生成默认配置
hermes config init

# 或通过向导配置
hermes model

LLM 连接失败

# 重新配置 LLM
hermes model

# 检查代理设置
echo $HTTPS_PROXY

# 尝试切换到国内提供商
hermes model    # 选择 DeepSeek / Kimi

权限问题

# 修复 ~/.hermes 目录权限
sudo chown -R $(whoami):$(whoami) ~/.hermes
chmod -R 755 ~/.hermes

技能未播种

# 重新播种内置技能
hermes skills reseed

# 验证
hermes skills list

在 CI/CD 中使用

# 在 CI 脚本中自动检查
hermes doctor --format json --only-failures | python -c "
import sys, json
result = json.load(sys.stdin)
if result['summary']['failed'] > 0:
    print('❌ 诊断失败')
    sys.exit(1)
else:
    print('✅ 所有检查通过')
"

诊断流程建议

遇到问题时，按以下流程排查：

运行 hermes doctor — 获取整体状态报告
关注 ❌ 项 — 按照建议修复
关注 ⚠️ 项 — 非关键但建议处理
使用 --verbose 查看详情 — 获取更多错误信息
查阅对应专题页 — 常见错误、安装问题、模型问题

hermes doctor 诊断

基本用法

诊断结果解读

检查项目详解

系统环境检查

配置检查

LLM 连接检查

记忆系统检查

技能系统检查

网关检查（如已配置）

高级选项

JSON 输出示例

常见诊断结果与修复

Python 版本不满足

配置文件缺失

LLM 连接失败

权限问题

技能未播种

在 CI/CD 中使用

诊断流程建议

相关页面