hermes-config-change-checklist
Use when modifying, reviewing, or troubleshooting Hermes Agent configuration, providers, models, auxiliary routing, MCP servers, tools, skills, gateway/platform settings, cron jobs, secrets, or profiles. Standardizes pre-change discovery, safe edits, post-change verification, and restart guidance so a config change is provable rather than assumed. Use when a settings edit must be verified before it is called done.
Hermes Config Change Checklist
Overview (EN). Turn any Hermes Agent configuration edit into a provable loop: discover current state, make the narrowest safe change, verify with real commands, report in a fixed four-section format, and state plainly whether the operator must restart the gateway. Built for the failure mode where a config file looks right but the subsystem was never exercised. Applies to providers, models, auxiliary routing, MCP servers, tools, skills, gateway/platform settings, cron, and profiles. The rest of this document is in Chinese.
Overview
Use this skill for any Hermes Agent configuration change or health check. It turns ad-hoc edits into a repeatable loop:
- discover current state,
- make the narrowest safe change,
- verify the result with real commands,
- report what changed in a fixed format,
- clearly state whether the operator must restart the gateway.
Important standing rule: do not execute system-level gateway lifecycle or shutdown commands yourself. Hand the exact command to the operator and say plainly that you did not run it. The gateway is usually the process serving your own conversation, so a lifecycle command issued from inside it kills the session mid-turn — and often leaves the change applied but unverified.
When to Use
Use this skill when the user asks to:
- Add, remove, or change Hermes providers, models, model aliases, fallback models, delegation, or auxiliary routing.
- Edit
~/.hermes/config.yaml,~/.hermes/gateway-config.yaml, the official Hermes env file (hermes config env-path), compatibility.secretsshims, profiles, tools, or skills. - Configure or verify MCP servers.
- Configure Telegram/Weixin/gateway/platform behavior.
- Add or modify cron jobs, blueprints, webhooks, or plugins.
- Check whether a Hermes setting from OpenClaw/migration still needs work.
- Troubleshoot a Hermes feature not taking effect.
Do not use this skill for ordinary non-Hermes app configuration unless Hermes itself is involved.
Safety Rules
- No gateway lifecycle by the agent. Never run gateway lifecycle, shutdown, reboot, or service-control commands. State the command and that the operator must run it.
- No secret disclosure. Do not print full API keys, OAuth tokens, passwords, cookies, or refresh tokens. Show only presence, source, length, or redacted prefix when necessary.
- Prefer CLI setters. Use
hermes config set KEY VALUE,hermes mcp add/test,hermes auth, andhermes toolswhere possible instead of raw YAML edits. - Use profile-safe paths. Default active profile uses
~/.hermes/; do not edit another profile under~/.hermes/profiles/<name>/unless explicitly asked. - Back up risky rewrites. For broad YAML rewrites, create or rely on
/snapshot/config snapshot where appropriate before editing. - Report blockers honestly. If a provider API or tool fails, do not invent success; capture the actual error and use an alternative if available.
Standard Workflow
1. Scope the change
Identify exactly what will be affected:
| Target | Common files/commands |
|---|---|
| Main config | ~/.hermes/config.yaml, hermes config ... |
| Gateway/platforms | ~/.hermes/gateway-config.yaml, hermes gateway status |
| Providers/auth | hermes auth list, hermes status --all, env vars |
| MCP | hermes mcp list, hermes mcp test NAME |
| Tools/skills | hermes tools list, hermes skills list |
| Cron | hermes cron list, cronjob tool |
Completion criterion: every requested setting is mapped to a file, CLI command, or Hermes subsystem.
2. Discover current state first
Use read-only checks before editing. Typical commands:
hermes config path
hermes config check
hermes status --all
hermes auth list
For targeted checks:
hermes mcp list
hermes mcp test <name>
hermes tools list
hermes cron list
For YAML inspection, read the relevant file section without exposing secrets.
Completion criterion: you can state the current value/source and whether the requested change is additive, replacement, or cleanup.
3. Validate external prerequisites
Before writing config that depends on an API/provider, make a minimal live probe when possible:
- Provider key present and syntactically plausible.
/models,/key, or provider equivalent works.- One tiny chat/completions call works for the chosen model if safe.
- MCP server starts and exposes tools via
hermes mcp test. - Scripts referenced by config exist and are executable/readable.
Completion criterion: a real tool output confirms the dependency works, or the final report states the exact blocker.
4. Apply the narrowest change
Prefer command-based edits:
hermes config set section.key value
hermes mcp add <name> --command <cmd>
hermes mcp test <name>
Use patch / write_file only when CLI setters cannot express the change. Never use sed/awk for config edits.
Completion criterion: the command reports success or the file diff shows exactly the intended change.
5. Verify immediately
Run the smallest checks that prove the change is valid:
hermes config check
hermes status --all
Then run subsystem-specific checks:
| Change type | Verification |
|---|---|
| Provider/model | tiny model call or hermes chat -q where appropriate |
| Auxiliary model | import/use agent.auxiliary_client.call_llm or equivalent tiny call |
| MCP | hermes mcp test NAME |
| Gateway config | hermes gateway status and config syntax checks; do not restart |
| Cron | hermes cron list or cronjob(action='list') |
| Skill | skill_view, frontmatter validation, linked script syntax check |
Completion criterion: at least one post-change command verifies the changed subsystem, not just that the file exists.
6. State restart/apply boundary
State whether the change is live now or requires a fresh session/gateway restart:
| Change | Usually needs |
|---|---|
Current chat model via /model | immediate/session-specific |
config.yaml model/provider/auxiliary | new session or gateway restart |
| Tools enabled/disabled | /reset / new session |
| Skills added/removed | new session or /reload-skills when available |
| MCP config | /reload-mcp or gateway restart depending surface |
| Gateway platform config | operator-run /restart or the CLI lifecycle command |
| Env/secrets | reload/new process; often gateway restart |
Completion criterion: the final answer includes the exact user-run command if needed, while clearly saying the agent did not run it.
Required Final Report Format
Use this structure after real changes. The four headings force the distinction between "I edited a file" and "the subsystem actually works":
## 已完成
<one-sentence result>
## 改了什么
- <file/setting/command changed>
- <old → new when useful>
## 验证结果
- `<command>` → <success/failure summary>
- <provider/model/MCP health if relevant>
## 现在状态
- <live or pending restart>
- <what the operator should run, if any>
For checks that did not change anything, use:
## 检查完成
## 发现
## 建议操作
Quick Recipes
Provider/API key change
- Check provider appears in
hermes auth listor env. - Probe key/model without printing secrets.
- Write provider/model config.
- Verify with a tiny model call.
- State whether a gateway restart or new session is needed.
Auxiliary model change
- Inspect
auxiliarysection. - Test candidate models with
agent.auxiliary_client.call_llmwhen possible. - Keep critical tasks (
compression,background_review,curator) on stable models, not flaky free routers, unless the operator explicitly accepts that risk. - Write only the selected task slots.
- Run
hermes config checkand report.
MCP server change
- Confirm command/script path exists and env vars are present.
- Add/update MCP config.
- Run
hermes mcp test NAME. - Report tool count and errors.
- State whether
/reload-mcpor a restart is needed.
Single skill change
- Load
hermes-agent-skill-authoringfor standards and pitfalls. - Create/edit with Hermes skill frontmatter standards.
- Add scripts under
scripts/, references underreferences/. - Validate frontmatter and syntax-check scripts.
- Use
skill_viewto confirm it loads.
Batch skill library maintenance
For bulk operations — auditing, migrating from another ecosystem, standardizing frontmatter, fixing secrets, or batch-verifying 10+ skills — see the dedicated reference: references/skill-library-maintenance.md.
Key phases covered there:
- Audit & categorize — count, classify (keep/merge/delete), identify duplicates
- Delete obsolete —
skill_managewithabsorbed_into - Standardize — frontmatter, path migration,
related_skills, secrets - Fix secrets hygiene — never use placeholder strings as run-time defaults; shell pattern with empty-string fallback and empty-string check
- Verify — bulk frontmatter validation, stale reference scan, script syntax checks,
hermes skills listsmoke test
Common Pitfalls
- Skipping discovery. Editing config without reading the current setting can overwrite working provider/profile choices.
- Trusting key presence as key validity. A set env var can be a placeholder. Always make a minimal provider call when the task depends on validity.
- Restarting for the user. Do not run lifecycle commands. Report that the operator must do it.
- Leaking secrets in logs. Avoid
env, fullauth.json, or raw config dumps containing tokens. - Declaring success after a file write only. Success requires at least syntax/config validation and, where relevant, a live subsystem probe.
- Editing another profile accidentally. Check active profile and path before writing profile-scoped files.
- Using free model routers for critical compression. Free routers can return empty content, 429, or ignore instructions; keep critical summarization on stable models.
- Letting
model.api_keyshadow a custom provider credential. A direct main-model key is selected asmodel_configbefore a custom provider'skey_env; compare masked fingerprints and probe the exact regional endpoint with each credential before changing models. A key accepted by one regional endpoint can be rejected by another.
Verification Checklist
- Relevant Hermes skill/docs consulted when needed.
- Active profile and target files identified.
- Current state inspected before edit.
- Secrets were not printed or persisted in unsafe places.
- External dependencies were live-tested when possible.
- Config change used
hermes config setor a targeted patch/write. -
hermes config checkor subsystem equivalent ran after change. - Provider/MCP/skill/cron-specific verification ran when relevant.
- Final report used the four sections: 已完成 / 改了什么 / 验证结果 / 现在状态 (done / changed / verified / current state).
- Restart/apply boundary clearly stated; no forbidden restart executed.
License and provenance
原创流程文档,无第三方代码,无个人环境信息。文中 ~/.hermes/ 为 Hermes 默认
路径,<name> 等为占位符。以 MIT-0 发布。
Related skills
- Downloads
- 230All time
- Security audit
- Pass
- Last updated
- 3w ago
- Current version
- v0.1.3
- License
- MIT-0
