Last updated: March 2026

Architecture Overview

Claw-Stack is not a monolithic runtime that wraps OpenClaw. It is a collection of independent modules — each a separate project — that integrate with a running OpenClaw gateway through its native extension points, without modifying the upstream source.

OpenClaw: The Foundation

OpenClaw runs as a Node.js daemon (the "gateway") on your host machine. It manages AI agent sessions, routes messages from connected channels (iMessage, Telegram, Discord, WhatsApp, etc.) to agents, executes tool calls, and exposes a web control UI. All persistent configuration lives in ~/.openclaw/openclaw.json.

Claw-Stack modules extend this gateway through mechanisms OpenClaw already provides. There is no Claw-Stack runtime process — the gateway itself is the runtime.

Directory Structure

~/.openclaw/
├── openclaw.json          # Gateway config: agents, models, tool policy, channels
├── workspace/             # Main agent workspace (loaded at session start)
│   ├── MEMORY.md          # Session-start context (keep under ~200 lines)
│   ├── AGENTS.md          # Behavioral rules, routing, session hygiene
│   ├── TOOLS.md           # Tool usage guide, MCP server syntax
│   ├── SOUL.md            # Agent personality
│   ├── IDENTITY.md        # Agent identity and role
│   ├── memory/            # Per-topic memory files (loaded on demand)
│   │   ├── entities/      # Projects, contacts, servers
│   │   ├── patterns/      # Reusable patterns and workflows
│   │   ├── lessons.md     # Extracted lessons from past sessions
│   │   └── summaries/     # Session summaries
│   ├── memory-system/     # Memory organizer scripts (Claw-Stack module)
│   └── skills/            # Agent skill files
├── workspace-coding/      # Per-agent workspace for the coding agent
├── workspace-researcher/  # Per-agent workspace for the researcher agent
├── agents/                # Agent-specific state directories
├── cron/                  # Scheduled tasks
├── subagents/             # Subagent session state
├── logs/                  # Gateway and agent logs
└── credentials/           # Encrypted credentials store

Integration Points

Each Claw-Stack module uses one or more of these extension points:

1. MCP Servers

Modules expose their functionality as Model Context Protocol servers. The agent calls these tools through mcporter. Examples: agent-time-awareness (time context via HTTP MCP), chrome-devtools-mcp (browser control via npx).

Config: TOOLS.md documents the MCP tool syntax; the agent calls them natively during sessions.

2. OpenClaw Plugins (Hooks)

Plugins hook into the gateway's event lifecycle: before_tool_call, after_tool_call, llm_input, llm_output. Example: openclaw-security installs a JS bridge plugin that calls Python security modules on each hook event.

Config: openclaw plugins install --link ~/projects/openclaw-security/openclaw-plugin

3. Workspace Configuration Files

AGENTS.md, TOOLS.md, MEMORY.md, and skills files load into agent context at session start. This is the lowest-overhead integration — no running process required. Example: info-pipeline reports are referenced in MEMORY.md for daily briefings.

Config: edit the Markdown files directly.

4. OpenClaw Cron Tasks

The gateway has a built-in cron scheduler. Modules register shell commands to run on a schedule. Example: openclaw-backup schedules backup.sh to run daily; the memory-system organizer runs on its own cron schedule.

Config: openclaw cron add --schedule "0 4 * * *" --command "/path/to/script.sh"

5. Subagent Orchestration

OpenClaw has native subagent support. The main agent can spawn subagents via sessions_spawn, each running with their own workspace and tool permissions. agent-meeting uses this to coordinate multiple agents through a structured meeting loop.

Config: agents.list[].subagents.allowAgents in openclaw.json.

Agent Configuration

Agents are defined in ~/.openclaw/openclaw.json under agents.list. Each entry specifies the model, workspace path, identity, and which subagents it may spawn:

// ~/.openclaw/openclaw.json (excerpt)
{
  "agents": {
    "defaults": {
      "model": {"primary": "anthropic/claude-opus-4-6"},
      "workspace": "/Users/you/.openclaw/workspace",
      "subagents": {"maxConcurrent": 8, "maxSpawnDepth": 2}
    },
    "list": [
      {
        "id": "main",
        "subagents": {"allowAgents": ["*"]}
      },
      {
        "id": "coding",
        "workspace": "/Users/you/.openclaw/workspace-coding",
        "model": "anthropic/claude-sonnet-4-6"
      },
      {
        "id": "meeting",
        "workspace": "/Users/you/.openclaw/workspace-meeting",
        "tools": {"allow": ["read", "memory_search", "memory_get", "session_status"]}
      }
    ]
  }
}

Why Not Modify OpenClaw Directly?

Forking or patching OpenClaw creates a maintenance burden that grows with every upstream release. Using OpenClaw's native extension points means the gateway updates cleanly via npm install -g openclaw without merge conflicts. Each Claw-Stack module evolves independently — adding new capabilities without touching the agent execution engine.

Frequently Asked Questions

Is there a separate Claw-Stack runtime process?

No. The OpenClaw gateway is the only persistent process. Claw-Stack modules either run as MCP servers (when they need to be always-on) or as on-demand scripts invoked by cron or the agent. There is no Claw-Stack daemon, no IPC socket, and no policy gate process.

Can individual modules be used without the others?

Yes. Each module is an independent project with its own README and setup steps. You can run just chrome-devtools-mcp without openclaw-backup, or just the memory system without the voice interface.

What happens if an MCP server module crashes?

The agent receives a tool error from the MCP call and can handle it like any other tool failure. The OpenClaw gateway itself continues running. Other modules and agents are unaffected. Restart the crashed MCP server and the tool becomes available again in the next session.

Authors: Qiushi Wu & Orange 🍊