Hermes Agent Plugins: Install, Enable, and Configure

Plugins, skills, and MCP are three different things

The three extension systems get conflated constantly, and choosing the wrong one is the usual reason an integration goes nowhere.

A plugin is the only one of the three that runs inside the agent process and can register a lifecycle hook. It is also the only one that can ship all three: a plugin may call ctx.register_skill() and read from an MCP server via ctx.call_mcp().

The four plugin types

Hermes discovers four categories, and they differ in how many can be active at once:

• General plugins — tools, hooks, slash commands, and CLI commands. Multi-select through plugins.enabled.
• Memory providers — single-select, chosen with memory.provider.
• Context engines — single-select, chosen with context.engine.
• Model providers — multi-register, adding new model backends.

Memory and context are single-select because only one can own the behaviour. Enabling a second memory provider does not layer them; it replaces the choice.

Where Hermes looks for plugins

Project plugins are gated behind an environment variable on purpose. Cloning a repository should not silently grant its .hermes/plugins/ directory the right to execute in your agent.

Install and enable

hermes plugins                       # interactive browser
hermes plugins list                  # table of discovered plugins
hermes plugins search <term>          # search the catalog
hermes plugins install <name>         # from the catalog
hermes plugins install user/repo      # from Git
hermes plugins install user/repo --enable
hermes plugins install user/repo --ref <40-char-SHA>   # pinned
hermes plugins enable <name>
hermes plugins disable <name>
hermes plugins capabilities [name]    # review what it was granted
hermes plugins update <name>
hermes plugins remove <name>

There are three distinct states, and the middle one surprises people: enabled (listed in plugins.enabled, loads automatically), disabled (listed in plugins.disabled, will not load even if something tries to enable it), and not enabled — discovered but never opted into, which is the default for every newly installed plugin. Installing is not enabling.

The config keys

Plugin state lives in ~/.hermes/config.yaml. Edit it with hermes config edit rather than by hand if the gateway is running.

plugins:
  enabled:
    - my-plugin
  disabled:
    - noisy-plugin
  scan_on_install: false      # optional; default true
  hook_callback_timeout: 30   # seconds
  entries:
    my-plugin:
      allow_gateway_injection: true
      mcp_allowlist: ["server1", "server2"]
      granted_capabilities: [...]

plugins.disabled wins over plugins.enabled. That precedence is useful operationally: to take a misbehaving plugin out of service without losing its configuration, add it to disabled rather than deleting it from enabled.

hook_callback_timeout matters more than it looks. A hook runs inside the agent turn, so a plugin that blocks on a slow network call delays every message until this timeout fires.

Capability grants are the security boundary

A plugin is code you chose to run in the same process as your agent and its credentials. Two entry keys are worth reading before enabling anything from a third party:

• allow_gateway_injection — lets the plugin call ctx.inject_message(), pushing content into a session as if it came from the user. That is a genuine prompt-injection surface, so grant it only to plugins you control.
• mcp_allowlist — restricts which MCP servers the plugin may reach through ctx.call_mcp(). An empty or absent allowlist is not a tightening.

Run hermes plugins capabilities <name> before enabling, and pin Git installs with --ref so a later upstream commit cannot change what executes. The same reasoning applies to OpenClaw security advisories: extension code is the part of an agent most likely to be attacker-supplied.

What a plugin can register

Inside register(ctx), the plugin context exposes the extension points. The commonly used ones:

ctx.register_tool(name=..., toolset=..., schema=..., handler=...)
ctx.register_hook("post_tool_call", callback)
ctx.register_command(name, handler, description)
ctx.register_cli_command(name, help, setup_fn, handler_fn)
ctx.register_skill(name, path)
ctx.register_platform(name, label, adapter_factory, check_fn, ...)
ctx.register_context_engine(engine)
ctx.call_mcp(server, tool, arguments, timeout=30)
ctx.inject_message(content, role="user", session_key=...)

register_platform is the one worth knowing about: a plugin can add an entire messaging surface, which is how Hermes reaches platforms that are not bundled.

The OpenClaw plugin system, for comparison

Both frameworks have plugins, but they share no code and no format. If you run both, keep them straight:

One OpenClaw detail catches people out: if your plugins section is backed by a single-file $include, the install, update, enable, disable, and uninstall commands write through to the included file that owns the change and leave openclaw.json untouched. Looking only at openclaw.json will then show no change at all.

A note on pre-installing plugins

If you are building images or templates, resist pre-installing npm-backed channel plugins into a base image. We run this fleet, and the failure mode is consistent: intermittent install failures and stale staging directories produce agents that look provisioned and are not. On-demand installation at connect time costs a little latency and is far more reliable.

OpenClaw Launch manages the Hermes Agent runtime itself. Plugins you install remain yours to review, pin, and update.

Hermes Agent plugins FAQ

Related guides

• Hermes Agent Skills
• Hermes Agent + MCP
• Hermes Agent Memory
• Hermes Agent vs OpenClaw