---
name: hermes-telegram-cutover
description: Cut Telegram from OpenClaw to Hermes gateway — one bot token, clean handoff. Use when Alexander wants real Timmy (with memories/sessions) on Telegram instead of the OpenClaw lobster.
triggers:
  - "openclaw telegram"
  - "timmy telegram hermes"
  - "real timmy on telegram"
  - "cut telegram"
version: 1
---

# Hermes Telegram Cutover from OpenClaw

## Context
OpenClaw and Hermes both have Telegram gateway capability but only ONE process can poll a given bot token (Telegram returns 409 Conflict on duplicate polling). OpenClaw has no Hermes memories/sessions — it's a lobster. This procedure does a clean cut.

## Pre-flight
1. Verify the Telegram bot token is in `~/.hermes/.env`:
   ```
   grep TELEGRAM_BOT_TOKEN ~/.hermes/.env
   ```
2. Verify Hermes gateway is running:
   ```
   ps aux | grep 'hermes.*gateway'
   curl -s http://localhost:8642/health
   ```
3. Verify OpenClaw is currently holding Telegram:
   ```
   grep -A3 '"telegram"' ~/.openclaw/openclaw.json
   ```

## Steps

### 1. Disable Telegram in OpenClaw config
```python
# Use Python to safely edit JSON
import json
with open(os.path.expanduser('~/.openclaw/openclaw.json')) as f:
    c = json.load(f)
c['channels']['telegram']['enabled'] = False
with open(os.path.expanduser('~/.openclaw/openclaw.json'), 'w') as f:
    json.dump(c, f, indent=4)
```

### 2. Add Telegram platform to Hermes config.yaml
```python
import yaml
config_path = os.path.expanduser('~/.hermes/config.yaml')
with open(config_path) as f:
    config = yaml.safe_load(f)
config['platforms']['telegram'] = {'enabled': True}
with open(config_path, 'w') as f:
    yaml.dump(config, f, default_flow_style=False, sort_keys=False)
```
Note: Use the Hermes venv python for yaml (`~/.hermes/hermes-agent/venv/bin/python3`), system python may not have PyYAML.

### 3. Restart gateways

**Preferred method — use OpenClaw's own restart command:**
```bash
openclaw gateway stop          # Gracefully stops the LaunchAgent, releases bot token
sleep 2                        # Wait for polling to fully release
cd ~/.hermes/hermes-agent && venv/bin/hermes gateway run
```

**If on iPad/remote (tmux injection):**
```bash
# Find tmux session
/opt/homebrew/bin/tmux list-sessions
/opt/homebrew/bin/tmux list-windows -t dev
# Create new window and send commands
/opt/homebrew/bin/tmux new-window -t dev
/opt/homebrew/bin/tmux send-keys -t dev 'openclaw gateway stop && sleep 2 && cd ~/.hermes/hermes-agent && venv/bin/hermes gateway run' Enter
# Monitor output
sleep 10 && /opt/homebrew/bin/tmux capture-pane -t dev -p -S -30
```

**Pitfall:** `hermes gateway --replace` is NOT a valid flag (despite being in some docs). Use `hermes gateway run`. If an existing Hermes gateway is already running, it will need to be killed first or use a different port.

**Pitfall:** `openclaw gateway restart` re-reads config but the LaunchAgent may cache state. Use `openclaw gateway stop` then start Hermes separately — cleaner than restart which immediately respawns OpenClaw.

### 4. Verify
Check gateway log for Telegram polling:
```bash
tail -20 ~/.hermes/logs/gateway.log | grep -i telegram
```
Should see:
- `Gateway running with 3 platform(s)` (api_server + discord + telegram)
- `getUpdates` calls returning 200 OK
- `[Telegram] Flushing text batch` when messages arrive

DM the bot — response should have Hermes tool traces and access to memories.

### 5. Known issue: execute_code may be broken
After Allegro's security patches (PR #60, interrupt race condition fix), `code_execution_tool.py` may fail with:
```
ImportError: cannot import name '_interrupt_event' from 'tools.terminal_tool'
```
This breaks the `execute_code` tool but all other tools (terminal, file ops, search, browser, etc.) still work. Fix by ensuring hermes-agent is on a consistent commit.

## Required env vars in ~/.hermes/.env
```
TELEGRAM_BOT_TOKEN=<bot token>
TELEGRAM_HOME_CHANNEL=<group chat id>
TELEGRAM_HOME_CHANNEL_NAME=<display name>
TELEGRAM_ALLOWED_USERS=<comma-separated telegram user IDs>
```

## Pitfalls
- Two processes polling same bot token = 409 Conflict. Kill OpenClaw gateway BEFORE starting Hermes telegram.
- System python on Mac may not have PyYAML — use the Hermes venv python.
- OpenClaw stores config as JSON (`openclaw.json`), Hermes stores as YAML (`config.yaml`). Don't mix formats.
- The Hermes API server endpoint (`/v1/chat/completions` on port 8642) is a separate thing from the Telegram gateway. Both can run simultaneously.
