The 2026 Openclaw Setup Guide:

Install, Configure, and Hardened for Security

This Openclaw tutorial shows you how to set up your own messaging gateway, so your AI agents can chat on WhatsApp, Telegram, Discord, and even email.

You’ll find everything you need — system requirements, how to install it, onboarding steps, setting up models and skills, building multi-agent workflows, and ways to keep things safe with sandboxing and security tweaks.

Just follow the steps and use the command examples. You’ll have your own personal assistant or automated agent running, and you’ll stay in control of your data and your server.

Table of Contents

• What Openclaw is and why you might use it

• Who this Openclaw tutorial is for

• Quick checklist before you begin

• Install Openclaw (step-by-step)

• Key onboarding decisions explained

• Workspace and agent memory basics

• Channels: connecting WhatsApp, Discord, Telegram, and email

• Skills: how Openclaw teaches tools to agents

• Building a personal assistant with Openclaw

• Multi-agent setups and switching agents

• Sandboxing: how to isolate agents safely

• Security hardening checklist

• Common mistakes and how to avoid them

• Practical example: create a Gmail check skill and integrate with WhatsApp

• Maintenance, monitoring, and troubleshooting

• Migration, backup, and multi-device sync

• When to run Openclaw on a VPS vs on a personal machine

• Useful commands reference

• Troubleshooting tips

• Checklist to go from zero to a safe, useful agent

• FAQ

• Summary and next steps

What Openclaw is and why you might use it

Openclaw is a self-hosted agent runtime and messaging gateway. It maintains persistent connections to chat platforms, runs configurable AI agents, and executes workflows on your machine or inside isolated sandboxes.

Use cases include:

• Personal assistant: triage email, manage calendar, reply to messages, trigger scripts.

• Automations: watch a repository, open pull requests, or run periodic checks and summaries.

• Multi-channel bots: connect the same agent to WhatsApp, Discord, Telegram, and web UI channels.

• Research and customization: author skills that teach the agent how to interact with specific tools or services.

The value of Openclaw is control: you host credentials, agent configuration, persistent memory, and tool integrations on infrastructure you own.

That also means you must treat security and permissions as first-class concerns.

Who this Openclaw tutorial is for

This guide assumes you have:

• Comfort using a command line interface on macOS, Linux, or a Linux-based VPS.

• Basic familiarity with large language models and API keys (Anthropic, Google, etc.).

• Willingness to self-host services and manage Docker if you plan to sandbox agents.

Quick checklist before you begin

• Node.js version 22 or later installed (Node 25 recommended).

• Docker installed and running if you plan to use sandboxes.

• An API key for the AI provider you plan to use (Anthropic, Google, or another supported model).

• A plan for channel access (which phone numbers, Discord server, or Telegram accounts will interact with an agent).

Install Openclaw (step-by-step)

The simplest global install uses npm. Run the following from a terminal:

npm install -g openclaw

After installing, run the onboarding wizard to configure paths, keys, and the gateway. Two onboarding options are commonly used:

• Manual onboarding: interactive setup that writes your workspace and config files.

• Install gateway as a daemon: register the gateway as a background service (systemd on Linux, launchd on macOS) so it starts on boot.

Example onboarding command with daemon install:

openclaw onboard --install-daemon

The wizard will ask where to store the workspace directory (default is ~/.openclaw), which model provider you want to use, whether to enable remote access, and which optional skills or integrations to install.

Key onboarding decisions explained

Local vs remote gateway binding

During onboarding choose the gateway bind option that matches your needs:

• Loopback: only accepts connections from the same machine. More secure for single-machine setups.

• LAN: exposes the gateway to devices on your local network.

• Tail or remote exposure: allows access from remote devices but requires careful security controls.

Choosing a model provider

Openclaw supports multiple model providers. For production-like reliability, pick a larger model (stronger resistance to prompt-injection).

For trial usage, a free option with request limits might be acceptable. When possible, choose a model with strong safety behavior and the features you need.

Gateway port and tokens

The gateway listens on a default port (for example 18789). A gateway token is generated to authenticate the TUI and control UI. Save it securely and avoid exposing it publicly.

Workspace and agent memory basics

Openclaw stores agent definitions, session memory, identity files, and skills as Markdown files and configuration JSON inside the workspace directory. Important concepts:

• Identity files: agent name, personality, time zone, and user context live as human-readable Markdown files. These drive the system prompt.

• Session memory: short-term and long-term memories are persisted to files. Heartbeat.md describes periodic tasks an agent should run.

• Bootstrap files: files used only on first run, then deleted to avoid re-executing one-time instructions.

• Config JSON: contains runtime parameters, channel lists, and plugin toggles. Edit via CLI where possible, not by manual file edits.

Because workspace files are plain text, you can back up or version them in Git. A Git-backed workspace provides portable, reproducible agent configuration across machines.

Channels: connecting WhatsApp, Discord, Telegram, and email

Openclaw exposes channels for bidirectional messaging. Channels commonly used:

• WhatsApp — pair via a QR scan using the channels login command.

• Discord — add a bot application, copy the bot token and guild/channel IDs, and configure the plugin to join a server.

• Telegram — supply the bot token from BotFather and configure allowed chat IDs.

• Email — skills can use SMTP or API-based sending with credentials stored in environment variables or secure config entries.

WhatsApp pairing example

To enable WhatsApp, first enable the plugin and restart the gateway, then scan the QR code:

openclaw plugins enable whatsapp
openclaw gateway restart
openclaw channels login

Scan the QR code with your phone as prompted. For production use, consider a dedicated phone number for the bot to avoid confusion between your personal messages and bot automation.

Discord bot example

Steps to add Openclaw to a Discord server:

1. Create a Discord application and bot at the Discord Developer Portal.

2. Enable the message content intent and generate a bot token. Keep it secret.

3. Invite the bot to a private server with appropriate scopes and permissions.

4. Configure the token, guild ID, and channel IDs in Openclaw using CLI configuration.

For security, run the bot inside a private or invite-only server. Treat the bot as a privileged client: it may have access to your host if allowed.

Skills: how Openclaw teaches tools to agents

Skills are the core extension mechanism. Each skill lives in a folder and contains a skill.md with YAML front matter plus instructions describing tool usage, arguments, and triggers. Skills can:

• Teach the agent specific API semantics (e.g., Google Workspace, Obsidian, Apple Notes).

• Expose functions the agent can call during reasoning or execution phases.

• Be installed globally so multiple agents share them, or kept per-agent for isolation.

Installing and auditing third-party skills

Clawhub is a registry of third-party skills. Install with a pip-like command such as:

clawhub install

Always read a skill’s code and Markdown before enabling it. Treat third-party skills as untrusted code until you audit them.

A malicious skill can contain instructions that manipulate agent prompts or request sensitive data.

Creating a simple email skill

A minimal email skill can be a small Python script using SMTP. Store SMTP credentials in environment variables and keep the skill’s YAML front matter descriptive about required inputs.

import smtplib
from email.message import EmailMessage

def send_email(to_address, subject, body):
    msg = EmailMessage()
    msg["From"] = os.environ["SMTP_SENDER"]
    msg["To"] = to_address
    msg["Subject"] = subject
    msg.set_content(body)
    with smtplib.SMTP_SSL("smtp.gmail.com", 465) as smtp:
        smtp.login(os.environ["SMTP_SENDER"], os.environ["SMTP_PASSWORD"])
        smtp.send_message(msg)

Keep secrets out of workspace files. Use OS environment variables or a secret management solution.

Building a personal assistant with Openclaw

A personal assistant is typically a configured agent that has:

• Identity and user context files describing how to behave.

• Allowed channels (a one-to-one chat or a dedicated bot phone number).

• Skills for email, calendar, repository checks, or browser automation.

• Reasonable sandbox or tool restrictions to limit potential damage.

Recommended starter approach:

1. Install Openclaw and complete onboarding.

2. Create a new agent workspace for the assistant and fill out identity.md and user.md with relevant context.

3. Enable only the channels you need. Start with a single channel for testing.

4. Enable core skills such as email and repository checks, and test them in a sandbox first.

5. Run security audits and set heartbeat and hook policies conservatively.

Multi-agent setups and switching agents

Openclaw supports multiple agents to separate personas, permissions, and workspaces. Each agent can have:

• Independent model selection and credentials.

• Agent-level or session-level sandboxing.

• Different skill sets and channel permissions.

Adding a new agent with CLI:

openclaw agents add work
openclaw agents list

Switch between agents from the TUI with a command like /agents. Multi-agent workflows are useful when you need a separate work assistant and a personal assistant with different permissions and integrations.

Sandboxing: how to isolate agents safely

Sandbox mode runs agents in Docker containers to limit file system and process access. Sandboxing is one of the most effective mitigations against an agent executing arbitrary host commands.

Sandbox modes and scope

• Modes: off (no sandbox), agent (one container per agent), session (new container per session), shared (one container shared by sandboxed agents).

• Workspace access: read-only, read-write, or none. Avoid giving write access unless necessary.

• Tool policies: use a deny-list to prevent access to high-risk tools like exec or host-level browsers.

Setting up a sandbox

Ensure Docker is running, then use the sandbox setup scripts or CLI helper to create and assign a sandbox to an agent. Example:

./scripts/sandbox-setup.sh
openclaw agents modify work --sandbox-mode agent --sandbox-scope agent
openclaw gateway restart

After sandboxing, confirm the agent cannot access host files outside the sandbox. Query the agent directly to ask what it can see. A properly sandboxed agent will report only the files in its container workspace.

Security hardening checklist

Use this checklist before exposing any Openclaw gateway to networks or using agents with elevated tools:

1. Run the security audit: use the built-in audit and doctor commands to fix file permissions and configuration issues.

2. Enable sandboxing: run untrusted agents in Docker containers with minimal filesystem access.

3. Restrict channels to allow-lists: limit which WhatsApp numbers, Discord users, or Telegram chats can issue commands.

4. Limit tools: deny exec, elevated, or browser tools for agents that receive untrusted input.

5. Use dedicated accounts: give the agent separate phone numbers or bot accounts to avoid accidental overlap with your personal identity.

6. Scope API keys: give model and service keys minimal permissions and rotate them periodically.

7. Keep host backups: version and back up your workspace in Git or other storage so you can recover if a config file is lost or modified.

Common mistakes and how to avoid them

Granting open permissions

Mistake: allowing open access to the gateway or running agents with host-level privileges. Consequence: a compromised agent could execute destructive commands. Fix: use loopback binding where possible, restrict channels, and enable sandboxing.

Using a single phone number for bot and personal use

Mistake: sharing one WhatsApp account between human and bot interactions. Consequence: messages and actions become confused, and accidental triggers may occur. Fix: use a separate phone number for the bot or a private server for Discord testing.

Installing unreviewed skills

Mistake: blindly installing third-party skills from registries. Consequence: skills can introduce prompt manipulation or request secrets. Fix: review skill code and Markdown before enabling, and prefer skills from trusted sources.

Not testing in sandbox first

Mistake: enabling powerful tools (exec, elevated) without sandbox testing. Consequence: unexpected host modifications or leaks. Fix: test workflows inside a container, then grant limited host access only when needed.

Practical example: create a Gmail check skill and integrate with WhatsApp

Example workflow outline to check for unread messages and notify you via WhatsApp:

1. Create a Gmail skill that uses the Gmail API to list unread messages. Use OAuth credentials stored securely.

2. Define a skill.md that documents arguments, rate limits, and outputs.

3. Install and activate the WhatsApp plugin, and restrict allowed sender to your phone number.

4. Set a hook or heartbeat to run the Gmail check every hour and send a synthesized summary to your WhatsApp number.

5. Run everything in sandbox or a dedicated bot account for initial testing.

This pattern is the basis for many agent automations: a data source skill, an output channel, and a scheduled or triggered hook connecting them.

Maintenance, monitoring, and troubleshooting

Keep a small maintenance routine in place:

• Run the built-in openclaw doctor periodically to detect integrity issues.

• Inspect logs in the workspace logs folder for errors or suspicious activity.

• Rotate API keys and gateway tokens on a schedule.

• Use container monitoring if sandboxing, and remove old containers to free resources.

Migration, backup, and multi-device sync

Because agent definitions are stored as files, you can:

• Initialize the workspace as a Git repository for versioned backups and history.

• Clone the repo on another machine or VPS, restore secrets via environment variables, and run a quick onboarding or sync to resume the same agents.

• Use agent-level configuration differences to keep work and personal contexts separate across devices.

When to run Openclaw on a VPS vs on a personal machine

Consider the following trade-offs:

• VPS: isolates your personal files from the agent, reduces risk of host compromise, and allows remote access. Downside: more setup complexity and possible cost.

• Local machine: easier to use browser tools and local integrations, but allows agents potential access to your entire filesystem — use sandboxing aggressively.

Useful commands reference

# Install globally
npm install -g openclaw

# Onboard and install gateway daemon
openclaw onboard --install-daemon

# Enable a plugin
openclaw plugins enable whatsapp

# Login to channels (opens QR code for WhatsApp)
openclaw channels login

# Add an agent
openclaw agents add work

# List agents
openclaw agents list

# Run the health check and audit
openclaw doctor
openclaw security audit

# Sandbox setup script (example)
./scripts/sandbox-setup.sh
openclaw agents modify work --sandbox-mode agent --sandbox-scope agent
openclaw gateway restart

Troubleshooting tips

• If a channel fails to connect, check token and plugin enable status and review gateway logs for authentication errors.

• If a skill does not behave as expected, read its skill.md and confirm required environment variables are set.

• If an agent appears to have too much access, verify sandbox settings, deny policies, and workspace file permissions using the security audit.

• For Docker sandbox failures, make sure Docker Desktop or the Docker daemon is running and you have necessary permissions.

Checklist to go from zero to a safe, useful agent

1. Install Node 22+ and Openclaw globally.

2. Run onboarding and choose loopback binding if you do not need remote access.

3. Create a dedicated agent workspace and complete identity.md and user.md.

4. Enable only the channel(s) you need. Use a separate bot account or phone number where possible.

5. Install and review skills, preferring built-in or audited skills.

6. Enable sandboxing for any agent that receives untrusted input or can run commands.

7. Run security audit and doctor, fix any issues, and restrict tool access.

8. Test workflows inside sandbox before granting host-level privileges.

FAQ

How do I install Openclaw on macOS or Linux?

Install Node 22 or later, then run npm install -g openclaw. Use openclaw onboard to configure your workspace and optionally install the gateway as a daemon with the --install-daemon flag.

Can Openclaw access my whole computer?

By default an agent may have access to the workspace and the host depending on configuration. To prevent host access, enable Docker sandboxing and restrict workspace access to read-only or none. Do not grant elevated exec or bypass privileges to untrusted agents.

Which model providers does Openclaw support?

Openclaw supports multiple providers such as Anthropic and Google models. Choose a provider and model size appropriate for your use case; larger models typically have stronger resistance to prompt manipulation.

How do I safely connect WhatsApp or Discord?

Pair WhatsApp via QR scan using openclaw channels login. For Discord, create a bot application, enable message intents, invite the bot to a private server, then provide the token, guild ID, and channel IDs to Openclaw. Limit access with allowed-sender lists and test in private servers.

What is a skill and how do I audit one?

A skill is a folder with a skill.md that documents how the agent should use a tool or API. Audit by reading the Markdown and any code; ensure the skill does not request secrets or try to modify system-level configuration unexpectedly.

When should I use a VPS instead of running locally?

Use a VPS when you want to isolate the agent from personal files, need remote access, or prefer an always-on environment that is independent of your workstation. If you run locally, sandbox agents to reduce risk to your host.

Summary and next steps

This Openclaw tutorial walks you through setting up, configuring, and running a self-hosted agent gateway the right way.

Begin with loopback binding and tight permissions — keep things locked down. Only install the skills you actually need, and always audit them. For any workflow you don’t fully trust, run it inside a Docker sandbox.

Once you’re comfortable with the basics, you can slowly add more channels and agents. Just keep your audit and backup habits strong — don’t let things slip.

Follow the commands and checklists above. You’ll have a secure, reliable Openclaw setup that handles your routine tasks and keeps your data and host safe.