OpenClaw

• 1: Getting Started with OpenClaw
• 2: Lossless Claw: Never Lose Context Again
• 3: OpenClaw + Hermes: Multi-Agent Infrastructure
• 4: Building Modular Content Moderation with Guardrails

1 - Getting Started with OpenClaw

OpenClaw is an open-source agent orchestration platform that helps you build AI agents with persistent memory, skill systems, and multi-agent coordination.

Core Concepts

Memory Architecture

OpenClaw uses a three-tier memory model:

• Episodic - Daily logs (memory/episodic/YYYY-MM-DD.md)
• Semantic - Knowledge base (memory/semantic/topic.md)
• Procedural - Workflows (memory/procedural/process.md)

Skills System

Skills are modular capabilities stored in ~/.openclaw/skills/. Each skill has:

• SKILL.md - Documentation
• Scripts or tools
• Configuration

Sub-agents

OpenClaw can spawn specialized sub-agents for tasks:

• homelab-guardian - Infrastructure management
• researcher - Web research and analysis
• communicator - Outbound messages
• orchestrator - Tool selection

Quick Start

Installation

# Install OpenClaw
npm install -g openclaw

# Initialize workspace
openclaw init

First Agent

# Create a simple agent
openclaw agent create my-agent

# Run it
openclaw agent run my-agent

Next Steps

• Memory Management Best Practices - Learn about the memory architecture
• Security Framework - Understand agent security levels

This guide covers the basics of OpenClaw. For more details, see the OpenClaw documentation.

2 - Lossless Claw: Never Lose Context Again

Every LLM has a context window — a maximum number of tokens it can process. When a conversation exceeds this limit, most agents simply truncate older messages. Lossless Claw replaces truncation with a DAG (Directed Acyclic Graph) summarization system that preserves every message while keeping active context within model token limits.

What You’ll Learn

• Why context loss happens and why it matters
• How LCM (Lossless Context Management) preserves every message
• Step-by-step installation and configuration
• Best practices for long-lived agent sessions

The Problem: Context Loss

When context exceeds the token limit:

[message 1] [message 2] ... [message 150]
                    ↓ Context window exceeded
[message 120] [message 121] ... [message 150]  ← First 119 messages LOST

What you lose:

• Earlier instruction context
• Decisions made at session start
• Tool outputs and results
• The “why” behind current work

The Solution: Lossless Context Management

Lossless Claw preserves every message through hierarchical summarization:

[raw messages 1-8]    → leaf_summary_1
[raw messages 9-16]   → leaf_summary_2
...
[leaf_summary_1-4]    → condensed_summary

Raw messages are never deleted — they’re stored in SQLite and linked to summaries. Agents can drill down through the DAG to recover any original message using lcm_grep, lcm_describe, or lcm_expand.

Key Benefits

Installation

Prerequisites

• OpenClaw with plugin context engine support
• Node.js 22+
• LLM provider configured

Install via OpenClaw CLI

openclaw plugins install @martian-engineering/lossless-claw

Restart Gateway

openclaw gateway restart

Configuration

Basic Configuration

Add to your ~/.openclaw/openclaw.json:

{
  "plugins": {
    "allow": ["lossless-claw"],
    "slots": {
      "contextEngine": "lossless-claw"
    },
    "entries": {
      "lossless-claw": {
        "enabled": true,
        "config": {
          "freshTailCount": 64,
          "contextThreshold": 0.70,
          "incrementalMaxDepth": -1
        }
      }
    }
  }
}

Key Settings Explained

Cost Optimization

Summaries don’t need top-tier reasoning. Use a cheaper model for compaction:

# Add to ~/.openclaw/.env
LCM_SUMMARY_MODEL=ollama-cloud/glm-5
LCM_SUMMARY_PROVIDER=ollama-cloud

This uses GLM-5 for summarization while your main conversation uses a more capable model.

Extend Session Lifetime

LCM preserves context, but OpenClaw still resets sessions. Extend the idle timeout:

{
  "session": {
    "reset": {
      "mode": "idle",
      "idleMinutes": 10080
    }
  }
}

Common values:

• 1440 = 1 day
• 10080 = 7 days
• 43200 = 30 days

Agent Tools

LCM provides three tools for agents to recall compacted history:

lcm_grep

Search across all messages and summaries:

lcm_grep(query: "kubernetes", mode: "regex", allConversations: true)

lcm_describe

Get details about a specific summary:

lcm_describe(id: "sum_abc123")

lcm_expand

Drill down into a summary to recover original messages:

lcm_expand(summaryIds: ["sum_abc123"], includeMessages: true)

Storage

Database Location

~/.openclaw/lcm.db

Size Considerations

• Every message is stored
• SQLite database grows linearly
• No built-in pruning (manual cleanup available via TUI)

Backup

# Simple backup
cp ~/.openclaw/lcm.db ~/.openclaw/lcm.db.backup

Best Practices

1. Set freshTailCount appropriately - Higher values protect more recent context at cost of earlier compaction
2. Use cost-effective summary models - GLM-5, local Ollama models
3. Monitor database size - Check ~/.openclaw/lcm.db periodically
4. Extend session lifetime - Match idleMinutes to your work patterns
5. Test with long sessions - Verify compaction behavior before production

Comparison to Alternatives

Common Issues

Plugin not loading

[plugins.allow is empty; discovered non-bundled plugins may auto-load

Fix: Add explicit allowlist:

{
  "plugins": {
    "allow": ["lossless-claw"]
  }
}

Summarization failing

Check your LLM provider configuration:

openclaw models list

Database locked

Close any database viewers and restart gateway:

openclaw gateway restart

Rollback

To disable LCM:

{
  "plugins": {
    "slots": {},
    "entries": {
      "lossless-claw": {
        "enabled": false
      }
    }
  }
}

Then restart gateway. Your lcm.db is preserved.

Resources

• Lossless Claw GitHub
• LCM Paper
• Animated Visualization
• Configuration Guide

Next Steps

1. Install and configure (above)
2. Run a long session (2+ hours)
3. Use lcm_grep "topic" to test recall
4. Check ~/.openclaw/lcm.db size after heavy use
5. Adjust contextThreshold and freshTailCount to taste

Now your agent never forgets. Because it doesn’t have to.

3 - OpenClaw + Hermes: Multi-Agent Infrastructure

Connect OpenClaw (Clawdia) to Hermes Agent for delegating infrastructure tasks via HTTP API. This lets you manage Docker, Kubernetes, and GitOps operations through conversational commands.

What You’ll Learn

• When to use multi-agent architecture for infrastructure tasks
• How to connect OpenClaw to Hermes via HTTP API
• Configuring the Hermes integration skill
• Querying Docker, deploying stacks, and managing GitOps
• Security considerations for agent-to-agent communication

Why Multi-Agent?

Running everything in one agent creates a security problem. Infrastructure tasks need terminal and Docker access—capabilities you don’t want tied to your general-purpose assistant.

Splitting these concerns means:

• Hermes can have elevated host access while staying isolated
• OpenClaw delegates infrastructure work through a controlled API
• Each agent does what it’s designed for

Both agents run on the same host (openclaw-node01) and communicate over localhost.

The Architecture

┌─────────────────┐         HTTP API          ┌─────────────────┐
│   OpenClaw      │  ═══════════════════════► │     Hermes      │
│   (Clawdia)     │    localhost:8642         │   (SRE Agent)   │
│                 │  ◄═══════════════════════ │                 │
│  - Skills       │    JSON responses         │  - Terminal     │
│  - Memory       │                           │  - Docker       │
│  - Subagents    │                           │  - Komodo API   │
└─────────────────┘                           │  - kubectl      │
                                              └─────────────────┘

Communication stays on 127.0.0.1:8642—no external exposure needed.

Prerequisites

• OpenClaw running (see Getting Started with OpenClaw)
• Hermes Agent installed with GitOps configured
• Python 3.10+ with httpx
• Hermes API key (stored in 1Password or secrets manager)

Step 1: Configure Hermes API Server

Hermes exposes an OpenAI-compatible HTTP API that OpenClaw uses to delegate tasks.

1.1 Configure Environment

Add to ~/.hermes/.env:

# Enable API server
API_SERVER_ENABLED=true
API_SERVER_KEY=${HSM_HERMES_API_KEY}

# Bind to localhost only
API_SERVER_HOST=127.0.0.1
API_SERVER_PORT=8642

Security: 127.0.0.1 restricts access to the local machine only. Hermes has full terminal access—don’t expose this port externally.

1.2 Start the Server

Via Komodo:

services:
  hermes-api:
    image: hermes-agent:latest
    command: hermes gateway
    env_file: ~/.hermes/.env
    ports:
      - "127.0.0.1:8642:8642"  # Bind to localhost only
    restart: unless-stopped

Or run directly:

hermes gateway

1.3 Verify

curl http://127.0.0.1:8642/health

Expected: {"status": "ok"}

Step 2: Install the OpenClaw Skill

The Hermes skill lives at ~/.openclaw/skills/hermes/.

2.1 Set API Key

# In ~/.openclaw/.env
export HERMES_API_KEY=$(op read op://OpenClaw/hermes-api/key)

2.2 Skill Structure

The skill provides a Python client (hermes.py) and configuration (SKILL.md). Place the skill files in:

~/.openclaw/skills/hermes/
├── SKILL.md          # Skill definition
├── hermes.py         # Python client
└── README.md         # Usage docs

2.3 Restart OpenClaw

openclaw gateway restart

Step 3: Test the Integration

Example: Check Docker Status

from hermes import HermesClient

async def check_containers():
    hermes = HermesClient()
    
    result = await hermes.chat(
        message="Run 'docker ps' and show running containers",
        system_prompt="Execute commands and report results concisely."
    )
    
    print(result)
    await hermes.close()

What happens:

1. OpenClaw sends the request to Hermes via HTTP API
2. Hermes executes docker ps using its terminal tool
3. Results return formatted through the API

Available Tools

Hermes exposes these capabilities through the API:

Common Usage Patterns

Pattern 1: One-Shot Infrastructure Query

For quick checks where you just need the answer:

result = await hermes.chat(
    message="How much disk space is left on /var/lib/docker?",
    system_prompt="Run 'df -h /var/lib/docker' and report the result."
)

Pattern 2: Stateful Multi-Turn Conversation

For complex tasks requiring context:

from hermes import HermesSession

session = HermesSession(hermes, "postgres-deploy-001")

# First message establishes context
await session.send("I need to deploy a PostgreSQL database")

# Subsequent messages have full context
await session.send("Use the template from /opt/stacks/templates/postgres")
await session.send("Set the password from my secrets manager")

Pattern 3: Stream Long Operations

async for chunk in hermes.chat_stream("Deploy nextcloud stack"):
    print(chunk, end="")  # Live progress updates

API Reference

HermesClient

class HermesClient:
    def __init__(
        self,
        base_url: str = "http://127.0.0.1:8642",
        api_key: Optional[str] = None,
        timeout: float = 300.0  # 5 minutes for long operations
    )
    
    async def chat(
        self,
        message: str,
        system_prompt: Optional[str] = None,
        stream: bool = False
    ) -> str
    
    async def chat_stream(
        self,
        message: str
    ) -> AsyncGenerator[str, None]
    
    async def close(self)

Error Handling

from httpx import HTTPStatusError, ConnectError

try:
    result = await hermes.chat("Deploy stack")
except ConnectError:
    print("Hermes API not running. Start with: hermes gateway")
except HTTPStatusError as e:
    if e.response.status_code == 401:
        print("Invalid API key. Check HERMES_API_KEY")
    else:
        print(f"API error: {e}")

Security Best Practices

Authentication

• Store API_SERVER_KEY in 1Password or similar—never in code
• Use environment variable injection, not hardcoded strings
• Rotate keys periodically

Network Security

• Always bind to 127.0.0.1—never 0.0.0.0 or public interfaces
• Both agents should run on the same trusted host
• Consider firewall rules to block external access to port 8642

Scope of Access

Remember: Hermes has full terminal access to your host. Be intentional about:

• Which OpenClaw agents can invoke Hermes
• What commands you’re delegating
• Using read-only operations when possible for safety

Troubleshooting

Known Issue: Import Variable Not Defined

Error: NameError: name 'HAS_REQUESTS' is not defined

Cause: The client tries multiple HTTP libraries but doesn’t initialize fallback variables properly.

Fix: Initialize all flags before the try blocks:

# In hermes.py
HAS_HTTPX = False
HAS_REQUESTS = False

try:
    import httpx
    HAS_HTTPX = True
except ImportError:
    pass

try:
    import requests
    HAS_REQUESTS = True
except ImportError:
    pass

Real-World Examples

Deploy a Stack via Komodo

result = await hermes.chat(
    message="Deploy the 'nextcloud' stack using Komodo. Ensure volumes are created first.",
    system_prompt="You are a GitOps SRE. Use the Komodo API to deploy Docker Compose stacks."
)

Check Kubernetes Pod Status

result = await hermes.chat(
    message="Check the status of pods in the monitoring namespace",
    system_prompt="Use kubectl to get pod status and report any issues."
)

File Operations with Safety

result = await hermes.chat(
    message="Show me the last 50 lines of /var/log/syslog",
    system_prompt="Read the file and display the content. Do not make changes."
)

Next Steps

• Add specialized agents for other domains
• Automate infrastructure checks with cron
• Set up alerts for Hermes-reported issues
• Document your own runbooks as delegatable tasks

Resources

• Hermes Agent Documentation
• OpenClaw Skills Framework
• AgentSkills Specification

Last updated: April 14, 2026

Have questions or feedback? Open an issue on the guides repository.

4 - Building Modular Content Moderation with Guardrails

When building AI agents, content moderation is often an afterthought — if it’s considered at all. This guide walks through building a modular guardrails skill for OpenClaw that can be optionally imported into any skill that needs content filtering.

Why Modular Over Middleware?

Traditional approaches often bake moderation into the core agent loop. This has drawbacks:

• All-or-nothing — You either moderate everything or nothing
• Hard to test — Global changes affect everything
• Inflexible — Different skills may need different rules

A modular approach lets you:

• Add moderation only where needed
• Test in isolation
• Customize rules per skill
• Disable easily without side effects

The Two-Phase Approach

Rather than building a comprehensive solution upfront, we used progressive enhancement:

Phase 1: Rule-based credential leak detection

• Fast pattern matching
• No external dependencies
• Catches the most critical issue (accidental credential exposure)

Phase 2: Full NeMo Guardrails integration (future)

• Richer content analysis
• NVIDIA’s safety models
• Comprehensive threat detection

Project Structure

~/.openclaw/skills/guardrails/
├── SKILL.md           # Documentation
├── __init__.py        # Package marker
├── guardrails.py      # Core module
└── test_guardrails.py # Tests

Phase 1 Implementation

The Core Module

# guardrails.py
import os
import httpx
from dataclasses import dataclass
from typing import Optional

API_URL = os.getenv("NEMOGUARDRAILS_API_URL", "http://localhost:8002")

@dataclass
class ModerationResult:
    safe: bool
    content: str
    reason: Optional[str] = None
    raw: Optional[dict] = None

class Guardrails:
    """Simple wrapper for content moderation."""
    
    def __init__(self, api_url: str = API_URL):
        self.api_url = api_url
        self.client = httpx.Client(timeout=30.0)
    
    def check(self, content: str) -> ModerationResult:
        """Check both input and output moderation."""
        return self._basic_check(content)
    
    def check_input(self, content: str) -> ModerationResult:
        """Check user input before processing."""
        return self._basic_check(content)
    
    def check_output(self, content: str) -> ModerationResult:
        """Check model output before returning."""
        return self._basic_check(content)
    
    def _basic_check(self, content: str) -> ModerationResult:
        """Rule-based content check."""
        blocked_words = ["password", "secret", "api_key", "token"]
        content_lower = content.lower()
        
        for word in blocked_words:
            if word in content_lower:
                # Check for credential patterns
                if f"{word} is" in content_lower or f"{word}:" in content_lower:
                    return ModerationResult(
                        safe=False,
                        content=content,
                        reason=f"Potential credential leak detected"
                    )
        
        return ModerationResult(safe=True, content=content, reason=None)

Usage in Other Skills

# In your-skill/your-skill.py
from guardrails import Guardrails

class YourSkill:
    def __init__(self):
        self.guardrails = Guardrails()
    
    def process(self, content):
        # Check input
        result = self.guardrails.check_input(content)
        if not result.safe:
            raise ValueError(f"Content blocked: {result.reason}")
        
        # Process...
        response = self._generate_response(content)
        
        # Check output
        result = self.guardrails.check_output(response)
        if not result.safe:
            return "I cannot share that information."
        
        return response

Testing Phase 1

False positive: “I forgot my password once” is blocked (acceptable — better safe than sorry)

Next Steps

1. Import into a real skill (e.g., communicator)
2. Add Phase 2 NeMo Guardrails integration
3. Write comprehensive test suite

References

• NeMo Guardrails: https://github.com/NVIDIA/NeMo-Guardrails
• OpenClaw Skills: https://docs.openclaw.ai/skills