---
name: openclaw-hermes-cohabitation
description: Architecture pattern for OpenClaw and Hermes running together — called "The Robing." OpenClaw is the Robe (messaging, dispatch, Telegram). Hermes is the Body (memory, tools, soul). A Robed wizard has both. An Unrobed wizard has Hermes only. A Lobster has OpenClaw only — reachable but empty, no memory, the failure state. Use when an agent needs both dispatch capabilities and durable memory/tools. A KT document exists on Timmy's Mac at ~/.timmy/docs/THE-ROBING-KT.md — point agents there before they try to figure it out from scratch.
triggers:
  - "openclaw hermes together"
  - "put on hermes"
  - "synergize openclaw"
  - "cohabitation"
tags: [openclaw, hermes, architecture, telegram, cohabitation]
related_skills: [hermes-telegram-cutover, wizard-house-birth]
version: 1
---

# OpenClaw + Hermes Cohabitation

## Context
OpenClaw is good at: multi-channel messaging (Telegram, Discord), subagent dispatch, gateway plumbing.
Hermes is good at: memory (11K+ sessions), session search, tools, SOUL.md, skills, cron.

Running both lets OpenClaw handle the messaging shell while Hermes handles thinking. The Bezalel pattern — proven on Ezra's house.

## Architecture

```
User (Telegram/Discord)
  |
  v
OpenClaw Gateway (messaging plumbing, dispatch)
  |
  v (routes to Hermes API)
Hermes API Server (localhost:8642)
  |
  v
Full Hermes Agent (memory, tools, SOUL.md, sessions)
  |
  v (calls inference)
LLM Backend (Claude, Kimi, local llama.cpp)
```

## Nomenclature (The Robing — established 2026-03-31)

| State | Robe (OpenClaw) | Body (Hermes) | Result |
|-------|-----------------|---------------|--------|
| **Robed** | Running | Running | Full wizard. Reachable and real. |
| **Unrobed** | — | Running | Real but not reachable via channels. CLI/API only. |
| **Lobster** | Running | — | Reachable but empty. No memory, no tools, no soul. THE FAILURE STATE. |
| **Dead** | — | — | Nothing running. |

"The Robing" = the act of configuring both layers. "Disrobing" = intentionally removing OpenClaw.
The lobster is always a bug, never a feature. If Telegram messages get clarification loops, sub-agent spawns for single API calls, or 5-minute delays on simple tasks — check if Hermes is actually running underneath.

## The Three Modes

### Mode 1: Hermes Owns Telegram (simplest, current Timmy setup)
- OpenClaw Telegram disabled
- Hermes gateway polls Telegram directly
- Full Hermes experience on every message
- **Use when:** You want the richest agent experience on Telegram

### Mode 2: OpenClaw Shell, Hermes Brain (Bezalel pattern)
- OpenClaw handles Telegram polling and message routing
- OpenClaw calls Hermes API at localhost:8642/v1/chat/completions for thinking
- Hermes has all memory/tools but OpenClaw controls the messaging UX
- **Use when:** You need OpenClaw's dispatch/subagent capabilities with Hermes's brain

### Mode 3: Separate Channels (split deployment)
- OpenClaw owns Telegram with one bot token
- Hermes owns Discord or a separate Telegram bot
- Each handles its own channel independently
- **Use when:** You want different personalities per channel

## Bezalel Pattern Implementation (Mode 2)

### Files on disk (from Ezra's working setup):
```
~/.openclaw/workspace/
  AGENTS.md       # Startup instructions: read SOUL, read IDENTITY, preserve sovereignty
  IDENTITY.md     # Name, emoji, theme, role
  SOUL.md         # The agent's charter — emphasizes "OpenClaw does not replace Hermes underneath"
```

### Key principle from Ezra's SOUL.md:
> OpenClaw may be used for gateway shell, session bus, and operator convenience.
> Hermes remains the memory-bearing harness and durable workbench.

### How OpenClaw calls Hermes:
OpenClaw has terminal tools. It can curl the Hermes API:
```bash
curl -s -X POST http://localhost:8642/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"hermes-agent","messages":[{"role":"user","content":"TASK HERE"}]}'
```
The model name is `hermes-agent` (from /v1/models endpoint).

### Hermes API endpoints (api_server.py):
| Endpoint | Method | Purpose |
|----------|--------|---------|
| /health | GET | Health check |
| /v1/health | GET | Health check (alt) |
| /v1/models | GET | List available models |
| /v1/chat/completions | POST | Full agent session (OpenAI-compatible) |
| /v1/responses | POST | Responses API |
| /api/jobs | GET/POST | Cron job management |

## Robing Procedure (Restoring OpenClaw Shell over Hermes Brain)

When switching from "Hermes owns Telegram" to "OpenClaw shell + Hermes brain":

1. Remove telegram from Hermes config: delete `platforms.telegram` from `~/.hermes/config.yaml`
2. Re-enable telegram in OpenClaw: set `channels.telegram.enabled: true` in `~/.openclaw/openclaw.json`
3. Kill Hermes gateway (Ctrl-C or via tmux send-keys C-c)
4. Restart Hermes gateway WITHOUT telegram: `hermes gateway run &`
5. Stop then reinstall OpenClaw gateway: `openclaw gateway stop && openclaw gateway install`
6. Verify both running: `ps aux | grep -E 'openclaw-gateway|hermes.*gateway'`
7. Verify OpenClaw has Telegram: check `~/.openclaw/logs/gateway.log` for `[telegram] starting provider`

Order matters: Hermes must release the bot token BEFORE OpenClaw tries to grab it.

## The Bezalel Skill Reference

Timmy's Mac has a comprehensive skill at `~/.hermes/skills/devops/openclaw-backend-delegation/SKILL.md` written by Bezalel. It covers:
- Full heartbeat dispatch architecture (launchd, NOT Hermes crons)
- Label lifecycle (assigned-kimi → kimi-in-progress → kimi-done)
- Two-phase dispatch with planning/decomposition for complex tasks
- Bot token creation, profile setup, repo collaborator permissions
- OpenClaw model IDs vs Hermes model IDs mapping
- Sovereignty checklist for heartbeat scripts
- Proven batch dispatch patterns

This is the authoritative reference for OpenClaw + Hermes cooperation on Timmy's Mac.

## Pitfalls

1. **Bot token conflict:** Two processes cannot poll the same Telegram bot token. If both OpenClaw and Hermes try to poll Telegram, one gets 409 Conflict. Either give Telegram to one or use separate bot tokens.

2. **OpenClaw LaunchAgent lifecycle:** `openclaw gateway restart` restarts the LaunchAgent. `openclaw gateway stop` stops it. If the LaunchAgent gets unloaded, use `openclaw gateway install` to re-register it. Don't use `pkill` unless the LaunchAgent commands fail.

3. **PyYAML not in system python:** On Mac, system python lacks yaml module. Use `~/.hermes/hermes-agent/venv/bin/python3` for any yaml operations.

4. **Hermes gateway flag:** `hermes gateway run` is correct. `hermes gateway --replace` is NOT a valid flag.

5. **OpenClaw config is JSON, Hermes is YAML.** Don't mix formats. Edit each with appropriate tools.

6. **The `hermes claw migrate` command** can sync settings from OpenClaw to Hermes (memories, env vars, provider keys). Run with `--dry-run` first.

7. **tmux is the only reliable way to start Mac processes remotely.** SSH sessions lack the right shell environment for OpenClaw. Use `tmux send-keys` to dispatch commands to existing tmux windows.

8. **execute_code tool may be broken after security patches.** Allegro's interrupt race condition fix (PR #60) changed `_interrupt_event` in terminal_tool.py. If code_execution_tool.py can't import it, the execute_code tool breaks while all other tools work fine. The import error: `cannot import name '_interrupt_event' from 'tools.terminal_tool'`.
