--- title: "How does OpenClaw work? The technical guide for agencies and developers" date: "2026-08-10T13:07:00" url: "https://www.godaddy.com/resources/skills/how-does-openclaw-work" --- # How does OpenClaw work? The technical guide for agencies and developers Most teams deploy [OpenClaw AI Assistant](https://www.godaddy.com/hosting/vps-hosting/openclaw) in a weekend, but few can explain what happens between a user's message and the agent's reply. This guide closes that gap, layer by layer, from the Gateway that routes every request to the memory system that decides what your agent remembers tomorrow. ## OpenClaw's core architecture: the Gateway model At the center of OpenClaw is a single process called the Gateway. It is the connection point between chat platforms and the AI model that receives messages from each channel, coordinates everything that happens behind the scenes, and sends responses back to users. Related: [What is OpenClaw?](https://www.godaddy.com/resources/skills/what-is-openclaw) ### The hub-and-spoke design explained Think of the Gateway as the hub of a wheel, with each communication channel acting as a spoke. Whether a message comes from Telegram, Discord, WhatsApp, Slack, or another supported platform, it follows the same path: the channel passes the message to the Gateway, the Gateway processes it, and the response is sent back through the same channel. The biggest advantage of this design is that every channel shares the same intelligence. A single OpenClaw instance can serve a Telegram group, a Discord server, and a web application at the same time without maintaining separate AI agents for each one. Without this centralized architecture, every platform would need its own bot, configuration, and logic, making deployments much more difficult to scale. ### How the Gateway separates interface from intelligence Each communication channel is responsible for one thing: delivering messages to and from the Gateway. Everything that requires reasoning happens inside the Gateway, including deciding how to respond, managing memory, calling tools, and communicating with the language model. Keeping the interface separate from the intelligence makes OpenClaw much easier to extend. New channels can be added without changing the agent's underlying logic because every request still passes through the same Gateway before a response is generated. ### The five subsystems inside one process Although OpenClaw runs as a single Gateway process, it includes five subsystems that each serve a specific purpose: 1. **Gateway (daemon)** maintains connections to providers, exposes the WebSocket API, and routes requests throughout the platform. 2. **Clients** include the macOS app, CLI, and web UI, all of which connect to the Gateway over WebSocket to send requests and receive streamed events. 3. **Nodes**run on macOS, iOS, Android, or headless systems with the *role: node*configuration, giving agents access to local capabilities such as screen capture, camera access, and shell commands. 4. **WebChat** provides a static web interface that uses the Gateway's WebSocket API to display chat history and send messages. 5. **Canvas host** is served through the Gateway's HTTP server and allows agents to render interactive HTML, CSS, and JavaScript experiences. This system can be great because it’s straightforward to deploy and manage. However, the tradeoff is that the Gateway is the platform's single point of failure, so every connected client and channel depends on it remaining available. In addition to the five subsystems, three workspace files define OpenClaw agent behavior. AGENTS.md sets up your agents and their routing rules. SOUL.md establishes personality, tone, and standing instructions. MEMORY.md stores long-term facts and preferences. You'll see these referenced throughout this guide as we cover how context gets assembled, how memory persists, and how agents stay separate. We'll go deeper on each in the Memory section below. ## How the agent loop works Every message sent to OpenClaw follows the same sequence of events. Understanding that workflow makes it much easier to troubleshoot issues, understand why an agent responded a certain way, and predict what happens next when tools, memory, or multiple users are involved. ### From message to action: the run sequence Each interaction begins when the agent RPC validates the request, resolves the session, and immediately returns an accepted status along with a unique runId. From there, OpenClaw determines the appropriate model and thinking settings, loads the current skills snapshot, and places the request into a per-session queue. That queue is an important part of the architecture because it processes one request at a time for each session. If multiple messages arrive in quick succession, they wait their turn instead of competing for the same conversation state, helping prevent conditions that can lead to inconsistent responses. When it's time to process the request, OpenClaw assembles the context window, builds the system prompt, and sends everything to the language model. If the model requests a tool, OpenClaw executes it, feeds the result back into the model, and continues the loop until the model produces a final response. If no tool is needed, the reply is returned to the user immediately. ### Context assembly: how OpenClaw builds the brain for each turn Before a request reaches the language model, OpenClaw builds a context window that gives the model everything it needs to respond. It starts with the system prompt, which combines the base prompt, SOUL.md, and any per-run overrides. Next, it loads bootstrap context files such as AGENTS.md, USER.md, and any relevant long-term memory. It then includes descriptions of available skills before adding the most recent conversation history. OpenClaw also enforces the token limits for the selected model. If the context grows too large, less important information is trimmed first so the most relevant instructions and conversation history remain available. The result is a carefully assembled context window that combines current conversation history with long-term memory, giving the agent the information it needs for each new turn. ### The execution loop: how tool calls work When the language model determines that it needs additional information or capabilities, it requests a tool. OpenClaw runs that tool, returns the result to the model, and the model uses the new information to continue generating its response. This cycle can repeat multiple times during a single conversation before a final answer is produced. Tool activity is streamed in real time, so clients receive start, update, and completion events as execution progresses. If a tool encounters an error, OpenClaw returns a structured error to the language model instead of automatically retrying the request. The model then decides how to handle the failure, whether that means explaining the issue, choosing a different approach, or continuing without the tool. ### Session state: how conversations persist across restarts OpenClaw stores several types of data so conversations can continue after a restart. Conversation history is saved in a per-agent SQLite database, long-term memory is preserved in files such as MEMORY.md and daily notes, and workspace configuration files like AGENTS.md and SOUL.md remain available between sessions. Some information exists only while the Gateway is running. Tool calls that are still in progress, responses that have not yet been delivered, and other in-memory states are lost if the process stops unexpectedly. If an agent appears to have forgotten previous conversations after a restart, the cause is often a workspace configuration issue rather than missing memory. In many cases, the Gateway is pointing to a different workspace directory, so verifying that agents.defaults.workspace is consistent is a good place to start. ## Memory: how OpenClaw remembers what matters Not every piece of information should be treated the same. OpenClaw uses separate short-term and long-term memory layers to keep conversations relevant while preserving important information across sessions. Understanding how those layers work makes it easier to fine-tune your agent and troubleshoot situations where it appears to have forgotten something. ### Short-term vs. long-term memory OpenClaw uses two memory layers to balance recent context with information that should persist over time. Both are stored as plain Markdown files, making them easy to inspect, edit, and manage without relying on a hidden database. **Feature** | **Short-term memory** | **Long-term memory** --- | --- | --- **What it is** | Daily notes stored in memory/YYYY-MM-DD.md files | Durable knowledge stored in MEMORY.md **How long it lasts** | Temporary, with today's and yesterday's notes loaded automatically | Persists across sessions until it's updated or removed **What it's good for** | Recent observations, ongoing tasks, and running conversation context | Lasting facts, preferences, and standing decisions Even with both memory layers, every conversation still has a limited context window. As discussions grow longer, older messages may be summarized or removed to stay within the model's token limit. That's where long-term memory search becomes important; it allows OpenClaw to retrieve relevant information without relying on the entire conversation history. ### How the semantic memory search works OpenClaw searches memory based on meaning, not just exact words. For example, a stored note that says a client prefers formal language can still be retrieved when the conversation mentions writing style or tone, even if those exact phrases never appear in the memory entry. To improve accuracy, OpenClaw combines semantic vector search with traditional keyword matching. Semantic search finds related concepts, while keyword search helps surface exact names, IDs, code symbols, and other precise references. OpenAI is the default embedding provider, which requires a valid OpenAI API key because Codex OAuth does not generate embeddings. OpenClaw also supports other language model providers, including Gemini, Voyage, Mistral, local GGUF models, Ollama, LM Studio, and GitHub Copilot through the agents.defaults.memorySearch.provider setting. As your memory store grows, it's a good idea to review and remove outdated entries from time to time. Keeping long-term memory focused on information that still matters helps improve search quality and keeps retrieved context relevant. ### The workspace files that shape agent behavior (AGENTS.md, SOUL.md, MEMORY.md) Let’s take a closer look at the core workspace files used for OpenClaw agents: - **AGENTS.md** defines your agents, the channels they use, the skills they can access, and the operating rules that govern their behavior. - **SOUL.md** establishes the agent's personality, tone, and standing instructions. For example, it might include guidance such as, "You are a customer support assistant for Client X. Always reply in a friendly, professional tone. Never discuss competitors." OpenClaw includes this file with every conversation, with a default limit of 20,000 characters per file and a total bootstrap budget of 60,000 characters. - **MEMORY.md**stores long-term facts, preferences, and decisions that should persist across sessions. The agent gradually distills useful information into this file over time, and you can also update it directly by asking the agent to remember something. One of the benefits of this approach is that changes take effect quickly. Update any of these files, and OpenClaw uses the new instructions on the next conversation turn without requiring a Gateway restart. ## Skills and plugins: extending what OpenClaw can do Skills are what turn OpenClaw from a conversational AI into an assistant that can take action. They let the agent search the web, read spreadsheets, call APIs, automate workflows, or perform virtually any task you build into the platform. ### What a skill actually is (SKILL.md and the plugin system) Every OpenClaw skill is a self-contained package made up of two parts: a SKILL.md file that explains what the skill does and when the language model should use it, and the code that performs the work when the skill is called. OpenClaw automatically discovers available skills at startup, so there's no manual registration process. It searches for skills in the following order, stopping at the first match: 1. /skills 2. /.agents/skills 3. ~/.agents/skills 4. ~/.openclaw/skills 5. Bundled skills 6. skills.load.extraDirs OpenClaw supports several types of skills: - Built-in skills come packaged with OpenClaw and are ready to use. - Managed skills are installed and updated with commands such as openclaw skills install. - Community skills are available through ClawHub and expand OpenClaw with capabilities created by other developers. A typical SKILL.md file might look something like this: ``` # Weather Description: Retrieves current weather conditions and forecasts. Use this skill when the user asks about weather, temperature, or forecasts. Inputs: - location Outputs: - Current conditions - Forecast ``` ### How OpenClaw selects and injects skills per turn Not every agent needs access to every available skill. OpenClaw filters skills using allowlists, giving each agent access only to the tools it needs. The agents.defaults.skills setting creates a shared baseline, while agents.list[].skills defines a replacement list for an individual agent rather than merging with the default. For example, imagine you've installed 12 skills across your workspace. A customer support agent might only receive four skills related to knowledge lookup, ticket management, and CRM access, while a coding agent receives a different set focused on source control, terminal commands, and documentation. Each agent only sees the skills relevant to its role. This approach keeps the context window smaller, helps the language model stay focused, and reduces the chance of an agent using a capability it doesn't need, such as a support assistant invoking a code execution skill. ### Building and auditing your own skills safely Creating a custom skill starts with a SKILL.md file and an entry point that performs the requested work. Once the skill is placed in one of OpenClaw's watched directories, it's automatically discovered and becomes available without any additional configuration. Before enabling a community skill, treat it the same way you would a browser extension. Review what it can access, verify where it sends data, and understand what permissions it requires. Although ClawHub displays scan results for published skills, those scans are helpful indicators rather than complete security guarantees. Before enabling a community skill, ask yourself: - Does it make outbound HTTP requests? - Can it write to or modify files? - Does it access conversation or session data? - Am I installing a specific version instead of always pulling the latest release? - Have I reviewed the changes before upgrading? After deployment, you can run openclaw security audit --deep to identify potentially risky skill configurations and review your environment for security concerns. ## Multi-agent routing and session isolation One OpenClaw deployment can support multiple agents at the same time. Each agent operates independently while sharing the same Gateway, giving agencies a scalable way to organize AI workflows. ### Running separate agents for different channels or clients OpenClaw routes conversations using bindings defined in your configuration. Routing is deterministic, with the most specific match taking priority in this order: 1. Exact peer 2. Guild + roles 3. Guild 4. Account 5. Channel 6. Default agent That flexibility makes it easy to assign dedicated agents to different clients or communication channels. For example: **Channel** | **Agent** | **Client** --- | --- | --- Telegram support | Support Agent | Client X Discord community | Community Agent | Client Y Even though both agents run in the same OpenClaw instance, each maintains its own SOUL.md, MEMORY.md, and conversation history. They can also use different language models, allowing you to assign a lower-cost model to routine support requests while reserving a more capable model for technical conversations or specialized tasks. Because each agent can use a different model, agencies can tailor AI costs for every client. Premium clients can get access to more advanced models, while routine work can run on lower-cost options. Each agent also has its own SOUL.md and MEMORY.md files, so handing off a client is as simple as transferring a workspace folder instead of managing a lengthy migration. ### How sessions create security boundaries Every conversation runs inside its own isolated session, so one user's messages and context remain separate from everyone else's. For direct message environments with multiple users, setting session.dmScope: "per-channel-peer" provides full DM isolation by creating separate sessions for each participant. OpenClaw also enables DM pairing by default. When an unknown sender initiates a conversation, the platform issues a pairing code and waits for approval before processing messages. > **Session isolation is not the same as tenant isolation.** Sessions separate conversation context, but they do not isolate the underlying host environment. If you need complete separation between clients, run a dedicated Gateway for each trust boundary. ### Agent-to-agent communication with session tools OpenClaw agents can collaborate by passing work to one another through session tools. The sessions_spawn tool creates a specialized sub-agent, and sessions_send passes messages between existing agents. These tools are disabled by default and must be explicitly enabled with tools.agentToAgent.enabled: true, along with an allowlist specifying which agents can use them. For example, a general-purpose assistant might receive a code review request and use sessions_spawn to launch a coding specialist. Once the specialist completes the review, the primary agent combines those results into a single response for the user. Because these tools allow agents to create and communicate with other agents, they should be enabled carefully. As a best practice, avoid granting sessions_spawn to agents that process untrusted user input. ## Deployment patterns for production use There's no single "correct" way to deploy OpenClaw in production. The right setup depends on your workload, infrastructure, and availability requirements. Here are four common deployment patterns: ### Local development vs. always-on VPS Running OpenClaw locally is the fastest way to get started. It requires no additional infrastructure, keeps costs low, and is ideal for development, testing, and experimenting with new skills. The tradeoff is that your agent is only available while your computer is running. If your laptop goes to sleep or loses its internet connection, OpenClaw goes offline with it. A virtual private server (VPS) keeps your agent running around the clock. If you're using cloud-hosted language models, a small server with 2 vCPUs and 2–4 GB of RAM is typically enough because the AI processing happens on the model provider's infrastructure. ### SSH tunnels, Tailscale, and remote access options OpenClaw supports several ways to securely access your Gateway remotely. - **SSH tunnel** is a simple option for testing or temporary access. It securely forwards a local port to your remote server. ``` ssh -N -L 18789:127.0.0.1:18789 user@host ``` - **Tailscale** creates a private network between your devices without exposing the Gateway to the public internet. OpenClaw includes native support with: ``` openclaw gateway --tailscale serve ``` - **Cloudflare Tunnel** provides a public URL for a local service, making it a good choice for webhooks, demonstrations, or integrations that require internet access. Before exposing your Gateway outside of localhost, configure authentication by setting: ``` gateway.auth.mode: "token" ``` ### Container deployment (Docker / Fly.io) OpenClaw works well in containerized environments, making deployments more consistent across development and production. For Docker, you can either run scripts/docker/setup.sh from the repository or pull the official container image using ghcr.io/openclaw/openclaw:latest. The most important deployment consideration is your workspace. Always mount your configuration and workspace directories as volumes instead of baking them into the container image. The official Docker Compose configuration handles this automatically through the OPENCLAW_CONFIG_DIR and OPENCLAW_WORKSPACE_DIR environment variables. For Fly.io, the repository includes a ready-to-use fly.toml file. Persistent volumes preserve your workspace across deployments, while automatic scaling helps reduce resource usage when the service is idle. OpenClaw also supports deployment with Podman, Render, Railway, and Kubernetes. ### Choosing the right hardware for your workload Your hardware requirements depend largely on where your language model runs. | **Cloud LLM** | **Local model** --- | --- | --- **Minimum system resources** | 2 vCPUs, 2–4 GB RAM | Depends on the model, plus sufficient system RAM **GPU required** | No | Yes, for most production workloads **Typical latency** | Depends on API response time and network latency | Depends on your hardware and model size **Best for** | Most agency deployments, lower infrastructure costs, and quick setup | Private deployments, data residency requirements, and reducing API costs at scale If you're using cloud providers such as OpenAI or Anthropic, a small VPS is usually all you need because the model inference happens on their infrastructure. Running models locally with tools like Ollama or llama.cpp is more demanding. Hardware requirements vary based on the model, quantization level, and runtime, but larger models generally require substantially more GPU memory than smaller ones. For most agencies, cloud APIs are the most practical starting point because they simplify deployment and minimize infrastructure management. Local models are a stronger option when sensitive data must remain on your own infrastructure or API costs grow large enough to justify dedicated hardware. ## Security model: what you need to understand before deploying Because OpenClaw is self-hosted, you're responsible for securing your deployment. The good news is that the most common risks are well understood and have straightforward mitigations. Before you put an instance into production, there are four areas worth reviewing. ### Tool sandboxing and Docker isolation Tool sandboxing isolates skill execution from the rest of your environment. Instead of running directly alongside the Gateway, skill code runs inside its own container, helping prevent a buggy or malicious skill from accessing the rest of your server. Sandboxing is disabled by default and can be enabled with agents.defaults.sandbox.mode. OpenClaw supports three modes: - off (default) - non-main - all When using the Docker sandbox backend, OpenClaw applies several security controls automatically, including: - No outbound network access (network: "none") - A read-only root filesystem - All Linux capabilities dropped It's important to note that only tool execution is sandboxed. The Gateway itself continues running outside the container. After making configuration changes, run openclaw security audit --deep to identify potentially risky settings before deploying. ### Channel access control and DM pairing By default, OpenClaw protects direct messages with DM pairing. When someone you've never interacted with sends a message, OpenClaw generates a pairing code and waits for approval before processing the conversation. Pairing codes expire after one hour, and each channel can have up to three pending pairing requests at a time. Other direct message policies are also available: - allowlist blocks unknown senders without a pairing handshake. - open allows anyone to message the agent, but it requires explicitly setting "*" and should only be used when absolutely necessary. - disabled turns off direct messaging entirely. For group conversations, enabling requireMention: true helps reduce unwanted interactions by ensuring the agent only responds when directly mentioned. Before connecting OpenClaw to any public-facing channel, run openclaw security audit --deep to verify your configuration. ### Prompt injection risks and how to mitigate them Prompt injection occurs when hidden instructions inside external content attempt to influence an AI agent's behavior. > Any skill that reads web pages, emails, documents, or other outside content can become an injection surface. OpenClaw removes common chat template special tokens from external content, which helps prevent one class of prompt injection attacks. That protection is useful, but it isn't a substitute for good security practices. To reduce your risk: 1. Keep direct messages in pairing or allowlist mode instead of exposing always-on bots to public conversations. 2. Use a dedicated read-only agent to summarize untrusted content instead of giving it access to high-risk tools. 3. Disable web_search, web_fetch, and browser for tool-enabled agents unless those capabilities are genuinely required. 4. Enable tools.exec.strictInlineEval when using interpreter allowlists. ### Known vulnerabilities and how to stay patched Keeping OpenClaw up to date is one of the simplest ways to improve security. Monitor the project's [GitHub Security Advisories](https://urldefense.com/v3/__https:/github.com/openclaw/openclaw/security__;!!Hj18uoVe_Lnx!sO9ZUYwqqfUemAIG9WhL0H_7MoYgy9nlc4I9MJsOyPuRuxFMTSCBJrLrVcKck5CWqr5Sdzj90JcM3ENmdTgyWRA$) for newly disclosed vulnerabilities and recommended updates. When a new release becomes available: 1. Pin deployments to a specific release tag instead of using latest or main, then review the changelog before upgrading. 2. Test the update in a development environment before deploying it to production. 3. Run openclaw doctor after major upgrades to verify that your deployment is healthy and correctly configured. ## Choosing and connecting an LLM One of OpenClaw's biggest strengths is its flexibility. It works with most major LLM providers, as well as models running on your own hardware. ### How model routing and failover work OpenClaw lets you define both a primary model and one or more fallback models in openclaw.json. If the primary model becomes unavailable, OpenClaw automatically works through its failover strategy to keep conversations running. ``` {   agents: {     defaults: {       model: {         primary: "anthropic/claude-sonnet-4-6",         fallbacks: [           "openai/gpt-4o",           "ollama/llama3"         ]       }     }   } } ``` When a request fails, OpenClaw first tries any additional API key profiles you've configured for the same provider. If those are unavailable, it moves to the next model in the fallback chain. Users receive a notification when the session switches to a fallback model and another when the primary model becomes available again. One exception is manual model selection. If someone explicitly chooses a model with the /model command, OpenClaw treats that as a fixed choice and won't silently switch to a fallback if the selected model fails. ### Cloud models vs. local models: trade-offs for agencies Both cloud-hosted and locally hosted models have advantages, and the right choice depends on your deployment. **Cloud models** | **Local models** --- | --- Easy to deploy with minimal infrastructure | Keep prompts and data on your own hardware Access to the latest flagship models | No ongoing per-token API costs Pay only for what you use | Require more powerful hardware to run efficiently Prompts and responses leave your server | Performance varies based on your available hardware For most agency deployments, cloud models are the easiest place to start. They provide strong performance with very little setup, and they're a practical fit unless your clients have strict data residency or compliance requirements. Local models become more attractive when keeping data on your own infrastructure is a priority or when API costs begin to outweigh the investment in dedicated hardware. OpenClaw supports more than 40 providers and runtimes, including OpenRouter, Groq, Mistral, DeepSeek, Ollama, and many others. One important consideration for tool-enabled agents is model quality. Smaller, lower-cost models are generally more susceptible to prompt injection and poor tool selection, so they're not the best choice for workflows that rely heavily on external tools or automation. ### API cost management and budget controls Managing AI costs starts with choosing the right model for the job. Routine tasks often work well with smaller, lower-cost models, while complex reasoning, planning, or technical work may justify using a flagship model. To help control usage: - Set a max_tokens limit for each request to prevent unnecessarily long responses. - Cache repeated context whenever possible instead of sending the same information with every request. - Use lower-cost models for sub-agents by configuring agents.defaults.subagents.model, reserving premium models for the primary agent when needed. - Configure spending limits through your model provider, such as OpenAI usage limits or Anthropic spend caps. OpenClaw doesn't include built-in budget tracking, so provider-level controls are your primary safeguard. - Review provider dashboards regularly, especially when running multiple client agents, since usage can grow quickly across concurrent deployments. ## Build smarter OpenClaw deployments OpenClaw gives developers and agencies plenty of flexibility, but getting the most from it starts with understanding how the pieces fit together. Once you know how the Gateway, memory, skills, sessions, and model routing work together, you'll be in a much better position to build reliable AI agents, troubleshoot issues, and scale deployments as your needs grow. ## Frequently asked questions about how OpenClaw works
What is the OpenClaw gateway, and why does it matter? The OpenClaw Gateway is the central process that connects chat channels to the language model. It manages memory, tool execution, session state, and message routing, so you don't need a separate process for every channel or client. That centralized architecture allows a single OpenClaw deployment to support multiple channels and clients at the same time.
Can multiple people use the same OpenClaw instance? Yes. OpenClaw supports multiple users across multiple channels simultaneously, with each conversation running in its own isolated session. Combined with multi-agent routing, a single deployment can serve different clients while keeping their personalities, memories, tools, and conversation histories separate.
How does OpenClaw handle failures or tool errors? When a tool fails, OpenClaw returns a structured error to the language model instead of letting the request fail silently. The language model uses that information to decide how to respond, and OpenClaw doesn't automatically retry the failed tool call. If you're building custom skills, return structured error results instead of unhandled exceptions so the agent can respond gracefully.
Is the OpenClaw plugin ecosystem safe to use? It can be, but you should evaluate community skills carefully before installing them. Community skills execute code on your server, so treat them the same way you would a browser extension by reviewing what they can access, pinning them to a specific version, and choosing projects with a solid reputation. ClawHub displays scan results, but those scans aren't a complete security guarantee, so it's also worth checking GitHub Discussions for reported issues before enabling a new skill.
How does OpenClaw differ from a standard LLM API integration? A standard LLM API integration gives you a stateless model, leaving you to build and manage memory, tools, sessions, routing, and channel integrations yourself. OpenClaw provides those capabilities out of the box in a single self-hosted platform. Instead of building the infrastructure around the model, you can focus on configuring agents, creating skills, and tailoring the experience for your users.