OpenClaw: Gateway, Memory, Tools, and Sandbox Boundaries

An AI agent that works on our behalf needs more than a language model: it must receive messages across channels, remember context, call tools, manage credentials, and decide where code runs. OpenClaw addresses these needs with a user-controlled, Gateway-centric architecture. This article covers its architecture, trust boundaries, and key security trade-offs.

A private server connected to an entry point, memory, tools, and a protective shield represents self-hosted AI architecture

What OpenClaw manages around the model

OpenClaw is an open-source project for running AI assistants or agents on user-controlled hardware and infrastructure. Its focus is orchestration rather than creating a new language model, connecting Channel for receiving orders, session and memory, model provider, tools, plugins, credentials and execution environment to work as one system

OpenClaw receives messages from Telegram, Slack, Discord, WhatsApp, iMessage, or its own UI and routes them to an appropriate agent. It then calls models and tools, stores task state, and returns results through the original channel. The LLM provides reasoning and generates responses within that process.

Unlike ordinary AI chat apps, OpenClaw lets users control agent runtime and state. The project says state, memory, and credentials reside on user hardware, while prompts go to chosen model providers and chat platforms. This does not mean no data leaves the device: cloud models and external chats still receive necessary data under the configuration.

Created by Peter Steinberger and the community, the project is now maintained under the OpenClaw Foundation and MIT-licensed. It suits people wanting to study or adapt an agent stack more deeply than a ready-made SaaS product allows.

Mental model: Split OpenClaw into 6 layers.

Understanding OpenClaw will be easier if the system is separated into six layers. Many words in a document have different functions and should not be used interchangeably.

Separating layers helps locate faults. An incorrect model choice differs from a tool running on the host without a sandbox, or a channel accepting strangers’ messages.

The Gateway is the architectural core

OpenClaw has a long-running Gateway daemon owning connected messaging surfaces. Its architecture documentation describes control clients such as CLI, Web UI, and native apps connecting through WebSocket. Device nodes also use WebSocket but declare their role as node and declare their own capabilities

Gateway defaults to binding loopback at 127.0.0.1:18789 This reflects the important idea that the control plane should not be unnecessarily exposed to a wide network. If you need to enter remotely The document recommends using private networking such as VPN/Tailscale or an SSH tunnel rather than opening the port directly to the public.

Within the connection protocol are request/response and server-pushed events such as agent state, chat, presence, health, heartbeat, and cron, allowing multiple UIs or clients to see the same state without having to create separate agent runtimes per client.

Modern agents do more than receive prompts and return text: they handle streaming, background work, tool execution, approvals, device events, and multisession state. A central Gateway gives these components clear places in the architecture.

One instruction's path: from text to side effect

Suppose a user sends, “Summarize the latest email and create a to-do list.” The conceptual workflow would roughly follow this sequence.

  1. Inbound message: channel receives the message and sends it to Gateway with sender information, chat room, and required metadata.
  2. Access policy: Gateway checks DM policy, pairing, allowlist, sender ownership, and channel limitations.
  3. Session routing: The system selects the session or agent that this message should enter and retrieves the relevant state.
  4. Context assembly: The agent runtime includes system instructions, workspace context, memory, transcript and allowed tool descriptions.
  5. Model inference: The prompt is sent to the specified provider/model such as OpenAI, Anthropic, Gemini or local model.
  6. Tool call: When a model requests a tool, the runtime checks policy before executing actions such as reading files, calling APIs, or running commands
  7. Execution boundary: The action may run on the Gateway host, node, or sandbox depending on the configuration.
  8. Result loop: The tool result is sent back to the model for further thought until the final response is obtained.
  9. Delivery: The results are returned through the original channel and the required state is recorded. session/memory

The runtime interprets tool calls and permits or denies actions under policy. Security therefore depends on the model and the surrounding orchestration code.

Model provider separate from agent runtime: change the "brain" without dismantling the system

OpenClaw references models using the format provider/model and supports many providers, including cloud APIs, subscription-style integrations, and local runtimes. Model selection becomes configuration instead of one provider embedded in the core.

This distinction is important in the agent world because “model” and “agent harness” are not the same thing. A model is an inference endpoint, while a harness is a runtime that manages threads, compaction, tool events, or specific agent behaviors. OpenClaw supports plugins for model providers, and there is also an agent harness plugin for cases where an external runtime needs to own the agent circuitry.

Administrators can select models by task—one for coding, another for general work—and set agent-specific fallbacks or policies without replacing all channels, memory, or the Gateway.

“Multiple provider support” does not mean all providers behave identically. Token limits, reasoning modes, caching, tool protocols, rate limits, and billing still differ. Test actual behavior when switching models, especially in workflows heavily dependent on tool calling.

What are the differences between Tools, Skills and Plugins?

These three terms are central to OpenClaw and are often confused

A simple rule: if an agent has tools but lacks a reliable workflow, add a Skill. If the system lacks the capability entirely, such as a new provider or channel, use a Plugin.

The strength of the plugin-oriented architecture is that the core does not have to expand indefinitely. The trade-off is increased supply-chain risk because native plugins run as real code. OpenClaw's documentation clearly states that native plugins are not automatically sandboxed and that you should use allowlists, pin versions, and check package origins before installing them.

Sessions and Memory: How to make the agent remember it without stuffing everything into the context window

LLM has a limited context window, so users' entire transcripts cannot be returned to the model every turn. OpenClaw separates "session history" from "memory" and has compaction to keep active contexts in a manageable size.

Main-session history can span days without a default daily reset. Compaction reduces context size, while daily memory notes retain useful information. When /new or /reset The system can retrieve relevant memory to prime a new session

The key idea is history is not equal to memory and memory index is not equal to canonical state Newer OpenClaw documentation distinguishes rebuildable indexes from sessions/transcripts that must be preserved. Do not randomly delete the main database to fix memory search: it may also hold other durable agent state.

For systems with multiple agents or sessions, session-state awareness also tells one session that its understanding of another session's state may be outdated. This seemingly small detail matters when agents collaborate or a human intervenes in a workflow.

Nodes enable OpenClaw to expand from “chat” to device agent.

A node is a companion device that connects to the Gateway and declares its own command surface. Examples of capabilities documented include camera, device, notifications, system, and on some platforms screen or computer-control capability.

The architectural point of view is that the Gateway does not need to run on a device that has all the hardware capabilities. The server itself can be the brain. while your phone or Mac acts as a node that Gateway launches with permission.

Nodes immediately increase risk: an agent that reads chat and one that controls devices have very different blast radii. Device pairing, node policy, and exec approvals are important security boundaries, not setup steps to click through casually.

Security model that you need to understand first: One Gateway is one trust domain.

The most important aspect of OpenClaw is not the number of plugins or models, but trust model Security documentation says a Gateway is designed for one trusted-operator boundary, not a hostile multitenant boundary for mutually untrusted groups

The practical meaning is If multiple people can send messages to the same agent and that agent has access to powerful tools, they are sharing the same agent's delegated authority. Even if the system has sender-scoped controls or session routing, this should not be interpreted as tenant-level isolation.

For mutually untrusted users or organizations, separate Gateways and credentials, and preferably OS users or hosts. This is a stronger boundary than many ACLs in one Gateway.

Prompt injection is still a problem even if the authentication is correct.

OpenClaw group messages pass through group policy, allowlists, and mention gating before replies, or are dropped or retained as context
OpenClaw's original diagram separates message acceptance from mention-triggered replies. Store for context can ingest data without replying, so this does not prove prompt-injection protection or tenant isolation. Source: OpenClaw Docs, MIT Converted SVG to WebP without changing labels. Click to read the original.

Agent systems have risks that traditional chatbots don't: Messages that the model reads may try to influence it to misuse the tool. Such as text in emails, documents, web pages, or forwarded messages. This problem is called prompt injection.

Authentication answers “Who can call the Gateway?” but not “Can every piece of context be trusted?” OpenClaw documentation warns that requester-scoped controls do not sanitize quoted text, shared-room history, fetched content, attachments, or tool results entering a prompt.

Use defense in depth: restrict channels reaching agents, limit tools, sandbox where appropriate, require approval for host commands, and separate trust domains for differently trusted users. System prompts alone do not sufficiently prevent prompt injection when agents can make real changes.

Sandbox: Reduced blast radius, but not automatically enabled for everything.

OpenClaw supports sandbox backends that move some tool execution off the main host, but its documentation explicitly says sandboxing Off by default and the Gateway process remains on the host even with sandboxing enabled

The benefit of the sandbox is that it limits filesystem, process, and network access to the tasks the model executes if the agent does something unintended. Damage is limited in a narrower environment, but a sandbox is not a perfect security boundary. And it doesn't solve every type of problem, such as plugins running in-process or credentials that the operator places in a location that the agent can read.

Another layer is exec approvals It uses policy + allowlist + user approval to control the commands that will run on the real host. This concept is suitable for workflows that need to occasionally touch the host because we can let the agent run automatically in the sandbox but require human approval when crossing the boundary to the real machine.

Secrets: How to store credentials without them becoming prompt content

A classic agent mistake is putting an API key in a configuration file or environment accessible to tools and hoping the model will leave it alone. OpenClaw therefore provides SecretRef to reference credentials from env, file, exec providers, or a shared store without embedding plaintext values throughout the configuration.

The documentation also describes protected secrets and egress-time substitution, aiming to let agents authenticate to designated destinations without seeing secret values directly. However, SecretRef does not automatically prevent a compromised host or host-exec agent from reading files. Filesystem restrictions remain the responsibility of the sandbox and OS permissions.

Here are some general lessons that apply to all agent platforms: Secret management and execution isolation are different problems. Just one solution is not enough.

How to audit OpenClaw’s security settings

Use this command to audit OpenClaw’s settings, including inbound messages, network exposure, tool and file permissions, plugin policy, sandbox settings, and command approvals.

openclaw security audit

Interestingly, many problems arise not from bugs but from configuration drift such as configuring a Docker sandbox while sandbox mode remains off, enabling powerful tools in a chat anyone can message, or exposing a Gateway to the network without appropriate authentication

Default settings may favor convenience for a personal agent on a personal computer. Moving to a server, enabling remote access, connecting multiple channels, or receiving others' messages immediately changes the threat model. Audit again whenever you add a new surface.

Before relying on a security audit to establish boundaries, inspect effective configuration with openclaw sandbox explain and existing environments with openclaw sandbox list, as documented in Sandboxing. Check the actual agent and session. An existing container does not mean every command runs inside it; elevated and node paths need separate permission review.

Deployment patterns: which approach suits whom?

The same architecture can be deployed in several ways, with very different risk profiles

OpenClaw makes agent infrastructure more visible and controllable. Administrators still need to understand and maintain those components.

Performance and stability: A good agent must handle long conversations without breaking

As of 2 October 2026 OpenClaw documentation shows release v2026.9.7 which has improved responsiveness of long chats, update/rollback protection, memory use, model picker and workflow after restart, including added support for OpenAI Agents API and Sign in with ChatGPT in Beta

These details reflect a real problem with agent platforms: with longer sessions, more background work, and more tool events, the bottleneck isn't just inference, but database I/O, transcript rendering, compaction, queuing, plugin lifecycle, and state recovery after process restart.

Therefore, evaluating an agent framework should not only be a benchmark of the model, but should also look at operational characteristics such as recovery, observability, migrations, release processes, and the ability to diagnose the system when state mismatches occur.

What OpenClaw does well and the trade-offs involved

Checklist before putting OpenClaw into practice

Hypothetical example: Two groups of people who are not supposed to read each other's files need to use Assistant. Don't start by creating two sessions and assume they have separate permissions. List the Gateway, OS users, credentials, and folders that each group has access to. Then use a test file that doesn't contain any actual data to check that one group can't read another group's files. Including checking tools running on the host. If there are still credentials or shared host rights, that point must be recorded as an undivided scope. Do not use the results of two chat rooms giving different answers as evidence instead of checking permissions.

Viewing OpenClaw as infrastructure rather than an app raises these questions before production use

Summary: OpenClaw's value lies in making the agent stack visible and controllable

OpenClaw combines Gateway routing, sessions, memory, model abstraction, extensions, and execution controls in one architecture. Assistant capabilities also depend on how those parts work together.

For developers and teams building real agents, switching providers, adding plugins, connecting multiple channels, and separating sandbox from host execution offer significant benefits. They also require serious work on trust boundaries, secret management, and operational security.

OpenClaw provides components for a user-controlled agent system. Safety, privacy, and reliability depend on its configuration, model, plugins, channels, and infrastructure. Evaluate the assembled system before actual use.

Sources

OpenClaw documentation and releases reviewed October 2, 2026. Features, defaults, commands, and architecture may vary by version. Check documentation for your installed version before configuring critical systems.