TAB 7 — REFERENCE

Framework reference.

OpenClaw and Hermes config, gotchas, and common tasks with Claude Code prompts.

This tab is your “look it up when you need it” reference. Everything about how OpenClaw and Hermes actually work, structured so you can jump to the specific thing you're troubleshooting. The top half is pure reference material. The bottom half is common tasks with ready-to-use Claude Code prompts.

Read this after you've built something. Skip it during first-time setup — Tab 2 has everything you need for that.

Part 1: Reference Material

OpenClaw

Language: Node.js / TypeScript
Requires: Node.js 24+ (check package.json engines field — not Node 20)
Package manager: pnpm
Main config: ~/.openclaw/openclaw.json
Workspace: ~/.openclaw/workspace/
Process manager: systemd (system-level, not user-level — see Tab 5 Incident 7)

File structure

text

~/.openclaw/
├── openclaw.json          ← main config (channels, models, plugins)
├── .env                   ← secrets (API keys, bot tokens)
├── workspace/
│   ├── SOUL.md            ← agent personality, values, voice
│   ├── USER.md            ← info about the human
│   ├── IDENTITY.md        ← agent's name, type, vibe, emoji
│   ├── AGENTS.md          ← operational manual, hard rules, memory system
│   ├── BOOTSTRAP.md       ← first-run script (auto-deletes after first conversation)
│   ├── HEARTBEAT.md       ← periodic check tasks
│   ├── TOOLS.md           ← environment-specific notes
│   ├── context/           ← additional reference documents
│   └── memory/            ← daily memory files (agent-managed)
└── devices/
    └── paired.json        ← Telegram device pairing state

Template loading order (every session)

SOUL.md — “Who am I?”
USER.md — “Who am I helping?”
memory/YYYY-MM-DD.md — today + yesterday's daily notes
MEMORY.md — long-term curated memory (main session only, not in group chats)

What goes where

Content	File	Why
Agent personality, role, voice, portfolio of responsibilities	SOUL.md	Defines the agent's character
Information about the user — name, preferences, context	USER.md	Tells the agent who it's serving
Agent's display name, emoji, vibe	IDENTITY.md	Metadata for display and routing
Hard rules, decision authority, memory system instructions	AGENTS.md	Operational manual
Domain knowledge, engagement context	context/ directory	Loaded on demand, referenced by path

Key gotchas

⚠

OpenClaw gotchas to know

workspace/ is the directory that matters. Files at the root ~/.openclaw/ are NOT loaded as templates. Only files in workspace/ are.
BOOTSTRAP.md auto-deletes. If it exists, the agent follows it on first conversation, then deletes it. Don't put anything in BOOTSTRAP.md you want to persist.
AGENTS.md defaults are good. The default AGENTS.md has solid operational guidance. Merge your rules into it rather than replacing it entirely.
Device pairing is fragile during rapid restarts. See Tab 5 Incident 11.
MEMORY.md only loads in main session (DMs). In group chats, MEMORY.md is NOT loaded — security feature to prevent personal context leaking.

Telegram configuration

json

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": { "source": "env", "provider": "default", "id": "TELEGRAM_BOT_TOKEN" },
      "dmPolicy": "allowlist",
      "allowFrom": ["YOUR_TELEGRAM_USER_ID"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["tg:YOUR_TELEGRAM_USER_ID"],
      "groups": {
        "-YOUR_GROUP_CHAT_ID": {
          "requireMention": false
        }
      }
    }
  }
}

systemd service (system-level)

ini

[Unit]
Description=OpenClaw Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=openclaw
Group=openclaw
SupplementaryGroups=agents
WorkingDirectory=/home/openclaw
EnvironmentFile=/etc/agent-board/shared.env
EnvironmentFile=/home/openclaw/.openclaw/.env
ExecStart=/home/openclaw/.npm-global/bin/openclaw gateway start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Key: SupplementaryGroups=agents allows the service to read files owned by root:agents (like the shared API key file).

Hermes

Language: Python
Requires: Python 3.10+
Main config: ~/.hermes/config.yaml + ~/.hermes/.env
Identity: ~/.hermes/SOUL.md (single file)
Memory: ~/.hermes/memories/ (agent-managed)
API server: Built-in, OpenAI-compatible, default port 8090

File structure

text

~/.hermes/
├── config.yaml            ← main config
├── .env                   ← secrets
├── SOUL.md                ← personality + role + hard rules (all in one file)
├── memories/
│   ├── USER.md            ← what the agent learns about the user (seed it, agent updates)
│   └── MEMORY.md          ← agent's personal notes
└── context/               ← additional reference documents

Template loading order

SOUL.md — injected as slot #1 in the system prompt. Everything about who the agent is.
memories/USER.md — what the agent knows about the user. Seeded by you, updated by the agent over time.

What goes where

Content	File	Why
Everything — personality, role, hard rules, decision authority, voice	SOUL.md	Hermes has one identity file; everything goes here
Seed information about the user (~200 words)	memories/USER.md	Agent builds on this over time
Domain knowledge, engagement context	context/ directory	Referenced by path from SOUL.md

⚠

Hermes gotchas to know

SOUL.md must be a standalone file, NOT a symlink. Writes to a symlink can modify the master copy.
Default base_url points to OpenRouter. Clear base_url in config.yaml if using Anthropic directly. See Tab 5 Incident 5.
memories/USER.md is agent-managed. You seed it, the agent updates it as it learns. Don't be alarmed when the content changes.
tool_progress default shows everything. Set display.tool_progress: off (not none or false). See Tab 5 Incident 9.
DISCORD_AUTO_THREAD defaults to true. Set DISCORD_AUTO_THREAD=false for inline replies. See Tab 5 Incident 8.

Key .env settings for Hermes

bash

# Required
ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=...

# Optional: Discord
DISCORD_BOT_TOKEN=...
DISCORD_ALLOWED_USERS=YOUR_DISCORD_USER_ID
DISCORD_ALLOW_BOTS=all
DISCORD_AUTO_THREAD=false
DISCORD_FREE_RESPONSE_CHANNELS=YOUR_CHANNEL_ID
DISCORD_REQUIRE_MENTION=true

Key config.yaml settings

yaml

display:
  tool_progress: off

# Clear this if using Anthropic directly (default points to OpenRouter)
# base_url: ""

systemd service (system-level)

ini

[Unit]
Description=Hermes Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=hermes
Group=hermes
SupplementaryGroups=agents
WorkingDirectory=/home/hermes
EnvironmentFile=/etc/agent-board/shared.env
EnvironmentFile=/home/hermes/.hermes/.env
ExecStart=/home/hermes/.hermes/venv/bin/python -m hermes_agent
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Cross-framework patterns

Shared secrets

If you're running multiple agents, share the Anthropic API key via a common file rather than duplicating it:

text

/etc/agent-board/shared.env    ← owned by root:agents, mode 640
    ANTHROPIC_API_KEY=sk-ant-...

All agent systemd services load this via EnvironmentFile=. The SupplementaryGroups=agents directive gives each service read access.

Shared context files

Both frameworks can share reference documents via a common directory:

text

/etc/agent-board/identity/context/    ← owned by root:agents, mode 640
    domain-knowledge.md
    project-context.md
    operating-principles.md

Symlink this directory into each agent's workspace. Reference in SOUL.md or workspace files as context/filename.md.

Telegram — platform limitation

Bots cannot see each other's messages on Telegram. This is a platform-level restriction. Both bots can see user messages in a group, but the bots are invisible to each other. See Tab 5 Incident 6.

Use Discord if you need bot-to-bot collaboration. Discord allows bots to see each other's messages when allowBots is enabled.

Part 2: Common Tasks (with Claude Code prompts)

The most common changes you'll make to a running agent board. Each task has a ready-to-use prompt you can copy into Claude Code.

Task 1: Update identity files

Use this when your priorities change, your context shifts, or you want to refine how the agent behaves.

▶ Claude Code Prompt

I want to update my agent's identity files. Please: 1. Show me the current content of `/home/openclaw/.openclaw/workspace/SOUL.md` so I can review what's there 2. Wait for me to tell you what changes I want 3. Show me the proposed changes as a diff before writing 4. After I approve, write the changes, restart the OpenClaw service, and verify it comes back up cleanly 5. Finally, remind me to test with a knowledge question ("what do you know about me?") to confirm the new identity loaded

Task 2: Add Discord to an existing OpenClaw setup

Use this when you've been running Telegram-only and want to add Discord as a second channel.

▶ Claude Code Prompt

I want to add Discord to my existing OpenClaw setup. I have: - Discord bot token: [I'll paste when you ask] - Discord server (guild) ID: [I'll paste when you ask] - My Discord user ID: [I'll paste when you ask] - The channel ID where the bot should respond: [I'll paste when you ask] Please: 1. Add `DISCORD_BOT_TOKEN=...` to `/home/openclaw/.openclaw/.env` 2. Update `/home/openclaw/.openclaw/openclaw.json` to add the discord channel configuration with: - Enabled = true, token from env var - dmPolicy = allowlist with my user ID - groupPolicy = allowlist - Guild config with requireMention = false in the target channel 3. Show me the changes before writing 4. Restart the service and verify 5. Tell me to test by @mentioning the bot in the Discord channel

Task 3: Reset a broken Telegram device pairing

Use this when your OpenClaw bot has stopped responding and the logs show a “pairing required” loop.

▶ Claude Code Prompt

My OpenClaw Telegram bot has stopped responding and I think the device pairing is broken. Please: 1. Check the OpenClaw logs for the last 10 minutes and look for "pairing required" or similar errors 2. Run `sudo -u openclaw /home/openclaw/.npm-global/bin/openclaw devices list` and show me the current device state 3. If there's a device in pending or repair status, show me the approve command before running it 4. If the scopes are insufficient, show me the `paired.json` content and propose the scope update before applying 5. After any fix, restart the service and tell me to send `/start` to the bot in Telegram

Task 4: Debug an agent that isn't responding

Use this when either agent has gone quiet and you don't know why.

▶ Claude Code Prompt

My agent isn't responding to messages. Please diagnose: 1. Check service status: `sudo systemctl status <service-name>` 2. Read the last 50 log lines: `sudo journalctl -u <service-name> --since "5 minutes ago" --no-pager` 3. Test the Anthropic API key directly with a curl call to make sure the key works and the API is reachable 4. Check that the env files exist with correct ownership and permissions 5. Check that the config file has valid JSON/YAML (no syntax errors) Show me what you find before making any changes. If you identify a fix, show me the fix before applying.

Task 5: Add a new context document for a project

Use this when you're starting new work and want the agent to have relevant background.

▶ Claude Code Prompt

I want to add a new context document for a project I'm working on. The content I want to add is: [paste the markdown content] Please: 1. Save it to `/etc/agent-board/identity/context/<descriptive-filename>.md` with owner root:agents and mode 640 2. Verify the context directory is symlinked into the OpenClaw workspace at `/home/openclaw/.openclaw/workspace/context` 3. Update SOUL.md or USER.md to reference the new file by path so the agent knows to consult it 4. Restart the service 5. Remind me to test with a question that would require the new context

Task 6: Quick diagnostic commands

Fast sanity checks you can run yourself when something feels off — no Claude Code needed.

quick-diagnostics.shbash

# Is the agent running?
sudo systemctl status openclaw

# Read recent logs
sudo journalctl -u openclaw --since "5 minutes ago" --no-pager | tail -30

# Restart the agent
sudo systemctl restart openclaw

# Test API key directly
source /etc/agent-board/shared.env && curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# Check workspace files exist
ls -la /home/openclaw/.openclaw/workspace/

# Check context symlink
ls -la /home/openclaw/.openclaw/workspace/context/

# Check device pairing state
sudo -u openclaw cat /home/openclaw/.openclaw/devices/paired.json | python3 -m json.tool

← PreviousTab 6: Models