| name | hermes-ops |
| description | Use when operating Hermes Agent itself: checking the version, updating from upstream, running doctor/doctor --fix, installing the browser stack, setting tokens, managing the gateway service, and telling apart real fixables from by-design 'optional integration not configured' doctor noise. |
| version | 1.0.0 |
| author | Hermes Agent |
| license | MIT |
| platforms | ["linux","macos","windows"] |
| metadata | {"hermes":{"tags":["hermes","agent","update","doctor","service-management","troubleshooting"],"related_skills":["openclaw-ops"]}} |
Hermes Ops
Overview
Hermes Agent is a Python AI assistant (checkout at ~/.hermes/hermes-agent, launched via
~/.local/bin/hermes) with a long-running messaging gateway. The recurring operator tasks
are: check the version, update from upstream git, run doctor, fix the handful of real
warnings, and — importantly — recognise which warnings are by-design informational noise
so you don't chase them forever.
This skill is for operating Hermes itself, not for using Hermes to complete another task.
For the sibling agent, see openclaw-ops.
When to Use
- Check whether Hermes is behind upstream and update it safely
- Run
hermes doctor and fix config/dependency warnings
- Install or repair the browser automation stack (agent-browser + Chromium)
- Set tokens/keys (e.g.
GITHUB_TOKEN) or understand "not configured" warnings
- Back up / restore the Hermes home, or inspect the gateway service
Do not use this skill for: OpenClaw operations (use openclaw-ops), or generic Python/npm
troubleshooting unrelated to Hermes.
Quick Checks
hermes --version
hermes status
hermes doctor
Update Workflow
hermes update --check
hermes update
hermes update --yes
Useful flags: --no-backup / --backup (a pre-update backup runs by default), --branch NAME.
What a real update does (observed jumping v0.16.0 → v0.17.0, ~387 commits, cleanly):
git pull + dependency reinstall, rebuilds the web UI,- syncs bundled skills (user-modified ones are kept;
hermes skills list-modified to inspect),
- migrates the config format (e.g. v29 → v30) — this also clears the
"Config version outdated" doctor warning,
- drains and restarts the
hermes-gateway service.
Verify afterwards: hermes --version should read "Up to date", then hermes doctor.
doctor & doctor --fix
hermes doctor
hermes doctor --fix
hermes doctor --ack <ID>
Doctor Warning Taxonomy — what to fix vs what to ignore
The single most important thing about hermes doctor: most ⚠ are advisories for optional
integrations you simply haven't configured, not failures. Do not try to drive them to zero
on a box that doesn't use those integrations.
By-design / informational (leave them unless you actually use the integration):
- Auth Providers "not logged in" — Nous Portal, Google Gemini OAuth, MiniMax OAuth, xAI OAuth.
Hardcoded per-provider checks; the only way to clear one is to actually log in. Not gated by
whether you use it.
- Tool Availability "missing " / "system dependency not met" — e.g.
discord,
x_search, moa, spotify, homeassistant, computer_use, video_gen, browser-cdp,
hermes-yuanbao. The doctor checks the deps of every registered toolset regardless of
enable/disable. Verified: hermes tools disable <tool> does NOT silence these — it
only changes what the model is offered, not the dependency check. Only configuring the
integration clears the row.
docker not found, OpenRouter API (not configured) — optional.
Actually fixable:
- Config version outdated →
hermes update (migrates during update) or hermes config migrate.
- agent-browser not installed → see "Browser stack" below.
- npm workspace vulnerability (e.g.
ui-tui ... high) → clears via the lockfile bump that
hermes update performs (it's build-time tooling, not runtime).
- No
GITHUB_TOKEN (skills hub 60 req/hr limit) → add GITHUB_TOKEN=... to ~/.hermes/.env.
Browser stack (agent-browser + Chromium)
The browser tool can show ✓ while the doctor still warns "agent-browser not installed
(run: npm install)" — the tool is registered but its Node backend isn't present, so it
silently fails at runtime. The doctor looks for ~/.hermes/hermes-agent/node_modules/agent-browser.
cd ~/.hermes/hermes-agent
npm install
./node_modules/.bin/agent-browser install
Verify: hermes doctor should show "agent-browser (Node.js) ✓" and "Playwright Chromium ✓".
Tokens & config
hermes config path
hermes config env-path
Put provider keys / GITHUB_TOKEN in ~/.hermes/.env (mode 600). After rotating a leaked
token, replace the line directly in .env rather than echoing the new value where it could be
logged.
Backup / Restore
hermes backup
hermes import <backup.zip>
hermes update also takes a pre-update backup by default. Take one before any risky change.
Gateway service
Hermes runs a hermes-gateway systemd user service. doctor confirms systemd linger is
enabled (so it survives logout). hermes update drains and restarts it automatically; use
hermes status to see live component state.
Common Pitfalls
- Chasing optional-integration warnings to zero. They are advisories;
hermes tools disable does not silence them. Configure the integration or accept the ⚠.
- Assuming
browser works because doctor shows the tool ✓. Check for the
"agent-browser not installed" / "Playwright Chromium" rows — install the backend.
- Running
hermes update headless without --yes. It will block on interactive prompts.
- Forgetting that config migration happens inside
hermes update. If you see a
"config outdated" warning, an update usually fixes it without a separate step.
Verification Checklist
