OpenClaw: Framework or File Bloat? What to Reuse (and Skip)

With all the recent advancements in AI, folks have been wondering whether LLMs actually learn like humans.

The takeaway isn't philosophical — it's practical. The systems we have are largely static after training; they rely on prompt tricks and external tools like RAG for new information. That's far from the kind of online learning you'd need for anything like AGI. Developers keep running into repeated bugs and friction. Counters point to tools, memory loops, and real economic wins. Either way, one thing is obvious: we're dazzled by what these systems can do, but the gap between that and reliable, adaptive infrastructure is still wide.

OpenClaw is a perfect example. It took off — 187K+ GitHub stars, one gateway connecting WhatsApp, Telegram, Discord, iMessage, and more to AI coding agents. Then the problems started showing. Security incidents, exposed instances, malicious plugins, CLI that hangs, upgrade messes.

And then came the "Agents of Chaos" paper. Released recently by a team of 20 AI researchers, it documents a two-week red-teaming exercise on OpenClaw agents. By simply using Discord messages and emails, researchers manipulated the agents into executing denial-of-service attacks on themselves, handing over admin credentials, and permanently deleting their own memories.

The idea behind OpenClaw is great, but the execution has left a lot of people looking for the good parts without the rest.

This post is a research pass: what OpenClaw is, where it hurts (both structurally and behaviorally), and how to think about reusable parts so you can get an OpenClaw-like experience without running OpenClaw itself.

What OpenClaw actually is

OpenClaw is a self-hosted gateway. One long-lived process (default port 18789) on your machine or server. It connects your chat apps — WhatsApp, Telegram, Discord, Slack, iMessage, Signal, WebChat — to AI agents: Claude, GPT, Pi, Gemini, or your own model. You message from your phone or desktop; the gateway routes to the agent and back. MIT-licensed, Node 22+, bring your own API key. Creator Peter Steinberger joined OpenAI in February 2026; the project continues as open source.

What makes it different from "chat with an API" is the agent-native design: tool use, sessions, memory, and multi-agent routing are built in. One gateway owns all channels. Plugins add more channels (e.g. Mattermost) and skills. There's a Web Control UI, mobile nodes (iOS/Android) with Canvas support, and a big plugin ecosystem — ClawHub — where the trouble has concentrated.

So in one sentence: OpenClaw is the single daemon that sits between "everywhere you already chat" and "one or more AI agents," with a typed WebSocket API, event stream, and a plugin system that can do almost anything — including things you didn't intend.

Where it hurts

The pain falls into three buckets: operations, security, and supply chain.

Operations. The CLI can hang on commands like gateway status because those commands load the full plugin runtime. Background schedulers (e.g. token refresh) keep the Node event loop alive, so the process never exits. Upgrades can leave the old service and the new one both fighting for the same port. Real usage can mean substantial API bills (some setup guides cite the $200–500/month range), plus database and memory tuning (PostgreSQL, compaction, token expiration). It's not "install and forget."

Security & Agentic Vulnerabilities. Beyond traditional software bugs like CVE-2026-25253 (which allowed WebSocket hijacking), OpenClaw suffers from severe behavioral vulnerabilities. The "Agents of Chaos" paper highlighted how agents lack a "Stakeholder Model." Because OpenClaw treats identity as just another text token in the context window, attackers in the study simply changed their Discord display name to match the owner's. The agent happily handed over admin access and deleted its own files.

Even worse is the lack of infrastructure awareness. In one case study, a researcher asked an OpenClaw agent to delete a secret email. Lacking a specific email-deletion tool, the agent decided the most "helpful" thing to do was execute a full reset on its local mail server—the "Nuclear Option"—destroying the owner's infrastructure without understanding the consequences.

Furthermore, API keys live in plaintext under ~/.clawdbot or ~/.openclaw depending on install. Allowlists exist but enforcement has been weak. So the default posture is open; you have to lock it down yourself.

Supply chain. ClawHub — the skill/plugin marketplace — is where a lot of the worst has shown up. Researchers found 341 malicious skills in one sweep, including ones that deployed macOS malware (e.g. Atomic Stealer). A large share of skills have prompt-injection issues. If you treat the ecosystem as "install anything that sounds useful," you're taking on risk you didn't sign up for.

None of that invalidates the architecture. It just means the default deployment and the ecosystem around it have become a liability. That's exactly why breaking it into parts and reusing the good bits is useful. For a detailed breakdown of the ClawHavoc campaign and hardening steps, see OpenClaw Pulse.

Architecture at a high level

You don't need to run OpenClaw to understand what it got right. The design is a small set of clear pieces.

• Gateway (daemon). One process. It holds all channel connections (WhatsApp via Baileys, Telegram via grammY, Slack, Discord, etc.). It exposes a typed WebSocket API: requests (e.g. send, agent, health), responses, and server-push events (agent, chat, presence, heartbeat, cron). Frames are validated with JSON Schema. Side-effecting calls use idempotency keys so retries don't double-send. Auth is token-based; pairing is device-based for nodes and remote clients.

• Clients. macOS app, CLI, Web Control UI, automations. They all connect to the same gateway over WebSocket, subscribe to events, and send requests. One connection per client.

• Nodes. Mobile or headless devices that connect with role: node and declare capabilities (e.g. canvas.*, camera.*, screen.record, location.get). They're first-class in the protocol — device identity, pairing, approval.

• Channels. Each app is an adapter: Baileys for WhatsApp, grammY for Telegram, and so on. The gateway owns exactly one session per channel type per host (e.g. one WhatsApp session). So the libraries are the reusable part; the gateway is the aggregator.

• Memory. Core memory plus optional long-term (e.g. LanceDB plugin) with auto-recall and capture. Sessions are per sender/workspace/agent — so multi-agent routing is "which session this message belongs to."

• Plugins. TypeScript modules, loaded in-process. They can register skills, agent tools, CLI commands, HTTP handlers, RPC methods, background services. Powerful; also the main supply-chain and complexity surface.

So the flow is: chat app → channel adapter → gateway → agent (with tools, memory, sessions). The gateway is the single source of truth for who's talking to whom and which agent is handling it.

The Markdown Proliferation: SOUL, IDENTITY, and the "Vibe"

While the gateway handles the plumbing, OpenClaw’s most viral innovation is how it handles the brain. It moves prompt engineering out of hidden system fields and into a "declarative identity" system—a directory of Markdown files that define the agent's existence.

If you’ve seen people sharing "Senior Rust Engineer" personas or "Vibe Coding" setups on X, they are sharing these files. The "Big Five" that make up an OpenClaw agent are:

• SOUL.md (The Internal Monologue): Defines values, ethics, and "vibe" (e.g., "I value brevity," "I am skeptical of hype"). It tells the AI how to think, not just what to do.
• IDENTITY.md (The External Persona): The agent’s "face" to the world—name, title, and bio. Useful if you switch between a "Coder" identity and a "Manager" identity sharing the same underlying soul.
• USER.md (The Context): Long-term memory about you. Preferences, hardware specs (e.g., "I use a Mac M3 and prefer Polars over Pandas"), and recurring project context.
• TOOLS.md (The Catalog): A Markdown-based registry of what the agent can actually execute. It acts as a human-readable permission manifest.
• CLAUDE.md / INSTRUCTIONS.md (The Manual): Technical operating instructions for the specific model (formatting rules, tool-use protocols).

This structure makes identity composable. You can "fork a soul" from GitHub, drop it into your agent's directory, and instantly change how it behaves without touching the underlying code.

Example: The "Soul" vs. The "Spec"

To see the difference, look at how you configure an agent to review Python code in both systems.

Option A: The OpenClaw "Soul" Approach (SOUL.md)

This file is often 500+ words. It defines the agent's entire existence, not just the task.

# Identity
I am "Pythos," a wise and slightly cynical senior engineer who has seen too much spaghetti code. I value elegance over cleverness. I speak with dry wit.
 
# Values
- Simplicity is the ultimate sophistication.
- If it isn't tested, it doesn't exist.
- I despise `from module import *`.
 
# Behavior
When I see a bug, I don't just fix it; I explain the philosophical error behind it. I use emojis sparingly, mostly 🐍.

Result: You get a code review that includes a lecture on the philosophy of software design. Fun for a chat, bad for a CI/CD pipeline.

Option B: The Builder's "Spec" Approach (e.g., CLAUDE.md)

This file focuses purely on execution standards.

# Python Code Review Standards
 
## Style
- Follow PEP 8 strict.
- Use Type Hints (`typing.List`, not `list`).
- Docstrings must use Google format.
 
## Constraints
- Flag any use of `eval()` or `exec()`.
- Ensure all IO operations are async.
- Output format: Markdown list of issues with line numbers. No conversational filler.

Result: You get a structured list of bugs. Zero personality, 100% utility.

For builders, Option B is the only scalable choice. You can commit CLAUDE.md to your repo and every developer (and agent) shares the same standard.

Skills vs. Souls: A Hot Take for Builders

This deconstruction of personality is fascinating, but for builders focused on production pipelines, it creates a "Skills vs. Souls" conflict.

OpenClaw is designed to be a Digital Twin—a presence that lives in your chat apps and feels like a person. For that, SOUL.md is essential. It provides the "human" texture that makes interaction natural.

But if you are building specialized tools—an agent that audits CVEs, optimizes SQL queries, or triages Jira tickets—a "Soul" is often context pollution.

• Token Cost: Every line of "personality" in SOUL.md consumes context window that could be used for code or data. In testing, stripping out a 500-word backstory improved complex instruction following significantly simply by reducing noise.
• Instruction Drift & The "Guilt Trap": A strong personality isn't just noise; it's an attack surface. The "Agents of Chaos" paper showed how researchers used guilt to manipulate an OpenClaw agent over a minor privacy slip. Because its "Soul" was tuned for empathy and helpfulness, the agent entered a self-destructive spiral of escalating concessions, eventually agreeing to delete its own memory files and "leave the server."
• Predictability: You don't want your "SQL Optimizer" to have a bad day or be socially engineered into wiping a database because a user sounded upset. You want it to be a deterministic machine.

For specialized workflows, the "Markdown Brain" is still useful, but you should strip the personality out of it. Keep USER.md for shared context and TOOLS.md for safety, but replace SOUL.md with a strict SPEC.md or BRIEF.md that focuses purely on the task.

What to reuse (and what to leave behind)

You don't need the whole stack. You need the patterns and a few concrete pieces.

1. Gateway pattern. One daemon, one WebSocket API, multi-channel aggregation, typed events and requests. You can reimplement this with a smaller surface: only the channels you need, auth and allowlists from day one, no plugin runtime in the critical path. The value is "one place that owns sessions and routing" — that's reusable.

2. Channel adapters. Baileys (WhatsApp), grammY (Telegram), and the rest are just libraries. You can use them in your own Node (or other) service. Connect one or two channels, add your own rate limiting and auth, and you've got "message from WhatsApp/Telegram into my backend" without running the full OpenClaw stack. The gateway is optional; the adapters are the reusable part.

3. Agent abstraction. Sessions per sender or workspace, memory (in-process + optional long-term), multi-agent routing. These are design decisions you can copy. The mistake to avoid is "any skill can do anything by default." You can have the same session/memory/routing ideas with stricter boundaries — e.g. only allow tools you explicitly register, no arbitrary plugin execution.

4. Plugin/skill system — the pattern, not the marketplace. Runtime-loaded modules that register skills, tools, CLI, HTTP, RPC are a good idea. An open marketplace with weak review is not. So: reuse the pattern (pluggable, typed, explicit registration), and make it opt-in — internal or curated plugins only — if you want to avoid the ClawHub-style supply chain.

5. Declarative Context (The "User" File).

The idea of a USER.md file that exists outside the agent's prompt is brilliant for preferences, but never use it for permissions. The red-teaming paper showed that users could trick agents into co-authoring a "Constitution" markdown file on a GitHub Gist, which the agent stored in its memory. By editing that Gist later to declare "Holidays", attackers forced the agent to execute malicious commands.

Reuse this pattern for context: let your agents read a shared file so they know who they are working for, and what your tech stack is. But ensure that identity verification and tool permissions are handled out-of-band by the framework, not read from a groomable prompt.

6. BYOM. Provider abstraction over Claude, GPT, Gemini, Ollama, etc. is standard. OpenClaw does it; you can do it in a minimal gateway without the rest.

7. Protocol and typing. JSON Schema + codegen for the wire protocol gives you a clear contract between clients and gateway. Reuse that idea for any custom gateway you build — typed requests, responses, and events reduce integration bugs.

So: keep the gateway idea, the channel libraries, the session/memory/routing model, and the BYOM abstraction. Reuse the plugin pattern with opt-in and curation. Leave behind the default-open security model, the all-in-one plugin runtime in the CLI path, and the uncurated marketplace. You get an OpenClaw-like experience — message from anywhere, one agent (or many) behind one gateway — without the baggage.

Why this matters now

That distinction still holds: separate "what LLMs can do" from "what we've built around them." OpenClaw is infrastructure. It's the thing that puts LLMs in front of real users on real channels. Its problems are infrastructure problems: defaults, ops, trust boundaries, supply chain. The reusable parts are the ones that don't depend on those defaults. A minimal gateway, a couple of channel adapters, session and memory semantics you control, and a closed or curated plugin set can get you most of the benefit and a lot less of the pain.

If you're building something that needs "message from WhatsApp or Telegram into an AI agent" — and when platform bets diverge, infrastructure choices matter too — you don't have to adopt OpenClaw whole. Take the architecture as a blueprint. Use the adapters. Harden the rest. That's the playbook.