hermes doctor

hermes doctor is Hermes Agent’s built-in automatic diagnostic tool that quickly checks if your installation environment, configuration, and network connections are working properly. When you encounter issues, this should be the first command you run.

Basic Usage

# Run full diagnosis
hermes doctor

# Check only specific modules
hermes doctor --check llm        # Only check LLM connection
hermes doctor --check gateway    # Only check gateway configuration
hermes doctor --check system     # Only check system environment

Interpreting Results

hermes doctor checks your environment item by item and displays results:

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

✅ Python version: 3.11.5 (meets requirement)
✅ Hermes Agent version: v0.13.0
✅ Config file exists: ~/.hermes/config.yaml
✅ LLM connection normal: openrouter/anthropic/claude-sonnet-4-20250514
✅ Memory system normal: ~/.hermes/memory/
✅ Skills directory normal: ~/.hermes/skills/
✅ Gateway config: Not configured (run hermes gateway if using messaging platforms)
✅ Disk space sufficient: 45GB available

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Diagnosis complete: 7/7 checks passed ✅

If a check fails, you’ll see ❌ and specific error description:

❌ Python version: 3.9.7 (requires 3.10+)
   Suggestion: Upgrade Python to 3.10 or higher

❌ LLM connection failed: Authentication failed
   Suggestion: Run hermes model to reconfigure API Key

Check Items Explained

System Environment Check

Check Item	Description
Python version	Confirm Python ≥ 3.10
Hermes version	Confirm installed and version correct
Disk space	Confirm sufficient space for memory and logs
System dependencies	Check if git, curl and other necessary tools are available
File permissions	Check read/write permissions for ~/.hermes/ directory

Configuration Check

Check Item	Description
Config file exists	Whether ~/.hermes/config.yaml exists
Config format correct	Whether YAML syntax is valid
API Key set	Whether LLM API Key is configured
Model identifier valid	Whether configured model ID exists

LLM Connection Check

Check Item	Description
API connectivity	Whether provider’s API endpoint is accessible
Authentication success	Whether API Key is valid
Model available	Whether configured model can be called
Response speed	Test request latency

Memory System Check

Check Item	Description
Memory directory exists	Whether ~/.hermes/memory/ is available
Memory files readable	Whether existing memory files can be read normally
Memory files writable	Whether new memories can be written normally

Skills System Check

Check Item	Description
Skills directory exists	Whether ~/.hermes/skills/ is available
Bundled skills seeded	Whether built-in skills are correctly copied
Skills load normally	Whether skills can be discovered and loaded normally

Gateway Check (if configured)

Check Item	Description
Gateway config correct	Whether each platform’s configuration is complete
Bot Token valid	Whether Telegram/Discord etc. Tokens are usable
Network reachable	Whether messaging platform API can be connected

Advanced Options

# Output JSON format (suitable for script processing)
hermes doctor --format json

# Output verbose logs
hermes doctor --verbose

# Skip network check (offline environment)
hermes doctor --offline

# Only output failed items
hermes doctor --only-failures

# Specify check timeout
hermes doctor --timeout 30

JSON Output Example

{
  "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": "Gateway not configured"}
  },
  "summary": {"total": 7, "passed": 6, "failed": 0, "warnings": 1}
}

Common Diagnosis Results and Fixes

Python Version Not Satisfied

# Upgrade Python (Ubuntu)
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.11 python3.11-venv

# Upgrade Python (macOS)
brew install python@3.11

Configuration File Missing

# Auto-generate default config
hermes config init

# Or configure via wizard
hermes model

LLM Connection Failed

# Reconfigure LLM
hermes model

# Check proxy settings
echo $HTTPS_PROXY

# Try switching to domestic provider
hermes model    # Select DeepSeek / Kimi

Permission Issues

# Fix ~/.hermes directory permissions
sudo chown -R $(whoami):$(whoami) ~/.hermes
chmod -R 755 ~/.hermes

Skills Not Seeded

# Reseed built-in skills
hermes skills reseed

# Verify
hermes skills list

Using in CI/CD

# Auto-check in CI script
hermes doctor --format json --only-failures | python -c "
import sys, json
result = json.load(sys.stdin)
if result['summary']['failed'] > 0:
    print('❌ Diagnosis failed')
    sys.exit(1)
else:
    print('✅ All checks passed')
"

Recommended Diagnosis Flow

When encountering issues, follow this flow:

1. Run hermes doctor — Get overall status report
2. Focus on ❌ items — Fix according to suggestions
3. Focus on ⚠️ items — Not critical but recommended to address
4. Use --verbose for details — Get more error information
5. Check corresponding topic pages — Common Errors, Install Issues, Model Issues

Related Pages

• Common Errors — Common errors quick reference
• Install Issues — Installation troubleshooting
• Model Issues — LLM provider issues
• Gateway Issues — Messaging platform issues