Skip to main content
Guides

OpenClaw Complete Guide | Self-Hosted AI Agents, Setup & Security

March 27, 2026•BlockframeLabs Content Team

OpenClaw: The Complete Guide to Self-Hosted AI Agents in 2026

OpenClaw started as Clawdbot in late 2025, briefly became Moltbot, and then launched as OpenClaw in early 2026. The project exploded to over 246,000 GitHub stars, putting it in the same league as React and Linux in community interest. OpenClaw is a self-hosted, multi-channel gateway that lets you connect cloud AI models like Anthropic Claude, OpenAI GPT-4, and Google Gemini to your favorite messaging apps. You can keep one AI brain that remembers conversations across Telegram, WhatsApp, Slack, Discord, IRC, Signal, and iMessage. Everything runs on your own hardware, so your data stays private.

This guide covers everything from hardware requirements to production security. You'll learn how to install OpenClaw on a VPS, Mac Mini, Windows PC, and handheld devices. We'll walk through connecting a Telegram bot, fixing common errors, hardening your deployment, and using skills from ClawHub. Whether you want a personal assistant on your phone or an enterprise automation platform, this is your starting point.

Why Self-Hosted AI Matters

In 2026, most people interact with AI through web apps like ChatGPT or Claude.ai. Those services are convenient, but they come with trade-offs:

  • Your prompts and responses are stored on the provider's servers.
  • You rely on the provider's uptime and rate limits.
  • Data residency and compliance are out of your control.
  • Integration with your internal tools requires tricky workarounds.

OpenClaw flips the script. You own the infrastructure. The AI "brain" lives in the cloud, but the gateway that orchestrates it runs on your machine. You decide where memory is stored, which channels are allowed, and which skills are installed. This setup is especially valuable for businesses that handle sensitive information, developers who want to automate workflows, and privacy-conscious individuals who want an AI that respects their data.

Self-hosting also means you can experiment freely. Need to run a browser automation skill that scrapes a website? You can do it without worrying about violating a provider's terms of service. Want to connect your AI to your personal calendar, notes, or smart home devices? All possible because the agent runs on your network.

A common misconception is that self-hosting is too technical for average users. OpenClaw's QuickStart mode and automated installer make the process straightforward. If you can run a command in a terminal, you can set this up.

Who This Guide Is For

  • Hobbyists who want a personal AI that works across multiple chat apps.
  • Small businesses that need a cost-effective, private automation solution.
  • System administrators looking to deploy AI agents for their team.
  • Developers building AI-powered tools and need a local orchestrator.
  • Anyone frustrated with cloud AI limitations and ready to take control.

Table of Contents

OpenClaw is a Node.js-based gateway that sits between cloud AI providers and the communication channels you use every day. It runs on your machine or server, storing configuration and memory locally. You can think of it as a unified control plane that gives a single AI consistent memory across multiple apps.

Key Features

  • Local-first: Configuration, memory, and credentials live in ~/.openclaw/ as JSON5 and Markdown. No mandatory cloud dependency.
  • Multi-channel orchestration: One agent works across Telegram, Discord, WhatsApp, Slack, IRC, Signal, and iMessage.
  • Privacy by design: Your data never leaves your infrastructure.
  • Skill extensibility: Over 13,000 community-built skills via ClawHub, plus native Model Context Protocol (MCP) support for tools like Figma, Jira, and Spotify.
  • Continuous availability: Designed for home servers or always-on VPS deployments.

The system is developer-ready but also accessible to non-technical users through an interactive onboarding wizard.

Hardware Requirements

OpenClaw itself is lightweight, but running AI models and skills consumes memory. RAM is the biggest bottleneck.

Minimum vs Recommended Specs

<!-- Unsupported block type: table -->

If your server has less than 2 GB RAM, create a swap file. Many budget VPS instances need this to avoid crashes during module compilation.

Deployment on a VPS (Ubuntu)

A VPS provides 24/7 uptime and good security isolation. Unlike a laptop that goes to sleep, a VPS keeps your agent running all the time so it can respond to messages and run scheduled tasks.

1. Prepare the Server

After creating your VPS (Ubuntu 22.04 or 24.04), create a non-root user. Do not run the gateway as root.

bash
sudo apt update &amp;&amp; sudo apt upgrade -y
adduser openclawops
usermod -aG sudo openclawops

Disable password SSH login. Edit the sshd_config file and set PasswordAuthentication to no, then restart SSH.

2. Install OpenClaw

Run the official installer:

bash
curl -fsSL https://openclaw.ai/install.sh | bash

The installer will ask you to choose QuickStart mode. This sets safe defaults and skips advanced options. When prompted, enter your AI provider API key (Anthropic, OpenAI, or Google).

3. Secure the Gateway

During configuration, bind the gateway to 127.0.0.1 only. Binding to 0.0.0.0 exposes your Control UI and API to the internet.

If you need remote access, either set up an SSH tunnel:

bash
ssh -L 18789:localhost:18789 user@vps-ip

or install Tailscale for a private network.

Mac Mini and macOS Setup

Apple Silicon Macs (M1–M4) are popular for OpenClaw because they handle concurrent AI tasks efficiently, stay cool, and run quietly.

Install Prerequisites

Open Terminal and run:

bash
xcode-select --install
/bin/bash -c &quot;$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)&quot;
brew install node

On Apple Silicon, add Homebrew to your PATH by following the instructions printed at the end of the Homebrew installer.

Onboard and Install as a Service

bash
openclaw onboard --install-daemon

This creates a launchd service that starts OpenClaw automatically and restarts it after reboots.

macOS will ask for Accessibility, Notifications, and Automation permissions. Approve these so the agent can interact with other apps.

Windows and WSL2 Installation

Windows users have two options: native PowerShell installation or WSL2. WSL2 is more stable and compatible with most skills.

Option A: Native PowerShell

Install Node.js from the official website and ensure "Tools for Native Modules" is checked. Then run:

powershell
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
iwr -useb https://openclaw.ps1 | iex

Option B: WSL2 (Recommended)

Enable WSL and install Ubuntu:

powershell
wsl --install

In the Ubuntu terminal:

bash
sudo apt update
curl -fsSL https://openclaw.ai/install.sh | bash

Enable systemd in WSL by adding to /etc/wsl.conf:

plain text
[boot]
systemd=true

Then restart WSL from PowerShell: wsl --shutdown.

Windows-Specific Fixes

  • Add ~/.openclaw/ and Node.js to your antivirus exclusions.
  • Open Windows Firewall port 18789 for the Control UI.
  • If you see driver stuttering on devices like MSI Claw, update or reinstall the Intel AI Boost driver.

Handheld Devices (MSI Claw)

Telegram is the easiest way to chat with your agent from your phone. It uses long polling, which means the bot checks periodically for new messages. This avoids the need for complex firewall rules or port forwarding. Even if your server sits behind NAT, Telegram works as long as outbound connections are allowed.

This section walks you through every step, from creating a bot to troubleshooting common pitfalls.

Step 1: Create a Bot with BotFather

BotFather is the official bot that creates other bots. It's run by Telegram and lives at @BotFather. The process is straightforward but easy to mess up if you skip a step.

  • Open Telegram (either the mobile app or desktop client).
  • In the search bar, type @BotFather. Make sure the account has a blue checkmark; it's verified.
  • Start a chat and press the Start button, or type /start.
  • To create a new bot, type /newbot and send.
  • BotFather will ask for a name. This is the display name that appears in conversations, e.g., My Assistant Bot.
  • Next, choose a username. It must be unique across all Telegram bots and must end with the word bot. For example, myassistantbot or blocksmith_bot. If the name is taken, BotFather will tell you to pick another.
  • After you pick a valid username, BotFather replies with a message containing the HTTP API Token. It looks like 123456789:AAHabcdefGhIJKlmnoPQRstuVWXyz1234567890. Copy this token immediately; you won't see it again unless you regenerate.

Security note: Treat this token like a password. Anyone who has it can control your bot. Do not commit it to version control or share it publicly. Insecurely stored tokens are a common reason for bot hijacking.

bash
# Example of what NOT to do:
echo &quot;BOT_TOKEN=123:ABC&quot; &gt;&gt; .env &amp;&amp; git commit -am &quot;add token&quot;

Instead, store it in a password manager or use an environment variable with restricted file permissions.

Step 2: Connect the Bot to OpenClaw

Now you'll tell OpenClaw about your new bot. Run this command in the same terminal where you installed OpenClaw:

bash
openclaw channels add --channel telegram --token &quot;YOUR_BOT_TOKEN&quot;

Replace YOUR_BOT_TOKEN with the exact token you copied. If your token contains special characters, wrap it in quotes to avoid shell interpretation.

You should see output:

plain text
Added Telegram channel. Bot username: @yourusername_bot

If you get an error like "Invalid token", double-check you copied the full token and that there are no extra spaces or line breaks.

Step 3: Pair Your Personal Telegram Account

By default, the bot will ignore messages from everyone. Only users who have been explicitly paired can interact. This prevents strangers from using your agent.

Pairing process:

  • In Telegram, search for your bot using its username (e.g., @myassistantbot).
  • Start a chat with the bot (press Start or send /start).
  • The bot will reply with a Pairing Code, something like X7D9-M2K1-PL4Q. It may be in a code block or plain text.
  • Switch to your terminal where OpenClaw is running and execute:
bash
openclaw pairing approve telegram X7D9-M2K1-PL4Q

(Replace the code with what you received.)

If successful, you'll see:

plain text
Approved telegram sender: 123456789 (Your Name)

That number is your Telegram user ID. OpenClaw now knows that this ID is allowed to chat with the agent.

  • Go back to Telegram and send a test message like "Hello". Your agent should respond within a few seconds.

Important: The pairing code expires after a few minutes for security. If you miss it, send /start again to get a fresh code.

Alternatively, from the terminal, you can send the telegram pairing message and the openclaw agent will pair it up for you

Understanding the Pairing Model

OpenClaw uses a "zero trust" approach. Channels start in a locked state. Each channel type has its own pairing mechanism:

  • Telegram: BotFather token plus per-user approval.
  • Discord: OAuth2 login plus optional role allowlist.
  • WhatsApp: Business API number and QR scanning.
  • Slack: Bot token and workspace install.

The pairing approve command tells the gateway "this user is trusted". Without it, the agent will respond with "Access Not Configured".

Step 4: Test Your Installation

Once paired, send a few messages to verify:

  • Simple question like "What is 2+2?"
  • Command to test a skill: for example, "search for latest OpenClaw news" if the web search skill is installed.
  • Multi-turn conversation: "My name is Alice" followed by "What is my name?"

The agent should remember your name across messages because it maintains session memory.

If you get no response, check the gateway logs:

bash
openclaw gateway logs -f   # if supported
# or
journalctl -u openclaw -f

Look for errors such as:

  • 401 Unauthorized – your AI provider key is wrong or expired.
  • Pairing Required – you haven't approved your user yet.
  • LLM Request Timed Out – your internet is slow or the provider is down.

Step 5: Configure for Production

The QuickStart wizard sets safe defaults, but you may want to tweak things for better reliability and lower cost.

Recommended post‑install tweaks:

  • Increase timeoutSeconds to 600 to avoid timeouts on complex queries.
  • Set sandbox.mode = "non-main" if you plan to allow untrusted users.
  • Define gateway.auth.token to protect your Control UI.
  • Create a dedicated non-root system user and ensure permissions on ~/.openclaw/ are locked down.

You can make these changes via the CLI or by editing openclaw.json directly. After any config change, restart the gateway:

bash
openclaw gateway restart

Going Beyond Telegram

Once your Telegram bot works, you can add other channels. The process is similar:

  • Discord: Create an application in Discord Developer Portal, add a bot, copy the token, then run openclaw channels add --channel discord --token <TOKEN>. Authorize the bot in your server and pair your Discord account.
  • Slack: Create an app in api.slack.com, add bot token scopes, install to workspace, then openclaw channels add --channel slack --token xoxb-....
  • WhatsApp: Requires a Meta Business account and approved template messages. This is more involved; see the dedicated WhatsApp guide in the docs.

Each channel has its own pairing flow, but the principles are the same: add channel token, then approve your user.

Advanced: Multiple Bots on One Gateway

You can run several independent bots by creating separate projects. Each project has its own openclaw.json and can connect to different AI providers or use different personalities.

Example:

bash
mkdir ~/projects/work-bot
cd ~/projects/work-bot
openclaw init --quickstart
# customize openclaw.json
openclaw gateway start --project .

Now this bot uses the project config instead of the global default.

Common Pitfalls and How to Avoid Them

  • Forgot to restart after config change? Always restart the gateway after editing openclaw.json or environment variables.
  • Using the wrong model format? Remember: "model": { "primary": "anthropic/claude-3-5-sonnet" }. Not a string.
  • Gateway not starting? Run openclaw doctor to diagnose. Common issues: port already in use, missing gateway token, invalid JSON5 syntax.
  • No messages from bot? Ensure you paired your user. Check bot permissions in Telegram (bot must be able to read messages).
  • Unexpected restarts? Look for OOM kills; add swap or upgrade RAM.

Glossary

The configuration file lives in ~/.openclaw/openclaw.json (JSON5 format). This is where you set your AI model, channel tokens, and security policies.

Override Mechanism

Settings can be defined at two levels:

  • Global: ~/.config/openclaw/openclaw.json
  • Project: ./openclaw.json (in a specific folder)

Project settings take precedence. This lets you maintain different agent personalities per project.

Common Settings

json
{
  agents: {
    defaults: {
      model: { primary: &quot;anthropic/claude-3-5-sonnet&quot; },
      timeoutSeconds: 300
    }
  },
  gateway: {
    auth: { token: &quot;your-32-char-token-here&quot; }
  },
  channels: {
    telegram: { dmPolicy: &quot;pairing&quot; }
  },
  session: {
    dmScope: &quot;per-channel-peer&quot;
  },
  sandbox: {
    mode: &quot;non-main&quot;
  }
}

Model Formatting Must-Know

Wrong: "model": "openai/gpt-4o"

Right: "model": { "primary": "openai/gpt-4o" }

The gateway schema requires an object. This mistake causes silent failures.

Skills, ClawHub, and MCP

Skills extend OpenClaw with real-world actions like web search, browser control, file operations, and more.

Installing Skills

bash
openclaw skills install &lt;skill-name&gt;

Caution with Community Skills

ClawHub hosts over 13,000 skills, but audits suggest around 20% may be malicious. Only install skills from "Awesome OpenClaw" curated lists or official OpenClaw publishers.

Model Context Protocol (MCP)

OpenClaw supports MCP, a standard that lets AI models interact with external tools. With an MCP Adapter, your agent can integrate with thousands of tool servers for Figma, Jira, Spotify, and more.

Security Hardening

An AI agent with terminal access is a high-risk system. Adopt a zero-trust model.

Sandbox Untrusted Channels

Set sandbox.mode = "non-main" so sessions from Discord, WhatsApp, and other public channels run inside a Docker container with restricted host access.

Isolate Multi-User Memory

Set session.dmScope = "per-channel-peer" to ensure each user has a private memory. Without this, users in a shared workspace can see each other's conversations.

Bind Gateway to Loopback

Never bind your gateway to 0.0.0.0. Always use 127.0.0.1 and access via SSH tunnel or Tailscale.

Require Pairing

Use channels.telegram.dmPolicy: "pairing" to force new users to enter a code before they can interact.

Performance Tuning

Even with adequate hardware, you may need to tweak OpenClaw for optimal responsiveness under load. Performance tuning focuses on three areas: resource allocation, network throughput, and skill execution efficiency.

Increase Timeout for Complex Tasks

Long-running skills like browser automation or data analysis can exceed the default 300-second timeout. Set a higher value per user or globally:

bash
openclaw config set agents.defaults.timeoutSeconds 600

You can also override per project in openclaw.json:

json
{
  agents: {
    defaults: {
      timeoutSeconds: 600
    }
  }
}

Control Concurrent Skill Execution

If the agent becomes sluggish when multiple users interact, limit the number of concurrent skill runs:

bash
openclaw config set skills.maxConcurrent 2

Optimize Model Token Usage

Large models like Claude 3.5 Sonnet have high token costs and latency. For short tasks, configure a secondary, cheaper model fallback:

json
{
  agents: {
    defaults: {
      model: {
        primary: &quot;anthropic/claude-3-5-sonnet&quot;,
        fallback: &quot;openai/gpt-4o-mini&quot;
      }
    }
  }
}

The gateway will use the fallback if the primary fails or times out.

Tune Memory Retention

OpenClaw keeps recent messages in active memory and writes older context to Markdown files. The window size affects both quality and cost. Adjust with:

bash
openclaw config set session.memoryWindow 20

A smaller window reduces token usage but may cause the agent to forget earlier details.

Network Bonding for High-Throughput

If you run a high-traffic bot, consider bonding multiple network interfaces or using a VPS with a 1 Gbps+ port. Also enable TCP keepalive to prevent idle disconnections:

bash
openclaw config set gateway.tcpKeepalive true

Profile Skills with the Built-in Monitor

The CLI includes a simple profiler to see which skills take the most time:

bash
openclaw skills profile

Use this to identify slow dependencies and consider replacing them with lighter alternatives.

Monitoring & Observability

Once your agent is live, you need visibility into its health, usage, and costs. OpenClaw emits structured logs and metrics that you can integrate with your existing monitoring stack.

Using openclaw doctor for Health Checks

openclaw doctor verifies:

  • Node.js version
  • Port availability (18789)
  • Provider API connectivity
  • Configuration syntax
  • Gateway token validity

The --fix flag attempts automatic repairs, such as regenerating a missing gateway token.

Accessing Gateway Status

bash
openclaw gateway status

Shows process state, bound ports, and active connections. Useful for quick checks.

Log Files

Logs are written to:

  • Systemd (Linux/macOS service): journalctl -u openclaw -f
  • Standalone process: ~/.openclaw/logs/gateway.log

The log format is JSON lines, suitable for parsing with tools like jq or Elastic Agent.

Exporting Metrics

Enable Prometheus metrics by adding to openclaw.json:

json
{
  metrics: {
    enabled: true,
    port: 9090
  }
}

Then scrape with Prometheus and visualize in Grafana. Key metrics:

  • openclaw_requests_total by channel and outcome
  • openclaw_tokens_used_total
  • openclaw_skill_duration_seconds
  • openclaw_memory_size_bytes

Cost Tracking with Token Counters

OpenClaw logs token usage per request. To get daily spend estimates:

bash
grep &#039;&quot;tokens&quot;&#039; ~/.openclaw/logs/gateway.log | jq -r &#039;.tokens&#039; | awk &#039;{sum+=$1} END {print sum}&#039;

Multiply by your provider's per‑million‑token rates.

Alerting

Set up alerts for:

  • Gateway down (port not listening)
  • Error rate > 5%
  • Token spend exceeding budget
  • Memory usage > 80%

You can use simple cron health checks:

bash
* * * * * curl -s http://localhost:18789/health || echo &quot;OpenClaw down&quot; | mail -s &quot;Alert&quot; [email protected]

Backup & Disaster Recovery

Your ~/.openclaw/ directory contains all configuration, memory, and credentials. Losing it means starting over. Regular backups are essential.

What to Back Up

  • openclaw.json – gateway configuration
  • projects/ – project-specific overrides
  • logs/ – request history for auditing
  • memories/ – long-term memory files
  • skills/ – installed skill data (some skills store state locally)

Automated Daily Backups

On Linux/macOS with systemd timers or cron:

bash
0 2 * * * tar -czf /backup/openclaw-$(date +%F).tar.gz -C ~/.openclaw .

Store backups offsite (e.g., Backblaze B2, Wasabi) and encrypt them with gpg.

Restore Procedure

  • Stop the gateway: openclaw gateway stop
  • Extract the archive to ~/.openclaw/
  • Restart: openclaw gateway start

Verify by running openclaw doctor.

Testing Backups

Periodically test restoration on a spare machine to ensure the backup is valid and the process works.

Handling Provider Lockout

If your AI provider API key is accidentally leaked or used beyond limits:

  • Revoke the key immediately in the provider console.
  • Generate a new key and update openclaw.json (or re-run onboarding).
  • Notify your team if you share the agent.

A good backup does not include API keys; instead store them in a password manager and reference via environment variables when possible.

Advanced Configuration Examples

Here are practical configurations for common scenarios.

Per-Project Personas

You can give each project a distinct personality and settings:

plain text
~/projects/work/
  openclaw.json  { model: &quot;anthropic/claude-3-5-sonnet&quot;, tone: &quot;professional&quot;, budget: &quot;high&quot; }

~/projects/personal/
  openclaw.json  { model: &quot;openai/gpt-4o-mini&quot;, tone: &quot;casual&quot;, budget: &quot;low&quot; }

When you run OpenClaw inside ~/projects/work/, those settings override global defaults.

Channel-Specific Rate Limiting

Prevent a noisy Telegram channel from exhausting your API budget:

json
{
  channels: {
    telegram: {
      rateLimit: {
        maxRequests: 100,
        perSeconds: 60
      }
    }
  }
}

Custom Skill Allowlist

Restrict skill execution to an allowlist:

json
{
  skills: {
    allowed: [
      &quot;openclaw-web-search&quot;,
      &quot;openclaw-notes&quot;,
      &quot;mcp-figma&quot;
    ]
  }
}

Any attempt to run a non-listed skill fails.

Multi-Provider Fallback Chain

json
{
  agents: {
    defaults: {
      model: {
        primary: { provider: &quot;anthropic&quot;, model: &quot;claude-3-5-sonnet&quot; },
        fallback: [
          { provider: &quot;openai&quot;, model: &quot;gpt-4o&quot; },
          { provider: &quot;google&quot;, model: &quot;gemini-2.0-flash&quot; }
        ]
      }
    }
  }
}

The agent tries providers in order until one succeeds.

Cost Optimization

Running an AI agent can get expensive if you don't manage token usage.

Set Monthly Budgets

bash
openclaw budget set --monthly 50  # USD

The gateway will reject requests once the estimated spend reaches the limit.

Choose the Right Model per Task

Use cheaper models for casual chat and reserve top‑tier models for complex reasoning. You can automate this with skill wrappers:

json
{
  skills: {
    webSearch: { model: &quot;openai/gpt-4o-mini&quot; },
    codeReview: { model: &quot;anthropic/claude-3-5-sonnet&quot; }
  }
}

Cache Frequent Results

Enable caching for read‑only skills like weather or stock-price:

json
{
  skills: {
    cache: {
      ttlSeconds: 300
    }
  }
}

Repeated queries within 5 minutes return the cached response, saving API calls.

Limit Output Tokens

Cap the maximum completion length:

bash
openclaw config set agents.defaults.maxTokens 1024

This prevents runaway generations.

Monitor and Adjust

Review your token logs weekly. If you consistently hit your budget, raise it or reduce usage. If spend is low, you might safely increase limits for better quality.

Real-World Use Cases

What can you actually do with OpenClaw? Here are real examples from the community.

Personal Life Automation

  • Morning briefing: The agent reads your calendar, weather, and news, then sends a summary to Telegram each morning.
  • Expense tracking: Forward receipts to a private channel; the agent extracts amounts and writes to a Google Sheet via a skill.
  • Habit reminders: The agent nudges you to stand, hydrate, or meditate based on your schedule.

Small Business Operations

  • Customer support triage: Connect a Telegram bot to your help desk. The agent categorizes inquiries and drafts replies.
  • Social media posting: Schedule tweets and LinkedIn updates by sending a message to the agent.
  • Inventory alerts: Monitor e‑commerce platforms and notify you when stock is low.

Development Workflow

  • Code review assistant: Point the agent at a pull request; it runs linters, checks tests, and leaves comments.
  • Documentation generator: Feed it a database schema; it writes Markdown docs.
  • Deployment notifier: After a CI/CD pipeline completes, the agent posts a summary to the team Slack.

Research and Learning

  • Paper summarizer: Send a PDF to the agent (via a skill); it returns an executive summary with key points.
  • Language practice: Chat with the agent in a foreign language, and have it correct your grammar.
  • Quiz generator: Provide a topic, and the agent creates a set of flashcards.

These use cases only scratch the surface. The flexibility of OpenClaw means you can adapt it to almost any text‑based or API‑driven workflow.

Upgrading and Maintenance

OpenClaw evolves quickly. A regular maintenance routine keeps your system secure and feature‑rich.

Update Checklist

  • Read the release notes for the new version. Look for breaking changes.
  • Back up ~/.openclaw/.
  • Run npm update -g openclaw@latest.
  • Run openclaw config migrate if the schema changed.
  • Run openclaw doctor to ensure everything is healthy.
  • If using Docker, pull the new image and restart the container.

Scheduled Maintenance Window

Pick a weekly or monthly time to perform updates, ideally when usage is low. Notify your team if downtime is expected.

Deprecation Notices

Follow the OpenClaw blog and GitHub releases to stay aware of upcoming deprecations. The warning period is usually at least one minor version.

Cleaning Up Old Skills

List installed skills and remove unused ones:

bash
openclaw skills list
openclaw skills uninstall &lt;skill&gt;

Old skills may have vulnerabilities; keep only what you need.

Performance Reviews

Every quarter, review your metrics:

  • Are you hitting rate limits?
  • Is memory usage growing?
  • Are any skills consistently slow?

Adjust configurations based on data.

Memory and Token Management

Effective memory and token management is crucial for maintaining performance, controlling costs, and ensuring your OpenClaw deployment remains responsive as usage grows. This section covers persistence strategies, token limiting, local search, and caching techniques.

Persistence Options

OpenClaw stores data in two primary forms: structured logs and long-term memory files.

  • Markdown-based logs: Daily logs in logs/YYYY-MM-DD.md capture conversation history and system events. These are human-readable and easy to back up.
  • Long-term memory: The memory/ directory holds notes that persist across sessions. Use these for enduring knowledge, user preferences, and project context.

For larger deployments, consider augmenting with a vector database:

  • PostgreSQL with pgvector: Store embeddings of memory entries to enable fast semantic search across thousands of notes. Integrate via a skill or custom plugin that indexes new entries and performs similarity queries.

Token Usage Controls

AI API costs are directly tied to token consumption. OpenClaw provides mechanisms to keep usage in check:

  • Per‑user limits: Set a maximum number of tokens each user can consume per day or per conversation. This prevents any single user from exhausting your budget.
  • Global budget caps: Define a monthly spend limit. Once reached, the gateway will reject new requests until the next period.
  • Automatic compaction: When token usage approaches configured thresholds, OpenClaw can automatically prune old context or compress memories to stay within limits.

Configure limits via openclaw.json or the CLI:

json
{
  agents: {
    defaults: {
      maxTokensPerDay: 1000000,
      budgetUsdPerMonth: 50
    }
  },
  memory: {
    autoCompact: true,
    compactThreshold: 0.8
  }
}

Local Search with qmd

Searching through logs and memory files doesn't require an external database. The qmd skill provides efficient local search using BM25, vector embeddings, and reranking—all without leaving your machine.

  • BM25 for keyword matches.
  • Vector for semantic similarity.
  • Rerank to combine both signals.

Install and configure:

bash
openclaw skills install qmd
openclaw config set qmd.enabled true

Then query:

plain text
search my notes about PostgreSQL setup

The skill returns ranked results from your local markdown store.

Caching Strategies

Repeated queries to the LLM can be expensive and slow. Caching common responses reduces cost and improves latency.

  • Provider-level cache: Some AI providers (e.g., OpenAI) offer response caching. Enable it in your provider dashboard and set cache: true in the model configuration.
  • Skill result cache: For deterministic skills like weather or currency conversion, cache the output for a short period (e.g., 5 minutes). Configure per skill:
json
{
  skills: {
    weather: { cacheTtlSeconds: 300 },
    cryptoPrice: { cacheTtlSeconds: 60 }
  }
}
  • Custom cache layer: You can implement a simple in-memory cache or use Redis for distributed setups. Wrap skill execution in a cache check to avoid duplicate work.

Best Practices

  • regularly archive old logs to cold storage to keep the active set small.
  • monitor token usage trends and adjust limits accordingly.
  • use local search for quick lookups; reserve LLM queries for complex reasoning.
  • enable provider caching for idempotent operations.

By proactively managing memory and tokens, you maintain a fast, cost-effective, and scalable OpenClaw deployment.

Troubleshooting Guide

The openclaw doctor command is your first line of defense. Run:

bash
openclaw doctor --fix

It checks Node version, port binding, provider health, and config syntax, and attempts automatic repairs.

Common Errors

<!-- Unsupported block type: table -->

Backup Before Updates

Always back up ~/.openclaw/ before updating:

bash
npm update -g openclaw@latest

Major updates can break configuration.

FAQ

Q: Can I run OpenClaw without a cloud AI provider? A: Not yet. OpenClaw needs a remote LLM. However, you can pair it with a locally hosted model like llama.cpp; just provide the provider URL.

Q: Is Windows Subsystem for Linux (WSL) fully supported? A: Yes. WSL2 with systemd enabled works well. Avoid WSL1.

Q: How many users can share a single gateway? A: There’s no hard limit, but RAM and API rate limits will be your constraints. For teams of 20+, consider a larger VPS and per-user rate limiting.

Q: What happens when the gateway crashes? A: If you used --install-daemon or systemd, it will restart automatically. Check logs with openclaw gateway status and journalctl -u openclaw.

Q: Can I move my installation to a new server? A: Yes. Back up ~/.openclaw/, transfer to the new machine, restore, and ensure the same Node.js version is installed.

Q: Are my messages stored in plain text? A: Yes, memory files are plain Markdown. Encrypt the disk or use filesystem-level encryption if needed.

Q: How do I completely remove OpenClaw? A: Delete the ~/.openclaw/ directory and uninstall the global npm package: npm uninstall -g openclaw.

Related Articles

Guides

5 Essential AI Prompting Techniques Every Beginner Should Master

A practical guide to the core prompting methods from Google's AI Essentials course — covering tool selection, context surfacing, zero-shot vs few-shot, chain-of-thought, and AI limitations.

AI News

Kimi K3: Moonshot AI Launches New Frontier Model - Complete Technical Analysis

Deep technical analysis of Moonshot AI's Kimi K3 release: 2.8T parameters, native multimodal architecture, 1M token context window. Covers architecture, competitive landscape, deployment patterns, and why long context changes AI system design.

AI News

Qwen 3.6 27B: the local AI model that finally makes sense

Alibaba's Qwen 3.6 27B is the first local AI model that handles real coding tasks on consumer hardware. Here is how to run it and why it matters.