OpenClaw 2.0 Setup: A Detailed Guide to Creating Your Own AI Agent

OpenClaw 2.0 setup turns a regular AI model into a full-fledged personal agent. AI agents can already do far more than a standard chat: they can work with files, calendars, and email, run commands, search for information, and automate routine tasks. OpenClaw quickly became one of the most prominent open-source projects in this space and gathered hundreds of thousands of stars on GitHub within just a few months.

I have been following the development of AI tools for a long time, and OpenClaw caught my attention because an agent like this can become part of your everyday workflow: you can give it the tools it needs, access to files and services, and real tasks to handle. In this guide, I will show you step by step how to install OpenClaw 2.0 and set up your own AI agent for everyday work.

What OpenClaw is and what it can do

Project history: from a weekend project to a global phenomenon

It all started in November 2025, when Austrian developer Peter Steinberger published a weekend project called Clawdbot. The idea was simple: you message it in Telegram or WhatsApp, and it does things for you — manages your calendar, sorts through email, runs scripts, and searches the web.

In January 2026, the project began gaining traction rapidly. After Anthropic asked for the Clawdbot name to be changed, it was first renamed Moltbot and soon after became OpenClaw. The project continued to grow under that name.

Later, the project was transferred to the independent OpenClaw Foundation, where it continued to develop as an open-source project.

On August 31, 2026, version v2026.8.1 was released and documented as OpenClaw 2.0. It significantly changed installation, initial setup, memory, automations, and security.

What changed in version 2.0

Version 2.0 reworked several important parts of OpenClaw:

• Simpler installation. During initial setup, OpenClaw checks whether you already have access to a model through Claude Code or Codex, an API key in environment variables, or a local model. If you do, there is very little to configure manually before the first conversation.
• The Control UI web interface was significantly redesigned. You can use it to chat with the agent, view files, approval requests, settings, and current tasks.
• Sessions and transcripts moved to SQLite. They used to be stored in files. This matters when upgrading — I’ll cover the details below.
• Memory gained semantic search. The agent can find relevant passages in its Markdown files by meaning, even when your query uses different wording.
• Skill Workshop now brings together creating and updating your own skills with a review step before changes are applied.
• In the user interface, Cron jobs are now called Automations. The command line uses openclaw automations, while openclaw cron remains available for compatibility with older scripts.
• The default settings are safer. In a standard local installation, Gateway binds to loopback by default and access is protected by authentication. Docker and shared Gateways have additional nuances that I’ll cover later.

How an agent differs from a regular chatbot

A regular chat mostly responds with text. OpenClaw gives the model access to tools: the agent can read a file, run a command, create a task, or perform another permitted action. For me, that is the key difference.

For example, OpenClaw can:

• Read and create files on your computer
• Run commands in the terminal
• Browse the web and fill out forms
• Send emails and messages
• Work with APIs from different services
• Automate tasks across different apps
• Remember context across sessions
• And much more

And it can do all of this through the familiar interface of your messaging app. You simply write in Telegram, “Sort through my inbox, delete spam, and make a list of the important emails,” and it does it. It does not explain how to do the task — it actually carries it out.

Runs on your own hardware 24/7

Gateway, the workspace, and agent data can live on your computer or server. That does not mean all data stays only with you: Claude, GPT, Gemini, cloud-based web search, and messaging services receive the requests OpenClaw sends through their platforms. OpenClaw can operate fully locally when you use a local model and no cloud integrations. On a VPS, the agent can run around the clock even when your main computer is turned off.

What file-system access gives the agent

When the agent has access to files, it can work with your actual materials instead of only replying in chat. OpenClaw can:

• Create and edit documents, code, and configuration files
• Organize files by renaming, sorting, and converting them
• Create backups and work with Git
• Analyze CSV, JSON, and logs
• Generate reports and save them

If the agent has the tools and permissions it needs, it can receive a task from a message, work with files and code, review the changes, and prepare a pull request on GitHub.

What you need before you start

Before installing OpenClaw, make sure you have everything you need.

Required Node.js version

This is a hard requirement. OpenClaw runs on Node.js, so older versions simply will not work. Check your version:

node --version

OpenClaw currently requires Node 24.16+ or 26.1+, and Node 26 is recommended. Node 22, 23, and 25 are no longer supported. If you install Node manually, use at least v24.16.0 or v26.1.0.

If Node.js is not installed, the official installer can add it for you: Node 26 on macOS and a supported Node 24 LTS branch on Linux. If Node.js is already installed but the version is unsupported, update it before launching OpenClaw. CLI installation on macOS with a current Node version requires macOS 13.5 or later.

Git on Windows: when you need it

You usually do not need a separate Git installation for the standard PowerShell setup. Git is required if you deliberately install OpenClaw from a Git repository. If a normal installation fails with an error such as spawn git ENOENT, rerun the installer or install Git for Windows manually.

On macOS, start by checking git --version. If Git is not available yet, macOS may offer to install the Command Line Tools; you do not always need to install Git separately through Homebrew.

Access to an AI model

OpenClaw is not a language model. For the agent to respond and carry out tasks, it needs access to an LLM. During initial setup, OpenClaw checks which options are already available on your computer and then asks you to choose a provider.

The most common options are:

• Anthropic — Claude through an API key or Claude CLI.
• OpenAI — GPT models through the API or a supported sign-in method.
• Google Gemini — through Google AI Studio / API.
• Local models — for example through Ollama or LM Studio.

Telegram bot through @BotFather

To connect Telegram, you need a bot token from @BotFather. The process takes about two minutes:

• Open @BotFather in Telegram
• Send the /newbot command or choose it from the command list
• Give the bot a name and username
• Copy the token

Save this token — you will need it during setup. In OpenClaw 2.0, Telegram no longer has to be connected before your first conversation: you can start the agent in the browser first and add Telegram later.

Computer or VPS

You have two main options:

• Local computer (Mac/Linux/Windows) — best for testing and getting started.
• VPS (Virtual Private Server) — a good option for 24/7 operation. Keep the system updated, configure a firewall, make backups, and make sure the server has enough resources for your setup.

I recommend starting on a local computer so you can understand how OpenClaw works first, then move to a VPS later if you need 24/7 operation.

How to install OpenClaw 2.0: step-by-step

Installing on macOS

Step 1. Install Homebrew (optional)

Homebrew is a package manager for macOS. OpenClaw no longer requires it: the installation script can install Node.js for you if it is missing. Still, Homebrew makes it easier to manage versions.

Check whether Homebrew is already installed:

brew --version

If the command is not found, install Homebrew. Open Terminal and paste:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the instructions in Terminal. When installation finishes, restart Terminal so the brew command is available.

Step 2. Install Node.js

OpenClaw can install Node.js automatically, but I prefer installing it separately so you know exactly which version is on the system and avoid dependency issues later.

brew install node

Check that the installation worked:

node --version

The command should return one of the supported Node versions. If you are starting from scratch, the easiest choice is the recommended Node 26.

Step 3. Install OpenClaw

Open the official OpenClaw website — it provides a ready-to-use installation command.

Select the macOS command, open Terminal, and paste the copied line:

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

This script checks Node.js, installs it if necessary, adds the OpenClaw CLI system-wide, and launches the setup wizard.

The installer also handles PATH correctly and is safer to rerun: if setup is interrupted, your existing configuration stays intact.

If the setup wizard does not start automatically, run:

openclaw onboard

Step 4 (optional). Install the OpenClaw app for macOS

OpenClaw also has a separate macOS app with a graphical interface. Its icon appears in the menu bar, where you can quickly open the agent and manage Gateway without keeping Terminal open.

Download OpenClaw-<version>.dmg from the GitHub releases page, install it, and launch OpenClaw.app. If you open it from Downloads, OpenClaw will offer to move itself to Applications, where updates and launch-at-login work correctly.

After installation, a lobster icon appears in the menu bar. From there you can start and stop Gateway, see the agent status, and open Control UI quickly — all without using the terminal.

Installing on Windows

On Windows, the simplest option with a graphical interface is currently Windows Hub.

Option A (recommended): Windows Hub

This is a signed Windows installer with a setup wizard, a system-tray icon, agent chat, and node mode. Windows Hub supports Windows 10 20H2+ and Windows 11.

Download the build that matches your system:

• OpenClawCompanion-Setup-x64.exe — for standard Intel and AMD PCs
• OpenClawCompanion-Setup-arm64.exe — for Windows on ARM devices

If you are not sure which build you need, check the official Windows guide or the latest stable Windows Hub release page. Most Intel and AMD PCs need x64; ARM64 is only for Windows devices with ARM processors.

Option B: PowerShell installer

If you prefer working from the terminal:

Step 1. Install Node.js

If you want to prepare the environment manually, install a current supported version of Node.js from nodejs.org. The PowerShell installer can also install Node for you if needed.

Step 2 (if needed). Install Git

If you choose installation from a Git repository, or PowerShell reports that Git is missing, install it from git-scm.com. You can usually skip this step for the standard npm-based installation.

Open PowerShell and verify that everything is available:

node --version
# If Git is installed:
git --version

Step 3. Install OpenClaw

Open PowerShell (not cmd) and run:

iwr -useb https://openclaw.ai/install.ps1 | iex

The PowerShell installer installs Node.js when necessary and updates PATH. If you choose installation from a Git repository, it can also prepare a local MinGit when Git is not already installed.

WSL2 is also supported. For a typical local agent on Windows, however, Windows Hub or the PowerShell installer is usually simpler.

Alternative method: Docker

Docker makes sense if you want a separate Gateway in a container or are setting up a server deployment. For a normal desktop installation, the official documentation recommends starting with the standard installation.

From the root of the official repository, the simplest supported setup is:

./scripts/docker/setup.sh

If you do not want to build the image locally, specify the official prebuilt image:

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

A container isolates OpenClaw only within the permissions you give it. Host access depends on mounted directories, the Docker socket, network access, and any other privileges passed into the container.

OpenClaw 2.0 setup

Initial setup: what the current onboarding flow looks like

After installation, the OpenClaw setup wizard usually starts automatically. If it does not, launch it manually:

openclaw onboard

On a fresh local installation, OpenClaw first offers two options:

How would you like to start?

Quick start (recommended)
Custom setup

Quick start is the fastest route. OpenClaw uses sensible defaults, automatically checks which AI connection methods are available, asks you to choose one, and opens Dashboard after the connection test succeeds.

Custom setup is the more detailed path. It lets you step through the security confirmation, telemetry, agent name, access mode, and other settings manually.

1. Security confirmation

The wizard first asks you to confirm that you understand OpenClaw’s access model:

I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?

For a standard personal installation, choose Yes and continue.

2. Telemetry

Next, OpenClaw asks whether you want to send usage statistics:

Help make OpenClaw better?

This step is optional. In my setup, I chose No thanks and continued.

3. Name your first agent

The next step is the agent name:

What should we call your first agent?

I named my agent Jarvis. You can choose any name here; I’ll cover the agent’s personality and rules in more detail later.

4. How OpenClaw will look for AI access

The wizard then asks:

How should I set things up?

In my case, I selected:

Full access — find everything automatically

In this mode, OpenClaw checks the local environment for AI access methods that are already available. The wizard shows what it found, and you choose the connection you want to use next.

5. AI detection

After the scan, you will see:

AI detection complete.

OpenClaw then shows exactly what it found. In my case, it detected an installed copy of Claude Code:

AI found

Claude Code — installed; login status unverified

If OpenClaw found a model connection that works for you, you can use it. If not, the next section shows how to connect a provider manually using Anthropic as the example.

Choosing a provider, authentication method, and model

After AI detection, OpenClaw moves on to provider selection. This is where you decide which AI platform the agent will use. I chose Anthropic.

After selecting Anthropic, OpenClaw shows a separate screen for the authentication method:

• Anthropic Claude CLI — reuse Claude Code that is already authenticated on this computer.
• Anthropic API key — connect directly through the Anthropic API.
• Anthropic setup-token — a separate supported authentication flow.

If you choose an Anthropic API key

Open Anthropic Console, create a key under API Keys, and paste it into OpenClaw.

I ran into exactly this: the key itself was valid, but because the API balance was empty, OpenClaw marked the profile as disabled:billing. If you see an inference error after launch, check Billing in Claude Console first.

If you want to use Claude Pro/Max through Claude CLI

This route makes sense if Claude Code is already installed and authenticated on the same computer. Before selecting the CLI option, test it separately:

claude auth status --text
claude -p "Reply with OK only"

The second command is the important one. Seeing Login method: Claude Pro account does not by itself guarantee that Claude Code is allowed to use the subscription. If claude -p returns a response, the CLI route works.

Choosing the model

After authentication, OpenClaw asks you to choose the specific model that will be the agent’s default. The list depends on the provider, your authentication method, and the models available to your account.

Do not spend too long on this during the first setup. Pick an available model, finish onboarding, and make sure the agent responds. You can change the default model later through Control UI or with /models.

Finishing onboarding and opening Dashboard

Once the provider, authentication, and model are configured, OpenClaw finishes the technical part of onboarding. It prepares the workspace, installs or starts Gateway, and verifies inference.

You should see an Inference ready block in the terminal, the local Gateway address, and Everything's in place. OpenClaw then opens Control UI in your browser automatically.

Once the browser connects, the main Dashboard / Control UI screen appears.

First test: does the agent respond?

In Control UI, open the Home tab and send a simple message that does not require web search, Telegram, or any additional Skills. For example:

Hello. Reply in one sentence and tell me whether you're ready to work.

If the agent responds, the basic setup is complete. You now have a working model, Gateway, and Control UI. At this point, you can personalize Jarvis and only then move on to extra capabilities.

What to configure next

You do not need to connect everything OpenClaw offers on day one. After the first successful response, I would proceed in this order:

• Configure the agent first — its name, context, response style, and rules. I will show this below using Jarvis as the example.
• Then add web search if your work needs it. In Control UI, go to Settings → Ask OpenClaw and enter configure web search.
• Connect Telegram if you want to use the agent from your phone. You already created a BotFather token near the beginning of the guide; below I’ll show how to add it to OpenClaw and approve access.
• Add Skills for specific jobs. There is no reason to install dozens of Skills on the first day.
• Leave Hooks and Automations for later. They become useful once the basic agent works and you know exactly what you want to automate.

Example: how I configured my Jarvis agent

Once the basic chat in Control UI is responding, you can configure the agent itself right away. You do not need to open workspace files manually. In the regular Dashboard chat, one message can explain who you are, what the agent should be like, how it should respond, and which actions require separate confirmation.

A new OpenClaw workspace already contains the core files AGENTS.md, SOUL.md, IDENTITY.md, USER.md, and the one-time BOOTSTRAP.md. During the first real conversation, the agent uses them for initial setup. Once bootstrap is complete, BOOTSTRAP.md is removed.

I did not stretch the introduction across a dozen short messages. I gave Jarvis the key context in one go:

My name is Dmytro. I work in the crypto industry and create
content, guides, articles, and product pages for Lwallet.

Your name is Jarvis.

I want you to be calm, precise, and slightly ironic.
Write naturally and get to the point. Avoid corporate language,
grandstanding, and filler.
Explain complex things simply, but never dumb them down.

If you see weak wording, suggest something better.
If you don't know something, say so directly instead of making it up.

Never send emails without my confirmation.
Never take any action involving money without my explicit approval.
If an action could have serious consequences, ask me first.

This is not a required template. You can write it in your own words, make it shorter, or add context gradually as you work. At the start, the important things are the agent’s name, basic information about you, the communication style you want, and a few clear boundaries.

OpenClaw stores these settings in the workspace: IDENTITY.md defines the agent’s identity, SOUL.md its personality, tone, and behavioral boundaries, and USER.md information about you and your stable preferences. That way, you do not have to explain everything to your agent again in every session.

Check Gateway

After onboarding, how Gateway is running depends on the setup path you chose. Quick start leaves Gateway running in the current terminal, while Custom/classic setup may install the background service during the wizard. On Windows, that service runs as a Scheduled Task.

Start by checking the status:

openclaw gateway status

If Gateway is running, continue. In the standard local configuration, it is only reachable from your own computer at 127.0.0.1:18789.

If you used Quick start and Gateway is still running in this terminal, stop it with Ctrl+C after the first check, then install the background service. If openclaw gateway status already shows an installed service, you can skip this step:

openclaw gateway install

After that, you can manage Gateway with the usual commands:

openclaw gateway start
openclaw gateway stop
openclaw gateway restart

Diagnostics: doctor and triage

This is an important step that many people skip. After setup, always run the built-in diagnostics:

openclaw doctor

Doctor checks the configuration, credentials, channels, and known problems. It can also apply some migrations and safe fixes automatically:

openclaw doctor --fix

Version 2.0 also added another very useful command:

openclaw triage

Triage builds a read-only diagnostic description of the problem and can hand it to Claude Code, Codex CLI, or OpenClaw’s built-in agent if one of them is available on the machine. Otherwise, it simply shows the next commands to run. This is much more convenient than collecting log fragments manually.

Still, review what the diagnostic report contains before sharing it. If the problem involves secrets or personal information, do not rely on automatic redaction alone.

When the checks finish, review the final terminal output and make sure there are no critical errors left.

Doctor may also offer to enable shell completion:

Enable zsh/shell completion?

You can safely choose Yes. Once enabled, typing openclaw and pressing Tab will show available commands. It is a small convenience, but it saves time.

Connecting Telegram and approving access

You already created the Telegram bot token through @BotFather near the beginning of the guide. Now add that token to OpenClaw.

Open a new PowerShell or terminal window and run:

openclaw channels add --channel telegram --token "<bot-token>"

Replace <bot-token> with the token BotFather gave you.

After adding the channel, restart Gateway so it reloads the configuration:

openclaw gateway restart

If you want, immediately check whether the Telegram channel is up:

openclaw channels status --probe

Now open Telegram, find your bot, and send it a message. By default, OpenClaw uses pairing for direct messages: a new user receives a confirmation code, and their messages are not passed to the agent until access is approved.

The easiest way to approve the request is directly in Control UI:

Settings → Channels → DM access requests → Approve

You will see the user who sent the request and their pairing code.

If you prefer the terminal, list active requests first:

openclaw pairing list telegram

Then approve the code you want:

openclaw pairing approve telegram XXXXXXXX

Here, XXXXXXXX is the 8-character code from the bot’s message.

After approval, send the bot another message in Telegram. Your direct messages will now be passed to the connected agent.

Give the agent real work

Do not invent artificial test tasks — give the agent something you are actually working on. For example:

• “Rewrite this so it sounds natural: {paste text}”
• “Write a short product-page description for {product name}”
• “Explain the difference between {A} and {B} in simple terms”
• “Read {file name} and give me a concise summary”
• “Create an outline for an article about {topic}”

You can interact with the same agent through the web interface, terminal, and Telegram. The channels are different entry points to the same agent, with shared long-term memory where configured.

How to interact with the agent

Once Gateway is running as a service, there are several ways to talk to the agent:

openclaw

Running openclaw without arguments opens the TUI — a text-based chat with the agent in your terminal. It is convenient for quick tasks, testing, and working over SSH.

openclaw dashboard

This opens the web interface (Control UI) in your browser. From there, you can chat with the agent, manage Skills, and view logs.

openclaw skills list

This shows the installed Skills.

Or simply message the bot in Telegram — if the channel is connected, the agent is already available there.

Web interface: Control UI

In version 2.0, Control UI became the main interface for day-to-day work with the agent.

From here, you can chat with the agent, view files, approval requests, current tasks, logs, and key settings. Some options that previously required editing configuration files can now be changed directly in the interface.

How to open Control UI

Make sure Gateway is running (openclaw gateway status), then run:

openclaw dashboard

openclaw dashboard opens Control UI through a short-lived, one-time owner-pairing link. After a successful handoff, that browser receives its own durable administrator device credential, so reopening the dashboard no longer depends on the shared Gateway token.

If you only want the URL without opening a browser automatically, for example to open it on another device:

openclaw dashboard --no-open

The command prints the same temporary handoff link in the terminal without launching a browser. Copy it and open it manually: the link is short-lived and intended for one-time use.

Do not share this link with other people or expose it in chats or screenshots. For remote access, use an SSH tunnel or Tailscale instead of exposing Gateway to the network just to reach Control UI.

What you can do in Control UI

• Chat with the agent — the main chat, files, and approval requests are all close at hand
• Configure Skills — Settings → Agents → Skills lets you manage the allowlist and settings for Skills that are already available
• Work with agent files — under Settings → Agents, you can open the workspace files for a specific agent and edit them in the browser
• View memory — the separate Settings → Memory section shows memory, search, and Dreaming status
• Check connections — see which channels are active and how they are configured
• View logs — see what happened in the system and which errors occurred
• Change settings — model, channels, tools, permissions, and other OpenClaw options
• Usage — session and token statistics plus estimated costs. If you connect an Anthropic Admin API key, OpenClaw can also show usage and cost data directly from Anthropic for the last 30 days.

Connecting additional channels

Telegram is only one option. OpenClaw also supports channels such as WhatsApp, Discord, Slack, Signal, and others. The exact list depends on the plugins you have installed and the integrations available in your setup.

Setup differs by channel. For example, WhatsApp is linked through a QR code with:

openclaw channels login --channel whatsapp

For other channels, use the Channels section in Control UI or follow that integration’s guide; plugin-installation and authentication steps can differ.

You can connect several channels to the same agent. Each one, however, is another external system with its own access and privacy rules, so do not add channels just because they are available.

To check the status of all channels:

openclaw channels status

Choosing a model and controlling costs

How to change the model

Method 1: through your messaging app (the simplest option). Send your bot:

/models

The agent will show the models available to you. Choose the one you want directly in chat.

Method 2: through the terminal. Version 2.0 has dedicated commands for this, which are easier than editing the configuration manually:

openclaw models list
openclaw models set anthropic/claude-sonnet-5
openclaw models status

To see which models are available to your account from a specific provider:

openclaw models list --provider anthropic

Method 3: Control UI → Settings → Models.

Claude vs GPT vs Gemini: which one should you choose?

I tried several different models. At the beginning, I would choose based on three things: quality, speed, and cost.

Claude Sonnet 5 (Anthropic) is my main choice for everyday work. The current API price is $2 per million input tokens and $10 per million output tokens; always check the latest rates on Anthropic’s pricing page.

Claude Opus 5 is better suited to harder tasks where quality matters more than cost. API pricing is $5 per million input tokens and $25 per million output tokens. For day-to-day work, I would keep Sonnet as the default and switch to Opus only when needed.

Claude Haiku 4.5 is the cheaper option at $1 per million input tokens and $5 per million output tokens. It can work well for simple background jobs or repetitive tasks once you have confirmed that the quality is good enough.

OpenAI — OpenClaw supports GPT-5.6 Sol and, since v2026.9.2, GPT-6 Astra for accounts where that model is already available. Do not rely only on a model name mentioned in an article: openclaw models list --provider openai shows what your account can actually use.

Google Gemini is another solid option. Here, I would focus on the specific model you have access to, its limits, and how well it performs on your actual tasks.

Local models (Ollama, LM Studio) let you keep LLM requests off cloud model providers. Other integrations may still use external services, however. For complex tool-heavy workflows, test the quality of the local model separately.

Why an agent uses more tokens than a regular chat

In a normal chat, one prompt often results in one response. An agent task may require several model calls: read a file, run a command, inspect the result, fix an error, and try again. One user instruction therefore does not mean one API call.

Session context, bootstrap files, and tool outputs add to that cost. The longer and more complex the session becomes, the more expensive each next step can be.

Practical advice: do not keep one session running forever. When a topic is finished, start a new one. This makes both context and spending easier to control.

Here is an example from my first setup. I used Claude Opus, completed BOOTSTRAP, sent several messages in Telegram, and ran a few test tasks. The total was 38 messages, and the Usage page showed $8.45 in spending for that evening. That is one real case from my setup, not a universal estimate. Your cost can be very different depending on the model, context length, and number of tool calls.

I would still start with Sonnet and use Opus only for tasks where the higher quality justifies the extra cost. I would also watch Usage from day one so you see your real spending instead of guessing what the monthly bill might look like.

Configuring the agent’s personality

You already set Jarvis’s basic personality directly in chat. Now I’ll show where OpenClaw stores those settings and how you can change them later through Control UI.

How the agent files work

Each agent has its own workspace with files that OpenClaw uses as persistent context. At the start of a new session, the relevant files are added to the agent’s context, so you do not have to explain its name, style, and basic rules all over again.

• SOUL.md — the agent’s personality, communication style, and behavioral boundaries.
• IDENTITY.md — name, persona, emoji, and other identity details.
• USER.md — information about you: how the agent should address you, your work context, and stable preferences.
• AGENTS.md — working instructions: rules, priorities, procedures, and how the agent should use memory.
• BOOTSTRAP.md — the one-time first-run introduction flow. It is removed after bootstrap is complete.
• MEMORY.md — an optional long-term memory file. It only appears once long-term memory has actually been created or written.

By default, the main workspace is located at ~/.openclaw/workspace. If Control UI is connected to a remote Gateway, these files physically live on the Gateway machine, not on the computer where you opened the browser.

Do not overload the bootstrap files

OpenClaw already creates the standard files, so you do not need to invent a complicated structure from scratch. Start with a concise SOUL.md, a useful USER.md, and clear rules in AGENTS.md, then expand them as real work gives you a reason to.

OpenClaw limits the default bootstrap context to 20,000 characters per file and 60,000 characters in total. USER.md has its own smaller budget. If a file is too large, some content may be truncated when it is injected into context.

A useful practical habit is to ask the agent, after a few days of real work, to review its own SOUL.md and suggest only the changes that genuinely follow from your interactions.

If long sessions start consuming too much context, there is an optional mode that avoids reinjecting bootstrap files on every safe continuation turn:

openclaw config set agents.defaults.contextInjection continuation-skip

This setting is optional. OpenClaw uses always by default, so I would leave it alone at first.

Where to find the files in Dashboard

Open Control UI → Settings → Agents, choose the agent you want, and open the Files tab. You can view and edit its workspace files directly in the browser.

It is more convenient to change the name, emoji, and avatar under Overview → Identity. These values also sync with IDENTITY.md, and UI settings take precedence over manually editing the same fields in the file.

If you do not want to edit Markdown manually, simply ask the agent in chat to change a specific rule or update information about you, then review the result in Files.

Memory: how the agent remembers

OpenClaw can preserve important context between conversations so the agent does not start every new session from scratch. It uses Markdown memory files, a search index, and a separate Dreaming mechanism.

In Control UI, open Settings → Memory. This is where you can check memory, search, and Dreaming status.

Long-term memory

MEMORY.md is compact long-term memory: stable facts, decisions, and important context worth keeping between sessions. More detailed working notes can be stored in files such as memory/YYYY-MM-DD.md.

OpenClaw does not necessarily create a new file after every conversation. If you want the agent to remember something explicitly, the simplest approach is to ask it directly — for example: “Remember that I want concise, natural wording in work-related writing.”

Dreaming

Dreaming is OpenClaw’s background memory-consolidation system, and it is enabled by default in the current version. It reviews accumulated short-term signals and promotes only the information it considers important enough for long-term memory into MEMORY.md.

You can inspect this process through Dream Diary. A human-readable Dreaming log is stored in DREAMS.md, where you can see what the system processed and what changed. Dream Diary itself is not used as long-term memory — the durable results are written to MEMORY.md.

Searching memory

Memory search can combine exact keyword matching with embeddings, which can find semantically similar content even when the wording is different. By default, OpenClaw uses OpenAI for embeddings.

To quickly check memory and embedding status:

openclaw memory status --deep

If you do not need semantic search yet, you can keep keyword-only search:

openclaw config set memory.search.provider none

Backups

Before major updates or configuration changes, create a backup of OpenClaw:

openclaw backup create --verify

This creates a verified archive containing the configuration, OpenClaw state, agent data, sessions, and workspace. By default, the backup is saved as a .tar.gz file.

You can verify an existing archive separately:

openclaw backup verify ./<backup>.tar.gz

Skills: how to add new capabilities to your agent

Skills, Plugins, and ClawHub: what’s the difference?

A Skill is a set of instructions for the agent built around a SKILL.md file. It explains when and how to perform a particular type of work — for example, how to review a pull request, prepare a report, or follow a specific workflow. A Skill does not necessarily add a new tool; often it simply teaches the agent how to use tools that are already available.

A Plugin is a software extension for OpenClaw. Plugins can add new tools, channels, model providers, hooks, web search, speech, and other runtime capabilities.

ClawHub is a public registry for Skills and Plugins. It is the most convenient place to browse available packages, check the author, versions, changelog, source code, and security scan results before installing anything.

How to find and install a Skill

For most users, I would start with ClawHub. Open the website, find the Skill you need, review its description and security scan, then install it with the OpenClaw CLI. You do not need the separate clawhub CLI for normal installation; that tool is aimed more at authors who need to sign in, publish, and manage their own packages.

You can also search directly from the terminal:

openclaw skills search "calendar"

Once you have chosen a specific Skill, verify its trust envelope and install it:

openclaw skills verify @owner/<slug>
openclaw skills install @owner/<slug>

After installation, check that OpenClaw can see it and that all dependencies are ready:

openclaw skills list
openclaw skills check

By default, a Skill is installed into the active workspace’s skills/ directory and belongs to that agent. If you want the Skill to be available to all local agents, use --global; it will be installed under ~/.openclaw/skills.

openclaw skills install @owner/<slug> --global

To update all ClawHub Skills:

openclaw skills update --all

What the Skills tab in Dashboard actually does

In the current Control UI, the path is Settings → Agents. The Agent Defaults page has Agents, Skills, Tools, and Session tabs. The important point is that Skills here is for configuration — it is not a marketplace and not an Install button for ClawHub.

• Agents → Skills under Agent Defaults defines the default Skill allowlist inherited by agents. If the list is not set, that means “no extra restriction,” not “no Skills.”
• Skills → Allow Bundled only limits OpenClaw’s bundled Skills. Managed and workspace Skills are not disabled by this list.
• Skills → Entries is where you configure individual Skills, including Enabled, Api Key, Env, and custom Config values.
• Tools is a separate tab. It controls available tools, allowlists/denylists, and command-execution policy; it is not used to install Skills.

That is why I do not use Dashboard as the main installation method in this guide. For discovery and installation, ClawHub + openclaw skills is simpler and more predictable; Settings → Agents → Skills is better for configuration afterward.

Plugins

You need a Plugin when OpenClaw is missing the capability itself, not just instructions for how to use it. A Plugin can add new tools, channels, model providers, web search, or other runtime functionality.

You can also find Plugins through ClawHub. Once you have found the one you need:

openclaw plugins install clawhub:<package>

You do not need to install extra Plugins during the initial setup. Come back to them only when you know which specific capability your agent is missing.

Skill Workshop

Skill Workshop is not for installing ready-made Skills; it is for creating your own based on real work. If you and the agent have gone through the same process several times, for example, that process can be turned into a reusable Skill.

The easiest approach is to ask the agent directly to turn an established workflow into a Skill. For the current conversation, you can also use:

/learn

/learn analyzes the current conversation or the materials you specify and prepares a Skill through Workshop. Changes are not applied automatically; you can review the result before using it.

Which Skills are worth looking for?

Do not install dozens of Skills “just in case.” Start with a real need and look for a suitable option on ClawHub:

• GitHub, code review, and repository workflows;
• email and calendars;
• processing and summarizing documents;
• working with secrets and password managers;
• your own team checklists and repeatable workflows.

Web search and Browser

You no longer need a separate Skill for ordinary web search. In Control UI, open Settings → Ask OpenClaw and enter:

configure web search

OpenClaw shows the available search providers and tells you which ones require an API key. You can configure the same thing from the terminal:

openclaw configure --section web

Why I chose DuckDuckGo

When I set up the first version of OpenClaw, I needed web search but did not want to pay for the Brave API or create another API key just for search. I went to ClawHub, found a DuckDuckGo option, added it to my Skills, and web search started working without a separate API key.

Today, the process is much simpler. DuckDuckGo Search is already one of the providers offered by configure web search. Select it from the list — no account or API key is required. If the provider needs an additional Plugin, the local setup flow installs it automatically.

web_search searches through the provider you selected, while web_fetch reads a specific page by URL. For most research tasks, that is enough.

When you need Browser

Browser is for actual interaction with a website: when the page depends on JavaScript, you need to click a button, fill in a form, or work inside an authenticated session.

OpenClaw has a separate managed browser profile called openclaw, isolated from your normal Chrome profile. You can check its status and start it when needed:

openclaw browser status
openclaw browser start

At the beginning, I would configure only web_search. Come back to Browser once the agent genuinely needs to interact with pages rather than simply find and read information.

Security: what you should configure

This is one of the most important sections in the guide. OpenClaw can have access to the command shell, files, the browser, messaging apps, and external services, so security needs to be taken seriously.

Safer defaults in version 2.0

Version 2.0 significantly revised the default security settings and made them more conservative for a standard local installation.

By default:

• Gateway is only reachable from the same computer. OpenClaw uses the local address 127.0.0.1 (loopback / localhost), so other devices on the network cannot connect directly.
• Gateway access is protected by authentication. OpenClaw rejects connections when authentication is not configured.
• During initial setup, OpenClaw creates an access token automatically even when Gateway is only local.
• If an unknown user messages the bot through a supported channel, OpenClaw will usually require approval through a pairing code. Until you approve it, that user’s message is not passed to the agent for execution.
• Group chats are restricted too: in most cases, the group must be explicitly allowed and the bot must be mentioned before the agent responds.

For a personal installation, this is already much safer than early OpenClaw versions. But these defaults will not protect you if you expose Gateway to the network without a reason or install untrusted code.

tools: {
  sessions: { visibility: "agent" },
  agentToAgent: { enabled: false }
}

Also review networking if you run OpenClaw in Docker or another container. The bind behavior can differ from a normal local installation, so restrict any exposed port with a firewall and do not publish it to the open internet.

Quick security check

Instead of checking dozens of settings by hand, start with:

openclaw security audit

This command checks:

• Inbound access — rules for direct messages and groups: can unknown users reach the bot?
• Tool permissions — could prompt injection lead to shell commands or file actions?
• Network access to Gateway — bind settings, authentication, and weak tokens
• Remote browser control — nodes and relay ports
• File permissions — permissions, symbolic links, and paths inside synchronized folders
• Plugins — whether they can load without an explicit allowlist
• Model selection — warnings about outdated models

Useful flags:

openclaw security audit --deep  # live Gateway check + deeper Skill and Plugin checks
openclaw security audit --fix   # apply safe fixes
openclaw security audit --json  # JSON output

--fix intentionally applies only safe local fixes, such as tightening open group policies and file permissions. It does not rotate tokens or keys, disable dangerous tools, or decide whether exposing Gateway to the network is appropriate for you.

I would run a security audit after major configuration changes, after installing new Plugins, and before enabling any remote access.

If you really need remote access

Check the current bind setting:

openclaw config get gateway.bind

Common values:

• loopback (default) — only local clients can connect
• lan, tailnet, or custom with a non-loopback address — makes Gateway reachable by a wider set of clients and increases the attack surface

A few rules are worth memorizing:

• Do not expose Gateway to a LAN or public network without authentication and a clear reason.
• For remote access, it is usually safer to keep Gateway on loopback and use Tailscale Serve or an SSH tunnel.
• If LAN access is necessary, allow only the required IP addresses through the firewall.

If for some reason you do not have a Gateway token, generate one with:

openclaw doctor --generate-gateway-token

Threats in ClawHub Skills

ClawHub is an open registry, so you should not install a third-party Skill or Plugin simply because it appears in the catalog. On the package page, check the author, source, version, required credentials and permissions, and the Security Audit.

ClawHub shows automated scan results and can block problematic releases, but even a Pass status is not an absolute security guarantee. Install only packages whose purpose and requested permissions you understand.

How to protect your setup

• Do not install Skills or Plugins blindly. Be especially careful with Plugins: they run inside the Gateway process and therefore operate with trusted access.
• For extra control, OpenClaw supports security.installPolicy: a local policy can return allow, warn, or block before a Skill or Plugin is installed or updated.
• Run openclaw security audit regularly.
• Use an isolated environment (sandbox) for risky tools. Docker/Podman can limit the impact of a mistake as long as you do not hand the container unnecessary directories, sockets, or privileges.
• Do not run OpenClaw as root unless there is a real need. A dedicated user with minimal privileges reduces the impact of a mistake.
• Do not store keys in arbitrary workspace files. Use built-in secret mechanisms or environment variables where supported.
• Install updates, then run openclaw doctor and openclaw security audit.
• Limit the agent’s authority with real technical controls, not only instructions in SOUL.md. A rule such as “do not send without confirmation” is useful, but it does not enforce anything at the system level by itself.
• If the agent has access to shell, browser, or important files, test a weaker model on your own workflows before switching to it. A weaker model may be worse at recognizing dangerous instructions and its own mistakes.

Prompt injection

Prompt injection is one of the main practical threats for agents that can use tools.

The idea is simple: text from an external source may try to push the model into doing something you never asked it to do. Those instructions can be hidden in a chat, webpage, email, document, attachment, or log.

That is why even a private Telegram bot does not solve the problem completely. If the agent reads external material, you should treat that material as potentially hostile too.

What helps:

• Keep direct-message access closed by default: use pairing or explicit allowlists.
• Treat links, attachments, and embedded instructions as untrusted data.
• Do not give exec, browser, or other high-risk tools to an agent that does not need them.
• Consider a separate lower-privilege agent for reading untrusted material.
• Keep secrets outside paths the agent can read unless those secrets are actually required for its work.

Incident response: what to do if something goes wrong

• Stop Gateway: openclaw gateway stop
• Close external access: return gateway.bind to loopback and disable unnecessary tunnels.
• Temporarily disable or restrict any channels through which malicious content may have arrived.
• Rotate any tokens and API keys that may have been exposed.
• Check the logs: openclaw logs
• After making changes, run openclaw security audit --deep again.

Automation: Heartbeat, Automations, and Hooks

These three mechanisms serve different purposes: Heartbeat performs periodic checks, Automations run tasks on a schedule, and Hooks react to events.

Heartbeat: periodic background checks

Heartbeat is a system automation that periodically runs the agent in its main session to check a short list of things and report only what genuinely needs your attention.

By default, Heartbeat runs every 30 minutes. With Anthropic OAuth/token authentication, including Claude CLI, OpenClaw may use a one-hour interval unless you set your own. Either way, choose a frequency that matches the task and your budget.

For example, to check once per hour:

openclaw config set agents.defaults.heartbeat.every 60m

If you do not need Heartbeat, disable it:

openclaw config set agents.defaults.heartbeat.every 0m

What happened to HEARTBEAT.md?

If you have read older OpenClaw guides, there is one major change here.

In earlier versions, the list of background checks lived in HEARTBEAT.md. In 2.0, that file was retired: OpenClaw no longer reads it, and Heartbeat instructions now live in the system automation’s scratch space.

If you are upgrading from an older version, run:

openclaw doctor --fix

Doctor creates or updates the system monitor for Heartbeat, moves instructions from HEARTBEAT.md into scratch, converts valid entries from the old tasks: block into regular Automations, archives the original file, and removes it from the workspace.

Find the system Heartbeat in the automation list:

openclaw automations list --all

It appears as Heartbeat (agent-id). You can view or edit its scratch with:

openclaw automations scratch <jobId>
openclaw automations scratch <jobId> --set "..."
openclaw automations scratch <jobId> --file notes.md
openclaw automations scratch <jobId> --unset

Here is an example of my scratch:

# Heartbeat checklist
- Quickly check whether there is anything urgent in my inbox
- Review calendar events for the next 2 hours
- If a task is blocked, note exactly what is missing

# When you should not message me proactively
- Do not message me about things that have not changed
- Do not remind me about anything I asked you to postpone
- Do not check work matters on weekends
- Maximum 3 unsolicited messages per day

The agent can also update its own scratch during Heartbeat or when you explicitly ask it to.

If scratch exists but is effectively empty — only headings, comments, or empty checkboxes — OpenClaw skips that run to avoid wasting an API call. If there is no scratch at all, Heartbeat can still operate using its built-in instruction.

Automations: scheduled tasks

Heartbeat is for periodic checks. An Automation runs a specific task at a defined time or on a recurring schedule.

Example: a morning briefing at 7:00 AM Kyiv time. Replace <chat-id> with the Telegram chat ID you want to use:

openclaw automations create "0 7 * * *" "Generate a briefing: weather, calendar, important emails." --name "Morning briefing" --tz "Europe/Kyiv" --session isolated --announce --channel telegram --to "<chat-id>"

View the list and current status:

openclaw automations list
openclaw automations status

Manage a specific job:

openclaw automations get <jobId>
openclaw automations edit <jobId> --message "Updated prompt"
openclaw automations enable <jobId>
openclaw automations disable <jobId>
openclaw automations run <jobId>
openclaw automations runs <jobId> --limit 50
openclaw automations remove <jobId>

You can also create and edit Automations through Control UI, where you can see their schedule, status, and run history.

For recurring schedules that fire at the top of every hour, such as 0 * * * *, OpenClaw may automatically shift the run by up to five minutes to reduce load spikes. If exact timing matters, add --exact.

Ideas for Automations:

• A weekly report every Monday at 9:00 AM
• Product-price monitoring twice a day
• An automatic workspace backup every day at 3:00 AM
• An evening Reddit or Hacker News digest

Hooks: reacting to events

Hooks run in response to specific events. Heartbeat is periodic, while Automations run on a schedule.

For example:

• Session reset or automatic reset → save the recent conversation fragment through session-memory.
• Gateway startup → run instructions from BOOT.md through boot-md.
• A command such as /new or /reset → record the event through command-logger.

You do not need every built-in Hook. Review the list, understand what each one does, and enable only the ones you actually need.

See what is enabled:

openclaw hooks list
openclaw hooks info <hook>
openclaw hooks check

Enable or disable a Hook:

openclaw hooks enable session-memory
openclaw hooks disable command-logger

For Hooks, I would use the CLI: it makes it immediately clear which Hook you are inspecting, enabling, or disabling.

Useful built-in Hooks:

session-memory — after /new, /reset, or auto-reset, saves a recent conversation fragment into a workspace memory file.

command-logger — records command events in JSONL. It logs control events but does not replace a full record of the agent’s shell commands.

boot-md — runs instructions from BOOT.md when Gateway starts. This Hook does not use BOOTSTRAP.md.

By default, session-memory saves the recent conversation to a file such as memory/YYYY-MM-DD-HHMM.md. If you enable llmSlug, the filename can also include a short description of the topic. The file lives in the workspace, and semantic search can later retrieve it by meaning.

How the three mechanisms fit together

Heartbeat is a periodic check performed by the system monitor. It fits questions such as “Has anything important happened?”

Automations are independent scheduled jobs with their own state and run history.

Hooks react to events such as session resets, Gateway startup, commands, and other events supported by a specific Hook.

This keeps periodic checks, scheduled work, and event-driven reactions separate instead of stuffing everything into one giant prompt.

Costs depend on the model, run frequency, and context. Instead of relying on universal estimates such as “$0.01 per run,” watch your actual spending in Usage and avoid running background checks more often than necessary.

My hands-on example

Theory matters, but this is easier to explain with a real example from my own use. It shows why an agent can be useful both for work and for hobbies.

I play Path of Exile, a complex ARPG with a deep build system where every upgrade needs to be weighed carefully. New league, new build. I was playing Exsanguinate/Reap Trickster and wanted to understand what I should improve to get closer to top players.

I sent Jarvis a link to my profile on poe.ninja and asked: “What should I change in my build to improve DPS and survivability?”

The first attempt was not especially useful. The agent tried to open poe.ninja directly, but the site renders through JavaScript, so ordinary web_fetch could not extract the data. Jarvis said so immediately instead of making things up: without a browser or API, it could not compare my profile with top builds. It still gave me some general advice — gem-level scaling, cluster jewels, aura setup, spell suppression — but those were exactly that: general recommendations you could find in any guide.

So I tried a different approach. At that point I still did not know about the agent’s built-in browser, which can work with JavaScript-heavy sites. I sent Jarvis my Path of Building code instead — a long encoded string containing essentially everything: passive tree, gear, gems, aura settings. In other words, a full snapshot of the character.

Jarvis decoded the PoB string, analyzed the build, and produced a detailed breakdown with concrete numbers:

What it found

DPS: Combined DPS ~5.4M, 100% crit with a 4.98x multiplier. That part looked fine.

Survivability was where things got interesting:

• Cold Resist 62%, Lightning 60% — both below cap. That is a serious weakness.
• Chaos Resist -45% — chaos damage can tear the character apart.
• Only 3,043 Life — critically low for level 94.
• Negative mana (-129) — some of the auras cannot actually run.

Specific problems I might have missed myself

Watcher’s Eye with a Pride modifier — but I was not using Pride. A dead modifier taking up space on one of the most expensive jewels in the build.

Level 2 Enlighten was too weak to fit all the aura reservations. I needed at least level 3, ideally 4.

Kikazaru gave curse reduction, but the ring itself was weak. If curses were not the main problem, a rare ring with resistances, life, and crit multi would be better.

Hrimsorrow was convenient for physical-damage conversion, but it provided no life and no offensive stats.

When I explained that my resistances were fine with one aura active — the problem was simply that all the auras did not fit into the mana reservation — Jarvis immediately understood the priority: “Then the plan is simple: Enlighten 4 first, then finish the resistances around the new aura setup.” In other words, it understood what should be upgraded first.

I also asked about farming strategies for the league. Jarvis did not pretend to know current prices when it could not verify them through web search, but its reasoning was sensible: “Influencers show their best runs, not their average ones. If you tried a strategy once and saw no result, the entry threshold may genuinely be high. For your current gear, that can be a trap. The best strategy is the one you can run quickly and without dying. Speed > theoretical loot.”

That is the kind of advice you would normally get from an experienced player after a long discussion on Reddit or Discord. Here it took a few Telegram messages, about a minute, and the answer was based on actual numbers from my own build.

Why does this example matter?

It showed me that Jarvis becomes much more useful when it works with my own data. With a general question, I got general advice. Once I gave it the PoB code, it was analyzing my actual character, found issues, and helped prioritize the next upgrades. Tasks like this are why I spent the time setting up OpenClaw in the first place.

Your first week with OpenClaw

This is what I learned during my first week with OpenClaw — and what I wish I had known on day one.

Days 1–2: just talk to the agent and get used to it

Do not try to automate everything immediately. For the first couple of days, simply talk to the agent and give it ordinary work: summarize something, analyze a file, prepare a draft, find information. After a few days, you will see which tasks it genuinely simplifies and where it only adds extra steps.

Do two things early: install Gateway as a service with openclaw gateway install and run openclaw security audit. That way Gateway will not stop when you close the terminal, and the audit will catch problems in the main security settings.

Days 3–4: add tools one at a time

Once you understand how the agent behaves on your own tasks, start adding tools one by one. Web Search, Calendar, Gmail — not everything in a single evening. If something breaks, this makes the cause much easier to find.

For basic web research, web_search is enough. Enable Browser when you need JavaScript, account login, or interaction with a website, and preferably use a separate browser profile for it.

Check openclaw hooks list and keep only the Hooks whose purpose you understand.

Days 5–7: build your first Automation

For the first Automation, I would choose something simple and easy to verify — a morning briefing, for example. Once it works reliably for a few days, move on to more complex workflows.

Do not overcomplicate Heartbeat either. Start with a frequency that fits one specific task, keep the scratch short, and watch Usage. Then you will know whether you need a different model or a separate Automation.

Finish one workflow properly

Pick one workflow and make it reliable enough that you know what to do when it fails. One dependable process is more useful than ten half-finished ones.

Treat OpenClaw like a new employee with significant permissions: start with the minimum access it needs, then expand that access only after you have seen how the agent behaves on real tasks.

Conclusion

After all these tests, I see OpenClaw as a tool that gives an AI model access to files, commands, and memory. It became genuinely useful to me when Jarvis started working with my PoB, my files, and other concrete data.

Version 2.0 made the first run easier: onboarding can detect existing AI access, Control UI is more practical for day-to-day work, and Gateway can run as a service. The defaults are safer too. OpenClaw is developing very quickly, so I would always compare commands from older guides with the current documentation.

I would define the agent’s access boundaries from the start. Review Skills and Plugins before installing them, give Browser only the permissions it actually needs, and do not expose Gateway to the network without a reason. If the agent can access the browser, files, and shell, I want to know exactly what it can do without asking me first.

I would start the same way again: install OpenClaw, complete BOOTSTRAP, and give Jarvis one real task from my own work. If it is useful, add one tool, one Automation, and expand from there. After a few days, you will know whether an agent like this belongs in your everyday workflow.

If you still have questions, leave them in the comments. I will update this guide when OpenClaw changes in ways that materially affect installation, setup, or how the agent works.