clawhive-hermes-plugin 0.1.2

ClawHive platform adapter plugin for Hermes Agent

ClawHive Hermes Plugin

This plugin lets a Hermes runtime register as a ClawHive runtime node, sync Hermes profiles into ClawHive, receive ClawHive user messages through the Hermes platform adapter connection, and write Hermes replies back through the ClawHive message API. It is shaped for the Hermes directory plugin loader: plugin.yaml plus a root __init__.py that exposes register(ctx).

Install Locally

Copy this directory into a Hermes plugin path:

mkdir -p ~/.hermes/plugins/clawhive
cp -R hermes-plugin/* ~/.hermes/plugins/clawhive/

Install From a Local Wheel

The plugin is packaged as a Python distribution because Hermes plugins are Python modules. Build and install it locally before publishing to PyPI:

cd hermes-plugin
python -m build
python -m pip install dist/clawhive_hermes_plugin-0.1.2-py3-none-any.whl

Hermes can discover the package when the wheel is installed into the same Python environment that runs Hermes, through the hermes_agent.plugins entry point:

python - <<'PY'
import importlib.metadata as md
print(md.entry_points().select(group="hermes_agent.plugins")["clawhive"])
PY

For end-user installs where the package may be installed outside the Hermes virtual environment, use the packaged installer to create a normal Hermes directory plugin:

clawhive-hermes install
hermes plugins enable clawhive

Re-run with --force to replace an existing ~/.hermes/plugins/clawhive directory.

Authorize Locally

Enable the plugin in Hermes, then run the ClawHive authorization command:

hermes clawhive authorize

This starts the same ClawHive device-code authorization flow used by the OpenClaw plugin: Hermes prints a QR code and fallback code, the user scans it in the already signed-in ClawHive app and explicitly approves the displayed node, and the command stores the returned plugin token in the Hermes .env file. The approval also pairs the scanning phone to this node. Restart the Hermes gateway after authorization so the platform adapter can call plugin-register and sync agents.

Status can be checked with:

hermes clawhive status

To move Hermes to another ClawHive account, first preview and then confirm the unlink:

hermes clawhive unlink
hermes clawhive unlink --yes

Hermes and OpenClaw share the phone's single ClawHive device record. If OpenClaw remains linked, Hermes can be authorized again only with the same account. Unlink every runtime that still uses the phone before authorizing Hermes with a different account. When Hermes is the last linked runtime, unlink releases the phone for either the original or a different account. The command preserves project URL, anon key, node name, plugin version, and unrelated Hermes settings while removing the revoked runtime identity.

Required Runtime Environment

Managed-cloud installs use the built-in ClawHive Supabase URL and anon key. For local or self-hosted Supabase, override them before authorization:

export CLAWHIVE_SUPABASE_MODE="local"
export CLAWHIVE_PROJECT_URL="https://<project>.supabase.co"
export CLAWHIVE_SUPABASE_ANON_KEY="<anon key>"

Normally hermes clawhive authorize writes the resolved project URL, anon key, and plugin token to $HERMES_HOME/.env; set them manually only for local testing or automation.

Optional values:

export CLAWHIVE_NODE_NAME="Hermes Desktop"
export CLAWHIVE_PLUGIN_VERSION="0.1.2"
export CLAWHIVE_USER_ID="<user uuid>"
export CLAWHIVE_PLUGIN_NODE_ID="<existing node uuid>"

Agent Registration

ClawHive follows the Hermes platform plugin flow. Hermes loads plugin.yaml, calls register(ctx), and creates ClawHivePlatformAdapter through ctx.register_platform(...). When the adapter connects, it registers the Hermes runtime node with ClawHive and syncs serviceable Hermes profiles as ClawHive agents.

Hermes profiles are discovered through Hermes profile APIs. With gateway profile multiplexing enabled, the adapter syncs all serviceable profiles. Without multiplexing, it syncs the active/default profile only.

Message Routing

ClawHivePlatformAdapter.send(chat_id, text) writes an agent message with:

chat_id = <session_id>:<agent_id>

If Hermes supplies session metadata separately, pass session_id and agent_id as keyword arguments instead of encoding them into chat_id.

Inbound messages are received by the platform adapter's connect() flow through the ClawHive Realtime bridge. The adapter converts user messages into Hermes MessageEvent values and dispatches them through self.handle_message(event).

poll_session(session_id) is a local debug/fallback helper. It is not the product message receive path.

Local Verification

From the repository root:

python3 -m pytest hermes-plugin/tests