OpenClaw Setup Guide (Locally)
A complete beginner's guide — no coding experience needed
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:
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=10000to 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:
| What you need | Details |
|---|---|
| A computer | Mac, Windows, or Linux — all three work |
| An internet connection | Needed throughout the whole setup |
| At least one API key | See Part 2 — pick whichever provider suits you |
| About 25 minutes | A little extra if it's your first time on the command line |
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, typeTerminal, pressEnter - Windows: Press the Windows key, type
PowerShell, pressEnter - 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.jsonand pressEnterto open the file - Press
ito 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:wqand pressEnterto save and quit - If you made a mistake and want to quit without saving, press
Escape, then type:q!and pressEnter
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.
- Go to nodejs.org
- Click the big green Download button
- 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
sudoto 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:
| Provider | Best for | Free tier? | Key format |
|---|---|---|---|
| Anthropic | Best overall quality, recommended default | No (pay-as-you-go) | sk-ant-... |
| Google Gemini | Great value, fast, generous free daily quota | Yes | AIza... |
| OpenAI | Widely-used GPT models | No (small trial credits) | sk-proj-... |
| OpenRouter | One key for all providers, model flexibility | Some free models | sk-or-v1-... |
Option A — Anthropic (Claude)
Recommended starting provider for most people.
Getting your key
- Go to console.anthropic.com
- Sign up or log in
- Click API Keys in the left sidebar
- 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:
| Model string | What it is |
|---|---|
anthropic/claude-sonnet-4-5 | Best balance of speed and quality — recommended |
anthropic/claude-opus-4-6 | Most capable, slower, higher cost |
anthropic/claude-haiku-4-5 | Fastest and cheapest, good for simple tasks |
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
- Go to aistudio.google.com
- Sign in with your Google account
- Accept the Terms of Service when prompted
- Click Get API Key in the left sidebar
- Click Create API Key — if you have no project yet, choose "Create key in new project"
- 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:
| Model string | What it is |
|---|---|
google/gemini-2.5-flash-preview | Gemini 2.5 Flash — fast, cost-effective, recommended |
google/gemini-2.5-pro-preview | Gemini 2.5 Pro — more capable, higher cost |
google/gemini-2.0-flash-lite | Lightest and fastest Gemini option |
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
- Go to platform.openai.com/api-keys
- Sign up or log in
- Click Create new secret key, give it a name
- 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:
| Model string | What it is |
|---|---|
openai/gpt-5.2 | Latest GPT-5 series |
openai/gpt-5.2-mini | Faster and cheaper |
openai/gpt-4.1 | Reliable, widely tested |
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
- Go to openrouter.ai
- Click Sign up — Google, GitHub, or email all work
- Go to openrouter.ai/settings/keys
- Click Create Key, give it a name, and copy it immediately — shown only once
- 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 isopenrouter/anthropic/claude-sonnet-4-5— notanthropic/claude-sonnet-4-5.
Popular OpenRouter models:
| Model string | What it is |
|---|---|
openrouter/anthropic/claude-sonnet-4-5 | Claude Sonnet via OpenRouter |
openrouter/google/gemini-2.5-flash-preview | Gemini 2.5 Flash via OpenRouter |
openrouter/openai/gpt-5.2 | GPT-5.2 via OpenRouter |
openrouter/meta-llama/llama-3.3-70b-instruct | Llama 3.3 — free |
openrouter/openrouter/auto | Auto-selects cheapest model for the task |
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
- Open Telegram and search for @BotFather
- Send it:
/newbot - Give your bot a name — for example:
My Assistant - Give it a username ending in
bot— for example:myassistant_bot - 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 --followand 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
| What you want to do | Command |
|---|---|
| Edit the config file | vim ~/.openclaw/openclaw.json |
| Run the interactive config wizard | openclaw configure |
| Validate config before restarting | openclaw config validate |
| Get a specific config value | openclaw config get agents.defaults.model.primary |
| Set a config value | openclaw config set agents.defaults.model.primary "google/gemini-2.5-flash-preview" |
| Restart the gateway | openclaw gateway restart |
| Check gateway status | openclaw gateway status |
| Check overall health | openclaw doctor |
Recovery — Switching to a New Computer
On the new computer:
- Install Node.js from nodejs.org
npm install -g openclaw@latestopenclaw onboard --install-daemonopenclaw plugins install @mem9/mem9vim ~/.openclaw/openclaw.json— add all your API keys- Run the mem9 config command from Step 4A using your original mem9 API key
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:
- Go to context7.com/openclaw/openclaw
- Click Copy on the Context Summary
- Open ChatGPT, Claude, or whichever AI you prefer
- 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
| Problem | What to try |
|---|---|
command not found after installing Node | Close and reopen Terminal, or restart your computer |
permission denied when installing OpenClaw | Add sudo to the start of the command |
| Telegram bot doesn't reply | Run openclaw logs --follow and look for red errors |
| Model not responding | Check your API key is in the config; run openclaw doctor |
| Gateway won't start | Run openclaw gateway --force to clear port 18789 |
| Config changes not taking effect | Always run openclaw gateway restart after editing the config |
| Backslash commands broken in terminal (Mac) | Paste as a single line — zsh doesn't handle \ line continuations from paste |
| mem9 "unreachable" |
Useful Links
| Resource | URL |
|---|---|
| Full OpenClaw docs (for AI assistants) | context7.com/openclaw/openclaw |
| Anthropic API console | console.anthropic.com |
| Google AI Studio (Gemini keys) | aistudio.google.com |
| OpenAI API platform | platform.openai.com/api-keys |
| OpenRouter keys | openrouter.ai/settings/keys |
| OpenRouter model browser | openrouter.ai/models |
| mem9 memory dashboard |