OpenClaw Setup Guide (Locally)

NOTE: This guide sets up your OpenClaw on your local machine. What that means is that it runs using your device and your laptop/PC has to be active to communicate with it, even via Telegram. If you want to use your OpenClaw on the go, it is recommended you set it up on a VPS.

Getting the Full Documentation (Read This First)

Before you start, bookmark this resource. It gives you the complete, always-up-to-date OpenClaw documentation in a format any AI assistant can read and work with:

context7.com/openclaw/openclaw

This page is maintained by Context7, which tracks the OpenClaw GitHub repository and auto-generates a structured summary of all docs, config options, and CLI commands. You can:

• Read it yourself — the Context7 page has a human-readable summary of everything
• Copy it into ChatGPT, Claude, or any other AI — paste the context summary and ask the AI to help you configure, troubleshoot, or extend your OpenClaw setup
• Grab the raw llms.txt — for advanced use, hit https://context7.com/openclaw/openclaw/llms.txt?tokens=10000 to get a plain-text version you can paste directly into any AI chat

This is especially useful when you hit a problem this guide doesn't cover. Copy the context summary, paste it into your AI of choice, and ask your question. The AI will have the full documentation in its context and can give you accurate, specific answers.

---

Before You Start

Make sure you have all of these before doing anything else:

Keep all API keys private. Treat them like passwords — never share them or paste them in public places.

---

What Is a Terminal?

Several steps below ask you to open a "Terminal" and type commands. A terminal is simply a text window where you give your computer instructions by typing.

• Mac: Press ⌘ Space, type Terminal, press Enter
• Windows: Press the Windows key, type PowerShell, press Enter
• Linux: Press Ctrl + Alt + T

A window appears with a blinking cursor. You can paste commands into it (⌘V on Mac, right-click or Ctrl+Shift+V on Windows/Linux) and press Enter to run them.

---

What Is vim?

Later steps ask you to edit a file using vim. vim is a text editor that runs inside the terminal. Here is everything you need to know:

• Type vim ~/.openclaw/openclaw.json and press Enter to open the file
• Press i to enter editing mode — you will see -- INSERT -- at the bottom
• Use the arrow keys to move around and make your changes
• When done, press Escape, then type :wq and press Enter to save and quit
• If you made a mistake and want to quit without saving, press Escape, then type :q! and press Enter

If vim feels uncomfortable, you can use nano instead (simpler for beginners), or open the file in any code editor like VS Code by navigating to ~/.openclaw/openclaw.json.

---

Part 1 — Install OpenClaw

Step 1 — Install Node.js

OpenClaw needs Node.js (version 22 or newer) to run. Think of it like installing a required app before another app can work.

1. Go to nodejs.org
2. Click the big green Download button
3. Open the downloaded file and run the installer — accept all defaults

After the installer finishes, close and reopen your Terminal before moving on. Skipping this is the most common reason the next step fails.

Check it worked:

node --version

You should see something like v22.x.x. Any number 22 or above is fine.

If you see "command not found": Restart your computer and try again.

---

Step 2 — Install OpenClaw

npm install -g openclaw@latest

A lot of text scrolls by — that's normal. Wait until the blinking cursor reappears.

Confirm it worked:

openclaw --version

If you see "permission denied": Add sudo to the very front of the command and try again. Your computer will ask for your login password.

---

Step 3 — Run the Setup Wizard

This is where OpenClaw configures itself. You have two paths: interactive (the wizard asks you questions) or non-interactive (you provide everything up front in one command). Most beginners should use interactive.

---

Path A — Interactive Setup (Recommended for Beginners)

openclaw onboard --install-daemon

The wizard walks you through the setup step by step. Here is exactly what you will see and what to do at each prompt:

---

Prompt: Choose your authentication method

The wizard lists the available providers. You will see something like:

? How would you like to authenticate?
  > Anthropic API key
    OpenAI API key
    Google Gemini API key
    OpenRouter API key
    GitHub Copilot (OAuth)
    ...

Use the arrow keys to select your provider and press Enter. See Part 2 of this guide for how to get each key before running this wizard.

---

Prompt: Paste your API key

? Paste your Anthropic API key:

Paste the key you copied from your provider's website and press Enter. The key will not be visible as you type — that's normal and intentional.

---

Prompt: Gateway port

? Gateway port: (18789)

Just press Enter to accept the default port 18789. Only change this if you know port 18789 is already being used by something else on your computer.

---

Prompt: Gateway bind address

? Bind address: (loopback)

Press Enter to accept loopback. This means the gateway only listens on your own machine, which is the secure default. Only change to 0.0.0.0 if you specifically need to access it from other devices on your network.

---

Prompt: Install as a system service (daemon)

? Install gateway as a system service? (Y/n)

Type Y and press Enter. This is the --install-daemon behaviour — it makes the gateway start automatically every time your computer boots, so you never need to start it manually.

---

Prompt: Workspace location

? Workspace directory: (~/.openclaw/workspace)

Press Enter to accept the default. This is where OpenClaw stores your agent's working files.

---

When the wizard finishes, it installs the daemon and prints a confirmation. You should see something like:

✓ Gateway installed as system service
✓ Gateway started
✓ Configuration saved to ~/.openclaw/openclaw.json

Run `openclaw doctor` to verify your setup.

---

Path B — Non-Interactive Setup (One Command, No Prompts)

If you already have your API key and want to skip every prompt, use this instead. Replace the placeholder with your actual key:

For Anthropic:

openclaw onboard --non-interactive --auth-choice anthropic-api-key --anthropic-api-key "sk-ant-YOUR-KEY" --gateway-port 18789 --gateway-bind loopback --install-daemon

For Google Gemini:

openclaw onboard --non-interactive --auth-choice gemini-api-key --gemini-api-key "AIzaSy-YOUR-KEY" --gateway-port 18789 --gateway-bind loopback --install-daemon

For OpenAI:

openclaw onboard --non-interactive --auth-choice openai-api-key --openai-api-key "sk-proj-YOUR-KEY" --gateway-port 18789 --gateway-bind loopback --install-daemon

For OpenRouter:

openclaw onboard --non-interactive --auth-choice openrouter-api-key --openrouter-api-key "sk-or-v1-YOUR-KEY" --gateway-port 18789 --gateway-bind loopback --install-daemon

Note on zsh (Mac default shell): Do not split these commands across multiple lines with backslashes when pasting into the terminal. Always paste as a single line. Backslash line continuations break in zsh.

---

After Either Path — Verify the Setup

openclaw doctor

You want to see mostly green ticks or "OK" messages. Some yellow warnings are normal at first. Red errors need to be fixed — run openclaw doctor --fix to automatically resolve the most common ones.

---

Part 2 — Choose Your AI Provider

OpenClaw supports several AI providers. You need at least one. Pick the one that suits you best — or set up more than one for flexibility.

Quick comparison:

---

Option A — Anthropic (Claude)

Recommended starting provider for most people.

Getting your key

1. Go to console.anthropic.com
2. Sign up or log in
3. Click API Keys in the left sidebar
4. Click Create Key, give it a name, and copy it immediately — you won't see it again

Your key looks like: sk-ant-api03-...

Adding it to OpenClaw

Open your config:

vim ~/.openclaw/openclaw.json

Press i, then add or update the file to look like this:

{
  env: {
    ANTHROPIC_API_KEY: "sk-ant-api03-YOUR-KEY-HERE"
  },
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5"
      }
    }
  }
}

Press Escape, type :wq, press Enter to save.

Or use the CLI shortcut instead of editing the file:

openclaw onboard --auth-choice anthropic-api-key
openclaw models set anthropic/claude-sonnet-4-5

Available Anthropic models:

---

Option B — Google Gemini Flash 2.5

Best choice if you want a free daily quota to get started at no cost.

Getting your key

1. Go to aistudio.google.com
2. Sign in with your Google account
3. Accept the Terms of Service when prompted
4. Click Get API Key in the left sidebar
5. Click Create API Key — if you have no project yet, choose "Create key in new project"
6. Copy the key immediately

Your key looks like: AIzaSy...

Adding it to OpenClaw

Open your config:

vim ~/.openclaw/openclaw.json

Press i, then set it up like this:

{
  env: {
    GEMINI_API_KEY: "AIzaSy-YOUR-KEY-HERE"
  },
  agents: {
    defaults: {
      model: {
        primary: "google/gemini-2.5-flash-preview"
      }
    }
  }
}

Press Escape, type :wq, press Enter to save.

Or via CLI:

openclaw onboard --auth-choice gemini-api-key
openclaw models set google/gemini-2.5-flash-preview

Available Google Gemini models:

About the free tier: Google gives you a free daily request quota via AI Studio keys. If you exceed it, you get a 429 error — wait until the next day or add billing in Google Cloud Console.

---

Option C — OpenAI (GPT)

Getting your key

1. Go to platform.openai.com/api-keys
2. Sign up or log in
3. Click Create new secret key, give it a name
4. Copy the key immediately — OpenAI shows it only once

Your key looks like: sk-proj-...

Add a payment method under Billing in the sidebar before using the API. New accounts get a small amount of free trial credits.

Adding it to OpenClaw

Open your config:

vim ~/.openclaw/openclaw.json

Press i, then set it up like this:

{
  env: {
    OPENAI_API_KEY: "sk-proj-YOUR-KEY-HERE"
  },
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-5.2"
      }
    }
  }
}

Press Escape, type :wq, press Enter to save.

Or via CLI:

openclaw onboard --auth-choice openai-api-key
openclaw models set openai/gpt-5.2

Available OpenAI models:

---

Option D — OpenRouter (All Providers via One Key)

Best choice if you want model flexibility, automatic fallbacks, or access to free models without managing multiple provider accounts.

OpenRouter is a gateway that gives you access to models from Anthropic, Google, OpenAI, Meta, Mistral, and many more — all through one key and one bill.

Getting your key

1. Go to openrouter.ai
2. Click Sign up — Google, GitHub, or email all work
3. Go to openrouter.ai/settings/keys
4. Click Create Key, give it a name, and copy it immediately — shown only once
5. Go to the Credits page and add at least $5 for paid models (free models need no credits)

Your key looks like: sk-or-v1-...

Adding it to OpenClaw

Open your config:

vim ~/.openclaw/openclaw.json

Press i, then set it up like this:

{
  env: {
    OPENROUTER_API_KEY: "sk-or-v1-YOUR-KEY-HERE"
  },
  agents: {
    defaults: {
      model: {
        primary: "openrouter/anthropic/claude-sonnet-4-5",
        fallbacks: [
          "openrouter/google/gemini-2.5-flash-preview",
          "openrouter/openai/gpt-5.2-mini"
        ]
      }
    }
  }
}

Press Escape, type :wq, press Enter to save.

Or via CLI:

openclaw onboard --auth-choice openrouter-api-key
openclaw models set openrouter/anthropic/claude-sonnet-4-5

OpenRouter model format: Always prefix with openrouter/, then the provider, then the model. So Claude via OpenRouter is openrouter/anthropic/claude-sonnet-4-5 — not anthropic/claude-sonnet-4-5.

Popular OpenRouter models:

Browse all models at openrouter.ai/models.

---

Using Multiple Providers at Once

Hold keys for more than one provider and use fallbacks across them. If your primary model hits a rate limit or goes down, OpenClaw automatically tries the next one.

{
  env: {
    ANTHROPIC_API_KEY: "sk-ant-api03-YOUR-KEY-HERE",
    GEMINI_API_KEY: "AIzaSy-YOUR-KEY-HERE",
    OPENAI_API_KEY: "sk-proj-YOUR-KEY-HERE"
  },
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: [
          "google/gemini-2.5-flash-preview",
          "openai/gpt-5.2-mini"
        ]
      }
    }
  }
}

---

Part 3 — Starting and Running the Gateway

The gateway is the core of OpenClaw. It is a background process that keeps your channels connected, routes messages to your AI model, and runs any scheduled tasks. Understanding how to start, stop, check, and troubleshoot it is essential.

How the Gateway Runs

There are two modes:

Service mode (normal everyday use) — the gateway runs in the background, starts on boot, keeps running even when your terminal is closed. This is what --install-daemon sets up.

Foreground mode (debugging) — the gateway runs in your terminal window and prints everything live. Closing the window stops the gateway. Use this only when something isn't working and you want to see what's happening.

---

Starting the Gateway

If you used --install-daemon during setup, the gateway is already running as a service and starts automatically on boot. You usually don't need to touch it.

To start it as a service manually:

openclaw gateway install --port 18789 --runtime node

To start it in foreground mode for debugging (all output visible):

openclaw gateway --port 18789 --verbose

Force-start if something is already using port 18789:

openclaw gateway --force

---

Checking the Gateway Status

openclaw gateway status

For a deeper scan that includes system-level service checks:

openclaw gateway status --deep

The quickest overall health check (includes model, channels, plugins):

openclaw doctor

You want mostly green ticks. Yellow warnings are usually fine; red errors need attention. Auto-fix most red errors with:

openclaw doctor --fix

---

Stopping and Restarting the Gateway

After any change to your config — adding an API key, changing your model, installing a plugin — you must restart the gateway for the change to take effect.

openclaw gateway restart

To stop it completely:

openclaw gateway stop

---

Watching the Logs

If your bot isn't responding, the logs are always the first place to look:

openclaw logs --follow

This streams everything happening inside the gateway in real time. Press Ctrl+C to stop. Red lines are errors. To see the last 200 lines without following live:

openclaw logs --limit 200

---

The Full Workflow After Editing the Config File

Any time you edit ~/.openclaw/openclaw.json, follow this exact sequence:

openclaw config validate

This checks your JSON for syntax errors before you restart. Fix anything it reports, then:

openclaw gateway restart

Wait about 30 seconds, then:

openclaw doctor

If everything is green, your change is live.

---

Using the Interactive Config Wizard

If editing the JSON file feels daunting, OpenClaw has a separate interactive configuration wizard you can run at any time after the initial setup:

openclaw configure

This opens a menu-driven interface that lets you change settings without touching the JSON file directly.

---

Changing Your Model Without Editing the Config

You can switch models from the command line without opening the config file at all:

openclaw models set google/gemini-2.5-flash-preview

Or add a fallback:

openclaw models fallbacks add openai/gpt-5.2-mini

These commands update the config and take effect after the next restart.

---

Part 4 — Connect Telegram

OpenClaw needs a messaging channel to talk to you. Telegram is the easiest place to start.

Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Send it: /newbot
3. Give your bot a name — for example: My Assistant
4. Give it a username ending in bot — for example: myassistant_bot
5. BotFather replies with a token. Copy it — it looks like 7123456789:AAF-abc123...

Add the Token to OpenClaw

Replace YOUR_TOKEN with the actual token from BotFather:

openclaw channels add --channel telegram --account personal --name "My Bot" --token YOUR_TOKEN

Then restart the gateway:

openclaw gateway restart

Test It

Open Telegram, search for your bot by username, and send Hello. If it replies, everything is working.

If your bot doesn't reply within 30 seconds: Run openclaw logs --follow and look for red errors.

---

Part 5 — Add mem9 (Persistent Memory)

By default OpenClaw forgets everything when a session resets. mem9 gives your assistant permanent cloud memory that survives restarts, resets, and switching computers.

What mem9 gives you

• Your assistant remembers preferences, project context, and past conversations across sessions
• Memory follows you between devices
• A web dashboard at mem9.ai/your-memory to view, manage, and export everything remembered

---

Step 1 — Create a mem9 API Key

curl -sX POST https://api.mem9.ai/v1alpha1/mem9s | jq .

You will see:

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

The string next to "id" is your mem9 API key. Save it somewhere safe immediately. You will need it if you ever switch computers.

Treat this key like a password. Anyone who has it can access your memory.

---

Step 2 — Install the mem9 Plugin

openclaw plugins install @mem9/mem9

---

Step 3 — Check Your OpenClaw Version

openclaw --version

• 2.2.0 or higher → use Step 4A
• Lower than 2.2.0 → use Step 4B

---

Step 4A — Configure mem9 (OpenClaw 2.2.0 or newer)

Replace YOUR_MEM9_API_KEY with the key from Step 1:

jq --arg api_key "YOUR_MEM9_API_KEY" '.plugins.slots.memory = "mem9" | .plugins.entries.mem9 = { enabled: true, config: { apiUrl: "https://api.mem9.ai", apiKey: $api_key } } | .plugins.allow = ((.plugins.allow // []) + ["mem9"] | unique)' ~/.openclaw/openclaw.json > /tmp/oc_tmp.json && mv /tmp/oc_tmp.json ~/.openclaw/openclaw.json

---

Step 4B — Configure mem9 (OpenClaw older than 2.2.0)

Replace YOUR_MEM9_API_KEY with the key from Step 1:

jq --arg api_key "YOUR_MEM9_API_KEY" '.plugins.slots.memory = "mem9" | .plugins.entries.mem9 = { enabled: true, config: { apiUrl: "https://api.mem9.ai", apiKey: $api_key } }' ~/.openclaw/openclaw.json > /tmp/oc_tmp.json && mv /tmp/oc_tmp.json ~/.openclaw/openclaw.json

---

Step 5 — Restart and Verify

openclaw gateway restart

Wait one minute, then verify (replace YOUR_MEM9_API_KEY with your actual key):

curl -sf -H "X-API-Key: YOUR_MEM9_API_KEY" "https://api.mem9.ai/v1alpha2/mem9s/memories?limit=1" && echo "Connected!" || echo "Something went wrong — check your API key"

Connected! means everything is working. A new key with zero memories is completely normal.

---

Step 6 — Import Existing Memory (Optional)

If OpenClaw already has local notes or session history, bring them into mem9 by sending your Telegram bot:

import memories to mem9

Your assistant will scan for local memory files and upload them automatically.

---

Full Config Reference

Your entire configuration lives in one file:

~/.openclaw/openclaw.json

Open it any time with:

vim ~/.openclaw/openclaw.json

Here is a complete example showing all sections together:

{
  // API keys for your AI providers — add whichever you have
  env: {
    ANTHROPIC_API_KEY: "sk-ant-api03-YOUR-KEY-HERE",
    GEMINI_API_KEY: "AIzaSy-YOUR-KEY-HERE",
    OPENAI_API_KEY: "sk-proj-YOUR-KEY-HERE",
    OPENROUTER_API_KEY: "sk-or-v1-YOUR-KEY-HERE"
  },

  // Which model to use and fallbacks if it goes down
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: [
          "google/gemini-2.5-flash-preview",
          "openai/gpt-5.2-mini"
        ]
      },
      // Optional: how often the agent sends a heartbeat
      heartbeat: {
        every: "30m",
        target: "last"
      }
    }
  },

  // Gateway server settings
  gateway: {
    port: 18789,
    bind: "loopback",        // loopback = this machine only; 0.0.0.0 = network-accessible
    reload: { mode: "hybrid" }
  },

  // Channel configuration (Telegram example)
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "allowlist",          // allowlist | open | pairing | disabled
      allowFrom: ["tg:YOUR_TELEGRAM_ID"]
    }
  },

  // Session reset and scope settings
  session: {
    dmScope: "per-channel-peer",      // Isolates conversations per user
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120
    }
  },

  // mem9 memory plugin (added by setup commands in Part 5)
  plugins: {
    slots: { memory: "mem9" },
    entries: {
      mem9: {
        enabled: true,
        config: {
          apiUrl: "https://api.mem9.ai",
          apiKey: "your-mem9-api-key-here"
        }
      }
    },
    allow: ["mem9"]
  }
}

---

Handy Commands to Know

---

Recovery — Switching to a New Computer

On the new computer:

1. Install Node.js from nodejs.org
2. npm install -g openclaw@latest
3. openclaw onboard --install-daemon
4. openclaw plugins install @mem9/mem9
5. vim ~/.openclaw/openclaw.json — add all your API keys
6. Run the mem9 config command from Step 4A using your original mem9 API key
7. openclaw gateway restart

Your memory reconnects instantly because the key points to the same cloud space.

---

Getting Help with Complex Setup

When you run into something this guide doesn't cover, here is the fastest path to an answer:

1. Go to context7.com/openclaw/openclaw
2. Click Copy on the Context Summary
3. Open ChatGPT, Claude, or whichever AI you prefer
4. Paste the context summary at the top of a new chat, then describe your problem

The AI will have the full OpenClaw documentation in context and can give you accurate, specific guidance. This works for any configuration question, error message, or advanced feature you want to set up.

For the raw documentation text (useful for pasting into AI tools that accept longer context):

https://context7.com/openclaw/openclaw/llms.txt?tokens=10000

---

Troubleshooting

---

Useful Links