OpenClaw Setup Guide for Beginners (Step-by-Step)

TL;DR: Install OpenClaw with npm install -g openclaw, run openclaw setup to configure your API key, start the gateway with openclaw gateway run, create your SOUL.md and AGENTS.md files, then type openclaw to open the chat interface. The whole process takes under 20 minutes.

OpenClaw is one of the fastest ways to get a self-hosted AI agent running on your own machine. You bring the API key, you own the setup, and you get a fully configurable agent that follows rules you write yourself.

The problem most beginners hit is not a hard one. It is a sequence problem. Every step in the setup chain depends on the one before it. Skip the gateway and the agent won’t respond.

Forget to write SOUL.md and the agent has no personality to draw from. Miss the PATH issue after install and you’ll spend an hour wondering why the command is not found.

This guide walks you through the full setup flow in the right order. If you hit a wall on the first run, there is a section at the end of this article that covers the three most common first-run failures and exactly what to do about each one.

If you would rather skip the self-hosting entirely, ClawTrust is a managed OpenClaw service that handles installation, gateway management, and uptime for you.

It is worth considering if you are not comfortable with Node.js tooling or do not want a terminal running 24/7.

One more note before you start: OpenClaw runs a daily reset at 4 AM by default. That means the agent’s short-term memory clears each night.

If you want sessions to carry over, you will need to set up permanent memory setup before you rely on the agent for anything stateful. For now, just know the reset exists.

What You Need Before You Install OpenClaw

You need three things: Node.js 20 or higher, an API key from a supported model provider, and a terminal you are comfortable leaving open.

The official Node.js download page (https://nodejs.org/en/download/) has installers for Windows, macOS, and Linux. Grab the LTS version labeled 20.x or higher.

When the installer finishes, open a terminal and run node --version to confirm. You should see something like v20.11.0.

If you are using Ollama instead of a cloud API key, install Ollama first and make sure a model is pulled and running locally before you start the OpenClaw setup wizard.

How to Install OpenClaw and Run the Setup Wizard

Run one command to install, then one command to configure. The setup wizard handles the rest and creates your config file automatically.

Open a terminal and run:

npm install -g openclaw

This installs OpenClaw globally so the openclaw command is available from any directory. Once the install finishes, run:

openclaw setup

The setup wizard will ask for your model provider and your API key. Enter the key when prompted. When the wizard finishes, it creates a configuration file at ~/.openclaw/openclaw.json.

A minimal version of that file looks like this:

{
  "model": "claude-3-5-sonnet-20241022",
  "provider": "anthropic",
  "apiKey": "sk-ant-your-key-here",
  "gatewayPort": 3000,
  "resetTime": "04:00"
}

The resetTime field is where the 4 AM daily reset is configured. You can change this to any time that fits your workflow.

The gatewayPort field controls which local port the OpenClaw gateway listens on.

If after install you get “command not found” when running openclaw setup, the npm global bin directory is not in your PATH. On macOS and Linux, running npm config get prefix shows you the prefix path.

Add /bin to your PATH in ~/.bashrc or ~/.zshrc. On Windows, npm global packages go to %APPDATA%\npm. Add that to your System PATH in Environment Variables.

How to Start the OpenClaw Gateway

The gateway is a local server that must stay running in a terminal for your agent to function. Without it, all agent commands will fail silently.

In a terminal window you can leave open, run:

openclaw gateway run

You will see a message confirming the gateway is listening on the configured port (default: 3000). Do not close this terminal. The gateway needs to stay running for the duration of any agent session.

If you are on macOS or Linux and want to run the gateway in the background without keeping a terminal open, you can use a process manager like pm2. Install it with npm install -g pm2, then run pm2 start "openclaw gateway run" --name openclaw-gateway. This keeps the gateway alive even after you close the terminal window.

For beginners, keeping the terminal window open is fine. Just treat it like a server process that needs to run alongside your work.

How to Write Your SOUL.md File

SOUL.md is the first file you write. It sets the agent’s personality, tone, and core identity. Without it, the agent has no character to draw from.

Create the file at the root of whichever directory you plan to run OpenClaw from. The agent loads SOUL.md from the current working directory when it starts.

Here is what a minimal SOUL.md looks like before you customize it:

Before (bare minimum):

You are a helpful assistant.

After (a more useful starting point):

# Agent Identity

You are a focused research assistant. Your job is to help the user gather information, summarize sources, and organize findings clearly.

## Personality

- Direct and concise. No unnecessary filler.
- Ask clarifying questions when the task is ambiguous.
- Always cite your sources when summarizing external content.

## Boundaries

- Do not make up information. If you do not know something, say so.
- Stay on task. If the user goes off-topic, gently redirect.

The second version gives the agent enough context to behave consistently across a session. You can expand it with domain-specific knowledge, preferred formats, or rules about what the agent should never do.

Start simple. You can always add more to SOUL.md after you have seen how the agent behaves in practice.

How to Write Your AGENTS.md File

AGENTS.md is the operational rules file. It tells the agent what tasks it is allowed to perform and how to approach each one.

Where SOUL.md defines who the agent is, AGENTS.md defines what it does. A minimal AGENTS.md might look like this:

# Agent Capabilities

## URL Summarization

When asked to summarize a URL, fetch the page content and return a 3-5 sentence summary. Include the page title and the main argument or purpose of the page.

## Research Tasks

When asked to research a topic, search for at least 3 sources, summarize each one, and identify points of agreement and disagreement across sources.

## Writing Assistance

When asked to write or edit content, match the tone of any existing text provided. Ask for a target word count before starting longer pieces.

Keep the rules action-oriented. Each section should describe a task type and the specific behavior you want from the agent when that task comes up.

For keeping costs in check, writing tight AGENTS.md rules that scope tasks clearly is one of the most effective strategies. An agent with vague instructions tends to over-fetch and over-generate, which adds up quickly on a per-token billing model.

How to Run Your First Test Session

Run openclaw in the same directory as your SOUL.md and AGENTS.md files. The chat interface opens and the agent loads your config automatically.

Make sure the gateway is still running in another terminal, then in your working directory run:

openclaw

The chat interface opens in the terminal. Send this message first:

Hello, what can you do?

If the agent responds with a description of its capabilities (pulled from your AGENTS.md), the setup is working. That is your confirmation that SOUL.md loaded, AGENTS.md loaded, the gateway is running, and the API key is valid.

For your first real task, ask the agent to summarize a URL:

Can you summarize https://nodejs.org/en/about/

The agent should fetch the page and return a summary based on the rules you wrote in AGENTS.md. If it does, your OpenClaw installation is fully functional.

If the agent does not respond or throws an error, skip ahead to the troubleshooting section below.

What to Do When OpenClaw Does Not Work on the First Try

Most first-run failures come from three causes: PATH issues after install, the gateway not running, and an invalid API key. Each one has a clear fix.

Start by checking which error you are seeing:

1. “command not found” after running openclaw – The npm global bin directory is not in your PATH. Run npm config get prefix to find the bin path, then add it to your PATH environment variable. Restart your terminal and try again.
2. Agent opens but does not respond to messages – The gateway is not running. Open a new terminal, run openclaw gateway run, and try the chat again.
3. Agent responds with a 401 error – Your API key is invalid or was entered incorrectly during setup. Open ~/.openclaw/openclaw.json, check the apiKey field, and correct it. Make sure there are no extra spaces or missing characters.
4. Agent starts looping on a task and won’t stop – This is a known behavior when the agent gets stuck on an ambiguous or circular task. The detailed fix is covered in this guide on how to stop agent loops.
5. SOUL.md not loading – Make sure you are running openclaw from the same directory where your SOUL.md file lives. The agent looks for SOUL.md in the current working directory, not in your home directory.

A broader troubleshooting guide covers additional error scenarios including gateway crashes, model provider timeouts, and AGENTS.md parsing errors.

If you are still stuck after working through the three common fixes above, the ClawTrust managed option removes the self-hosting layer entirely and gives you a pre-configured OpenClaw environment with support included.

Frequently Asked Questions

The most common questions about OpenClaw setup cover model compatibility, the daily reset, gateway management, and how to handle updates.

Does OpenClaw work with OpenAI models or only Anthropic?

OpenClaw supports Anthropic (Claude models), OpenAI (GPT-4 and later), and local models via Ollama. During the openclaw setup wizard, you select your provider and enter the corresponding API key. You can switch providers later by editing ~/.openclaw/openclaw.json directly.

What does the 4 AM reset actually do?

The reset clears the agent’s short-term session memory at the configured time each day. Any context from previous sessions is gone after the reset. Files you have created, SOUL.md, and AGENTS.md are not affected. Only the in-session memory is cleared. If you need memory to persist across sessions, follow the permanent memory setup guide.

Can I run multiple agents with different SOUL.md files?

Yes. Because OpenClaw loads SOUL.md from the current working directory, you can have different agents in different folders. Create a separate directory for each agent, write a unique SOUL.md and AGENTS.md in each one, and run openclaw from the relevant directory when you want that specific agent.

Is there a way to run the gateway without keeping a terminal open?

On macOS and Linux, use pm2 or screen to run the gateway as a background process. On Windows, you can run it as a background task via Task Scheduler or use nohup openclaw gateway run & in WSL. For a fully managed experience without any of this, ClawTrust at https://crownmediacreative.com/ClawTrustAI handles gateway uptime automatically.

How do I update OpenClaw after it is installed?

Run npm install -g openclaw again. npm will fetch the latest version and overwrite the existing global install. Your ~/.openclaw/openclaw.json config is not touched during updates, so your API key and settings stay intact.

How much does it cost to run OpenClaw per day?

Cost depends entirely on your model provider and how much you use the agent. Anthropic and OpenAI both bill per token. A light-use day (a few summaries, some research tasks) typically costs under $0.50 on Claude Sonnet or GPT-4o Mini. Writing specific, scoped AGENTS.md rules keeps the token count down. The full breakdown is in the guide on keeping costs in check.

Quick Takeaways: – Install with npm install -g openclaw, configure with openclaw setup – The gateway (openclaw gateway run) must stay running in a separate terminal during every session – SOUL.md sets personality, AGENTS.md sets task rules. Both load from your current working directory – Test with “Hello, what can you do?” before attempting any real tasks – The 4 AM daily reset clears short-term memory. Use permanent memory setup if you need persistence – Most first-run failures are PATH issues, a stopped gateway, or an incorrect API key – ClawTrust (https://crownmediacreative.com/ClawTrustAI) is the managed option for anyone who does not want to self-host