How to Run OpenClaw Locally (Full Setup Guide)

Introduction

OpenClaw is the most powerful open-source framework for building autonomous AI agents that can browse the web, execute code, manipulate files, and interact with external APIs. However, the gap between reading the documentation and actually having a working agent on your machine is where most developers get stuck. Misconfigured environment variables, incompatible runtime versions, and subtle YAML indentation errors can consume hours of debugging before you ever see your first agent response.

This guide eliminates that friction entirely. By the end of this tutorial, you will have a fully functional OpenClaw instance running on your localhost, configured with persistent memory, tool access, and a clean architecture for scaling to production. You will understand the underlying process model, master the configuration schema, and know exactly how to diagnose the three most common failure modes that plague local installations.

Running OpenClaw locally is not just a development convenience—it is a security and cost imperative. Cloud-hosted agents incur per-token costs during iterative debugging, and sending half-baked prompts to remote infrastructure risks data leakage. Local execution gives you complete control over your code, your data, and your iteration speed. Whether you are building a personal research assistant, a code-generation pipeline, or a customer-support bot, mastering local OpenClaw execution is the foundational skill you need.

Architecture / Core Concepts

Before writing a single command, you must understand how OpenClaw operates under the hood. This mental model will save you hours when things go wrong.

The Process Model

OpenClaw runs as a client-server architecture even in local mode. The core components are:

1. The OpenClaw Engine (Daemon): A long-running Python process that manages agent state, tool execution, and the event loop. It listens on a configurable port (default 127.0.0.1:18789) for API requests.
2. The CLI Client: A lightweight command-line interface that sends commands to the engine via REST API. This separation means you can run the engine on one machine and control it from another.
3. The Agent Runtime: Each agent session spawns an isolated runtime environment with its own working directory, environment variables, and tool permissions.
4. The Tool Registry: A plugin system that dynamically loads tool definitions (web search, file I/O, code execution) based on your configuration.

Configuration Hierarchy

OpenClaw uses a three-tier configuration system:

• Global Config (~/.openclaw/config.yaml): Applies to all projects and users on the machine.
• Project Config (./openclaw.yaml in your project root): Overrides global settings for a specific codebase.
• Runtime Flags (CLI arguments): Highest precedence, used for ephemeral overrides during testing.

The configuration merge order is: defaults < global < project < CLI flags. Understanding this hierarchy is critical because a stray setting in your global config can silently override your project-level settings.

The Tool Execution Sandbox

When OpenClaw executes a tool (like running a shell command or writing a file), it does so inside a sandboxed subprocess. The sandbox enforces:

• Filesystem isolation: Tools can only access paths whitelisted in your config.
• Network restrictions: Outbound HTTP requests require explicit tool permissions.
• Resource limits: CPU time and memory caps prevent runaway agent loops.

This sandbox is your first line of defense against prompt-injection attacks where a malicious webpage tries to trick your agent into executing arbitrary commands.

Prerequisites & Environment Setup

System Requirements

OpenClaw requires a Unix-like environment. Windows users should use WSL2 (Windows Subsystem for Linux) with Ubuntu 22.04 or later.

Component	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	4 GB	8 GB
Disk	2 GB free	10 GB free
Python	3.10	3.12
Node.js	18.x	20.x LTS

Step 1: Install Core Dependencies

Open your terminal and run the following commands to install the base toolchain:

# Update package manager
sudo apt update && sudo apt upgrade -y

# Install Python 3.12 and pip
sudo apt install -y python3.12 python3.12-venv python3-pip

# Install Node.js 20 LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Install Git and build tools
sudo apt install -y git build-essential curl

# Verify installations
python3.12 --version  # Should output Python 3.12.x
node --version        # Should output v20.x.x
git --version         # Should output git version 2.x

Step 2: Install OpenClaw

OpenClaw is distributed as a Python package. We strongly recommend installing it inside a dedicated virtual environment to avoid conflicts with system packages:

# Create a virtual environment
mkdir -p ~/openclaw-env
cd ~/openclaw-env
python3.12 -m venv .venv

# Activate the environment
source .venv/bin/activate

# Install OpenClaw
pip install --upgrade openclaw

# Verify installation
openclaw --version

If the openclaw command is not found after installation, your virtual environment's bin directory is not on your PATH. Run export PATH="$HOME/openclaw-env/.venv/bin:$PATH" and add this line to your ~/.bashrc for persistence.

Step 3: Initialize the Configuration Directory

# Create the global config directory
mkdir -p ~/.openclaw

# Generate a default configuration file
openclaw init

The init command creates a starter config.yaml in ~/.openclaw/. We will replace this with a production-grade configuration in the next section.

Step-by-Step Implementation

Step 1: Create Your Project Structure

# Create project directory
mkdir -p ~/my-openclaw-agent
cd ~/my-openclaw-agent

# Create the directory structure
mkdir -p agents tools memory logs data

# Initialize a git repository
git init

Your project structure should look like this:

my-openclaw-agent/
├── agents/          # Agent definitions and personas
├── tools/           # Custom tool plugins
├── memory/          # Persistent memory stores
├── logs/            # Runtime logs
├── data/            # Working data for agents
├── openclaw.yaml    # Project configuration
└── .env             # Environment variables (gitignored)

Step 2: Configure Global Settings

Create ~/.openclaw/config.yaml with the following production-ready configuration:

# Global OpenClaw Configuration
server:
  host: "127.0.0.1"        # Bind to localhost only
  port: 18789              # Default API port
  workers: 4               # Number of concurrent agent workers
  request_timeout: 300     # Seconds before timing out a request

logging:
  level: "INFO"            # DEBUG, INFO, WARNING, ERROR
  file: "~/.openclaw/logs/openclaw.log"
  max_bytes: 10485760      # 10 MB per log file
  backup_count: 5          # Keep 5 rotated log files

security:
  api_key_required: true   # Require API key for all requests
  sandbox_enabled: true    # Enable tool execution sandbox
  network_isolation: true  # Block outbound network by default
  max_memory_mb: 2048      # Per-agent memory limit
  max_cpu_seconds: 60      # Per-tool CPU time limit

memory:
  backend: "sqlite"        # Persistent memory backend
  path: "~/.openclaw/memory.db"
  ttl_days: 30             # Memory entries expire after 30 days

Step 3: Configure Project Settings

Create openclaw.yaml in your project root:

# Project-specific OpenClaw Configuration
project:
  name: "my-openclaw-agent"
  version: "0.1.0"

agent:
  default_model: "gpt-4o"           # Or your preferred LLM
  temperature: 0.7
  max_tokens: 4096
  system_prompt: |
    You are a helpful AI assistant running locally.
    You have access to the following tools:
    - web_search: Search the web for current information
    - file_read: Read files from the workspace
    - file_write: Write files to the workspace
    - code_execute: Execute Python code in a sandbox
    - memory_store: Store information in long-term memory
    - memory_recall: Retrieve information from long-term memory

tools:
  enabled:
    - web_search
    - file_read
    - file_write
    - code_execute
    - memory_store
    - memory_recall
  
  web_search:
    provider: "duckduckgo"    # No API key required
    max_results: 5
  
  file_read:
    allowed_paths:
      - "./data"              # Only allow reading from data directory
  
  file_write:
    allowed_paths:
      - "./data"              # Only allow writing to data directory
  
  code_execute:
    language: "python3"
    timeout_seconds: 30

memory:
  namespace: "my-agent"       # Isolate memory from other projects
  auto_compact: true          # Automatically summarize old memories

Step 4: Set Up Environment Variables

Create a .env file in your project root:

# LLM Provider API Keys
OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here

# OpenClaw Server Configuration
OPENCLAW_API_KEY=your-local-api-key
OPENCLAW_HOST=127.0.0.1
OPENCLAW_PORT=18789

# Optional: Set your preferred model
OPENCLAW_DEFAULT_MODEL=gpt-4o

Security Note: Never commit this file to git. Add .env to your .gitignore immediately:

echo ".env" >> .gitignore
echo "logs/" >> .gitignore
echo "memory/" >> .gitignore

Step 5: Start the OpenClaw Engine

# Load environment variables
set -a
source .env
set +a

# Start the engine in the background
openclaw serve --config ./openclaw.yaml --daemon

# Verify the engine is running
openclaw status

You should see output similar to:

OpenClaw Engine Status:
  Status: RUNNING
  Host: 127.0.0.1
  Port: 18789
  Workers: 4
  Uptime: 0:00:03

Step 6: Test Your First Agent Interaction

Create a simple test script test_agent.py:

import openclaw

# Initialize the client
client = openclaw.Client(
    host="127.0.0.1",
    port=18789,
    api_key="your-local-api-key"
)

# Create a new agent session
session = client.create_session(
    agent_name="test-agent",
    project="my-openclaw-agent"
)

# Send a simple message
response = session.chat(
    "Hello! Please introduce yourself and list the tools you have available."
)

print(f"Agent Response: {response.content}")

# Test memory functionality
session.chat("Remember that my favorite color is blue.")
recall_response = session.chat("What is my favorite color?")
print(f"Memory Recall: {recall_response.content}")

# Close the session
session.close()

Run the test:

python test_agent.py

If everything is configured correctly, you should see the agent introduce itself and correctly recall your favorite color from memory.

Step 7: Test File Operations

Create a test for file operations test_file_ops.py:

import openclaw

client = openclaw.Client(
    host="127.0.0.1",
    port=18789,
    api_key="your-local-api-key"
)

session = client.create_session(agent_name="file-test-agent")

# Ask the agent to write a file
write_response = session.chat(
    "Please write a Python script to data/hello.py that prints 'Hello from OpenClaw!'"
)
print(f"Write Response: {write_response.content}")

# Ask the agent to read the file back
read_response = session.chat(
    "Please read the file data/hello.py and show me its contents."
)
print(f"Read Response: {read_response.content}")

# Verify the file exists on disk
import os
if os.path.exists("data/hello.py"):
    print("✓ File was successfully written to disk")
else:
    print("✗ File was not created")

session.close()

Step 8: Run the Agent in Interactive Mode

For development and testing, you can run OpenClaw in interactive REPL mode:

openclaw run --config ./openclaw.yaml

This opens an interactive prompt where you can chat with your agent directly:

OpenClaw Interactive Mode
Type 'exit' to quit, 'help' for commands

You: What is the current date and time?
Agent: The current date is September 4, 2026, and the time is 14:32:07 UTC.

You: Please create a markdown file called README.md in the data directory with a brief description of this project.
Agent: I've created the file data/README.md with a project description.

You: exit
Goodbye!

Production Best Practices & Security Hardening

1. Never Run as Root

Always run OpenClaw under a dedicated, unprivileged user account:

# Create a dedicated user
sudo useradd -r -m -s /bin/bash openclaw-user

# Grant access to necessary directories
sudo chown -R openclaw-user:openclaw-user ~/.openclaw
sudo chown -R openclaw-user:openclaw-user ~/my-openclaw-agent

# Run as that user
sudo -u openclaw-user openclaw serve --config ./openclaw.yaml

2. Implement Strict Filesystem Permissions

Your sandbox configuration should follow the principle of least privilege:

tools:
  file_read:
    allowed_paths:
      - "./data"              # Read-only data directory
    denied_paths:
      - "./data/secrets"      # Never allow reading secrets
  
  file_write:
    allowed_paths:
      - "./data/output"       # Only write to output directory
    denied_paths:
      - "./data/input"        # Never overwrite input files

3. Rotate API Keys Regularly

Implement a key rotation policy:

# Generate a new API key
openssl rand -base64 32

# Update the key in your environment
export OPENCLAW_API_KEY="new-generated-key"

# Restart the engine to apply the new key
openclaw restart

4. Enable Comprehensive Audit Logging

logging:
  level: "INFO"
  audit_log: true
  audit_events:
    - "agent.created"
    - "agent.message"
    - "tool.executed"
    - "file.read"
    - "file.written"
    - "memory.stored"
    - "memory.recalled"

5. Use Environment-Specific Configurations

Create separate configuration files for development and production:

# Development config
openclaw serve --config openclaw.dev.yaml

# Production config
openclaw serve --config openclaw.prod.yaml

The production config should disable debug tools and enforce stricter limits:

# openclaw.prod.yaml
security:
  api_key_required: true
  sandbox_enabled: true
  network_isolation: true
  max_memory_mb: 1024
  max_cpu_seconds: 30

tools:
  enabled:
    - file_read
    - file_write
    - memory_store
    - memory_recall
  # Note: web_search and code_execute are disabled in production

6. Deploy to a VPS for 24/7 Availability

While local development is essential, production agents need to run continuously. For that, we recommend deploying to a cloud VPS. Start with Vultr Cloud VPS (Get $35 Credit) → offers high-performance compute instances starting at $2.50/month, perfect for running OpenClaw agents 24/7. Their NVMe SSD storage and 99.99% uptime SLA ensure your agents are always available.

Troubleshooting & Common Pitfalls

Case 1: "Connection Refused" Error

Error Output:

Error: Failed to connect to OpenClaw engine at 127.0.0.1:18789
Connection refused

Root Cause: The OpenClaw engine is not running, or it is bound to a different interface.

Solution:

# Check if the engine is running
ps aux | grep openclaw

# If not running, start it
openclaw serve --config ./openclaw.yaml

# Check what port the engine is listening on
netstat -tulpn | grep 18789

# If the engine is bound to a different host, update your client
# For example, if it's bound to 0.0.0.0, use:
# client = openclaw.Client(host="0.0.0.0", port=18789)

Case 2: "Module Not Found" Error

Error Output:

ModuleNotFoundError: No module named 'openclaw.tools.web_search'

Root Cause: The tool plugin is not installed, or the tool name is misspelled in your configuration.

Solution:

# List all available tools
openclaw tools list

# Install missing tool plugins
pip install openclaw[tools-web-search]

# Verify the tool is now available
openclaw tools list | grep web_search

# Check your configuration for typos
cat openclaw.yaml | grep -A 5 "tools:"

Case 3: "Permission Denied" When Writing Files

Error Output:

Error: Permission denied: Cannot write to /home/user/my-openclaw-agent/data/output.txt
Tool execution failed: file_write

Root Cause: The file path is not in the allowed_paths list in your configuration, or the sandbox user does not have write permissions.

Solution:

# Check your allowed paths
grep -A 5 "file_write" openclaw.yaml

# Add the correct path to your configuration
# tools:
#   file_write:
#     allowed_paths:
#       - "./data/output"

# Check filesystem permissions
ls -la data/
# If needed, fix permissions
chmod 755 data/
chown -R $(whoami) data/

# Restart the engine to apply configuration changes
openclaw restart

Case 4: Agent Memory Not Persisting

Error Output:

Agent: I don't have any memory of our previous conversation.

Root Cause: The memory backend is not configured correctly, or the memory namespace is different between sessions.

Solution:

# Verify memory configuration
grep -A 5 "memory:" openclaw.yaml

# Check if the memory database exists
ls -la ~/.openclaw/memory.db

# If the database doesn't exist, the memory backend may not be initialized
# Run the memory initialization command
openclaw memory init

# Ensure you're using the same namespace across sessions
# In your client code:
# session = client.create_session(agent_name="test-agent", namespace="my-agent")

Frequently Asked Questions

What are the minimum system requirements to run OpenClaw locally?

OpenClaw requires a 64-bit Unix-like operating system (Linux, macOS, or WSL2 on Windows). The minimum hardware requirements are 2 CPU cores, 4 GB of RAM, and 2 GB of free disk space. For comfortable development with multiple concurrent agents, we recommend 4 CPU cores, 8 GB of RAM, and 10 GB of free disk space. You also need Python 3.10 or higher and Node.js 18 or higher installed on your system.

How do I secure my local OpenClaw instance?

To secure your local OpenClaw instance, you should: (1) Bind the server to 127.0.0.1 only, never 0.0.0.0, to prevent external access; (2) Enable API key authentication by setting api_key_required: true in your security configuration; (3) Use the sandbox mode to restrict file system access to whitelisted directories; (4) Enable network isolation to block unauthorized outbound requests; and (5) Never run OpenClaw as the root user—always use a dedicated unprivileged user account.

Can I run multiple OpenClaw agents simultaneously on one machine?

Yes, OpenClaw supports running multiple agents concurrently. By default, the engine spawns 4 worker processes, each capable of handling a separate agent session. You can increase this number by modifying the workers setting in your server configuration. Each agent session runs in an isolated runtime environment with its own working directory and tool permissions, so there is no risk of cross-agent interference.

How do I update OpenClaw to the latest version?

To update OpenClaw, activate your virtual environment and run pip install --upgrade openclaw. After updating, restart the OpenClaw engine with openclaw restart to ensure the new version is loaded. We recommend checking the official changelog before updating, as major version updates may introduce breaking changes to configuration files or API endpoints.

What should I do if my agent cannot access the internet?

If your agent cannot access the internet, first check your network isolation settings in the security configuration. If network_isolation: true, the agent cannot make outbound requests by default. You have two options: (1) Set network_isolation: false to allow all outbound traffic, or (2) Add specific domains to an allowlist in your tool configuration. For security reasons, we recommend the allowlist approach rather than disabling network isolation entirely.

Related Guides & Resources

• OpenClaw Docker Installation Tutorial — Learn how to containerize your OpenClaw setup for reproducible deployments.
• OpenClaw Configuration Guide (Complete Walkthrough) — Deep dive into every configuration option available in OpenClaw.
• Best OpenClaw Tools for Beginners — Discover the essential tools and plugins to extend your agent's capabilities.
• OpenClaw CLI Guide: Commands and Examples — Master the command-line interface for managing your OpenClaw instances.

For visual configuration assistance, use the OpenClaw Config Generator to create and validate your YAML configuration files without syntax errors.

When you're ready to move beyond local development and deploy your agents to a production server, Start with Vultr Cloud VPS (Get $35 Credit) → for reliable, low-latency hosting that keeps your agents running 24/7.