This walkthrough gets OpenClaw running on macOS or Linux in about five minutes. You will check prerequisites, run one install command, answer three onboarding questions, verify the install, and send your first message to a live agent. No Docker, no Windows detour, no configuration rabbit holes. This is the straight path from empty terminal to working agent.
If you want to compare install methods (curl vs Docker vs hosted), see our OpenClaw installation guide. For a broader overview of what installation involves, see our OpenClaw installation overview. This article is the procedural walkthrough for the fastest path.
In This Article
- What You Need Before You Start
- Step 1: Check Your Node.js Version
- Step 2: Run the Install Command
- Step 3: Complete the Onboarding Wizard
- Step 4: Verify the Installation
- Step 5: Run Your First Agent Command
- If Something Went Wrong
- What to Do Next
- Frequently Asked Questions
- Key Takeaways
What You Need Before You Start
You will spend roughly five minutes total on a typical connection.
Required:
- A Mac (macOS 13+) or Linux box (Ubuntu 22.04+ or Debian 12+)
- Node.js 22 or higher
- An API key from OpenAI, Anthropic, or another supported provider (have it ready in your clipboard before Step 3)
- 4 GB of free RAM and about 10 GB of disk space
Not covered in this walkthrough:
- Windows installs (you need WSL2; see the installation guide for Windows steps)
- Docker installs (see our Docker deployment guide)
- One-click hosted installs (see our Hostinger setup walkthrough)
If you are not sure your machine qualifies, our hardware requirements guide has the full specs by deployment scenario.
Step 1: Check Your Node.js Version
Time: 30 seconds
Open a terminal and run:
node --version
You should see v22.x.x or higher. If you see v20, v18, or “command not found”, install or update Node.js before moving on.
On macOS (with Homebrew):
brew install node
On Ubuntu or Debian:
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs build-essential
Run node --version again. When you see v22 or higher, move to Step 2.
Step 2: Run the Install Command
Time: 1-3 minutes
In the same terminal, run the install script:
curl -fsSL https://openclaw.ai/install.sh | bash
The script will:
- Download the OpenClaw package
- Install it globally via npm
- Create a configuration directory at
~/.openclaw/ - Launch the interactive onboarding wizard
You will see progress output as dependencies install. The download and install step typically finishes in under two minutes on a fast connection. Leave the terminal focused. As soon as the install completes, the wizard starts automatically.
Step 3: Complete the Onboarding Wizard
Time: 1 minute
The wizard asks three questions. Here is what to answer for a first-time install:
Prompt 1: Choose a model provider
? Which model provider would you like to use?
> OpenAI
Anthropic
Google Gemini
Groq
Ollama (local)
We recommend OpenAI if you are not sure. It is the default and has the widest model support. You can switch later by editing ~/.openclaw/config.json.
Prompt 2: Enter your API key
? Paste your API key:
Paste the key from your clipboard. The wizard masks the input, so you will not see the characters. Press Enter.
Prompt 3: Choose a Gateway port
? Which local port should the Gateway listen on? (3000)
The Gateway is the local process that routes your requests to the model provider. Press Enter to accept the default port 3000 unless something else on your machine is already using it.
When you see a success message like OpenClaw installed. Run 'openclaw' to start., the wizard is done.
Step 4: Verify the Installation
Time: 15 seconds
Confirm the openclaw command is on your PATH:
openclaw --version
You should see a version number like 1.8.2. If the command is not found, your shell session may need to reload:
source ~/.zshrc # macOS default
source ~/.bashrc # Linux default
Then try openclaw --version again. A version number means the binary is installed and your PATH is correct.
Step 5: Run Your First Agent Command
Time: 20 seconds
Installation is done when the agent responds to a real prompt. Run a one-shot message:
openclaw chat "Say hello and tell me which model you are running."
The Gateway starts, your message routes to your chosen provider, and you should see a reply within a few seconds:
Hello. I am running on gpt-4o-mini via OpenClaw.
If you get a response, your install is complete and working end-to-end. Close the terminal; you are done.
If Something Went Wrong
Based on experience supporting OpenClaw deployments, most install failures fall into four buckets. Here’s how to match your symptom to the fix.
node: command not found or Node.js below v22
Install or upgrade Node.js using the commands in Step 1. If you have multiple versions via nvm, activate the right one:
nvm install 22
nvm use 22
nvm alias default 22
Then rerun the install command from Step 2.
EACCES: permission denied during install
npm is trying to write to a system directory. Point it at your home directory instead:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
(Use ~/.zshrc on macOS if zsh is your default shell.) Then rerun Step 2.
openclaw: command not found after a clean install
Your shell session has not reloaded the PATH. Run:
source ~/.zshrc # macOS
source ~/.bashrc # Linux
If the command is still missing, check that the binary exists:
find ~ -name "openclaw" -type f 2>/dev/null | head -5
If you see a path under ~/.npm-global/bin/openclaw or /usr/local/bin/openclaw, your PATH is not picking it up. Add the containing directory to your shell profile and source it again.
First agent command hangs or times out
The Gateway could not reach the model provider. Check three things:
- Your API key is correct. Edit
~/.openclaw/config.jsonand paste a fresh key. - You have network access. Try
curl -v https://api.openai.comto confirm. - Port 3000 is free. If another process is using it, change the Gateway port in the same config file.
Rerun the Step 5 command.
What to Do Next
Your OpenClaw install is working. To turn it into a useful assistant:
- Configure your workspace. Personality, memory, and daily behavior live in workspace files. Our 10-step setup guide walks through each file.
- Connect Telegram or another messenger so you can chat with your agent from anywhere. Covered in the setup guide.
- Enable the heartbeat, a 30-minute cycle that lets the agent take proactive actions on your behalf.
- Tune model routing. Pick which model handles which task to control cost and quality. See our OpenClaw API costs guide.
If you plan to run OpenClaw on a server rather than your laptop, switch to a Docker install when you move. Our Docker deployment guide has the production setup.
Frequently Asked Questions
How long does this installation take?
Under five minutes on a typical broadband connection, assuming Node.js 22 is already installed. If you need to install Node.js first, add another two to three minutes.
Do I need to install Node.js before running the installer?
Yes. Node.js 22 or higher is a hard prerequisite. The install script will fail at the first step if Node is missing or too old. Install it first using the commands in Step 1.
What if I am on Windows?
OpenClaw does not install natively on Windows. You need WSL2 (the Windows Subsystem for Linux), and once WSL2 is set up, the Linux instructions in this walkthrough apply inside your WSL terminal. The full installation guide has the WSL2 setup steps.
What if I want to use Docker instead?
Docker is a separate install path. It gives you isolation and easier updates but adds a few minutes of setup. See our Docker deployment guide for the Compose file and production configuration.
Do I need an API key ready before I start?
Yes. The onboarding wizard in Step 3 requires a key from at least one model provider (OpenAI, Anthropic, Gemini, Groq, or a local Ollama endpoint). Generate the key before you start so you can paste it when prompted.
What do I do if openclaw --version returns “command not found”?
Reload your shell profile: source ~/.zshrc on macOS or source ~/.bashrc on Linux. If that does not work, the install directory is not on your PATH. The troubleshooting section above has the fix.
Can I reinstall if something broke?
Yes. Rerun curl -fsSL https://openclaw.ai/install.sh | bash. The installer is idempotent: it upgrades an existing install or reinstalls if files are missing. Your config at ~/.openclaw/config.json is preserved unless you delete it manually.
Key Takeaways
- OpenClaw installs in about five minutes on macOS or Linux: check Node.js 22+, run one curl command, answer three wizard prompts, verify, and send a first message.
- Have your model provider API key in your clipboard before Step 3. The wizard will block there without it.
- The install is not complete at
openclaw --version. It is complete whenopenclaw chat "..."returns a real agent response. - If you want to compare install methods or use Windows, Docker, or a hosted option, our installation guide covers those paths in depth.
- Installation is separate from setup. Once installed, the setup guide is your next stop.
SFAI Labs
