Step-by-step setup

Quick requirements

Prepare:

  • Node.js and npm
  • A terminal or PowerShell
  • Git if you plan to install from source
  • Ollama if you want a local model
  • A local model pulled in Ollama
  • Bot credentials if you plan to connect Discord or Telegram
  • A safe local workspace for testing

OpenClaw's current docs show global installs through npm, pnpm, or bun, with Node recommended for the gateway runtime.

Option 1: Install with the official script

For macOS or Linux:

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

For Windows PowerShell:

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

Then run onboarding:

openclaw onboard --install-daemon

Option 2: Install globally with npm

If you already manage Node yourself:

npm install -g openclaw@latest
openclaw onboard --install-daemon

If the openclaw command is not found after installation, check your global npm path:

npm prefix -g
echo "$PATH"

Add the global npm bin directory to your shell startup file if needed.

Option 3: Install from source

Use this only if you want to inspect or modify OpenClaw itself:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm link --global
openclaw onboard --install-daemon

For most users, the installer or npm global install is simpler.

Run onboarding and install the daemon

The key command is:

openclaw onboard --install-daemon

The onboarding process sets up:

  • LLM provider
  • Local or remote model endpoint
  • Gateway daemon
  • Messaging channels
  • Initial configuration

The daemon keeps OpenClaw running in the background. The docs describe OS-specific service handling: LaunchAgent on macOS, systemd user service on Linux or WSL2, and scheduled-task style setup on native Windows.

Check status with:

openclaw status

Start a basic local chat test with:

openclaw chat "Hello, what can you do?"

Connect OpenClaw to Ollama

OpenClaw uses Ollama's native API, not the OpenAI-compatible /v1 URL. Pull a model first:

ollama pull llama3.3

Test the model endpoint:

curl http://localhost:11434/api/tags

During OpenClaw onboarding, choose Ollama as the provider or set the custom base URL to:

http://localhost:11434

Use this when OpenClaw and Ollama run on the same host environment.

If OpenClaw is running in Docker or another environment that needs to reach Ollama on the host, test:

http://host.docker.internal:11434

For WSL2, test the endpoint from inside WSL before saving it:

curl http://host.docker.internal:11434/api/tags
curl http://127.0.0.1:11434/api/tags

Use the endpoint that returns your model list.

Connect Discord or Telegram

OpenClaw can connect to messaging channels during onboarding or later.

For Discord, you generally need:

  • A Discord bot application
  • Bot token
  • The correct server/channel permissions
  • A private test channel first

For Telegram, you generally need:

  • A bot from BotFather
  • Bot token
  • A private chat or controlled group
  • Clear limits on who can message the bot

Do not connect broad public channels on the first run. Start with a private test channel and low-risk tasks.

Verify it works

OpenClaw is working when openclaw onboard --install-daemon completes, openclaw status shows the runtime is available, and a local model connection returns a response from the same environment where OpenClaw runs. If you connect Discord or Telegram, confirm the bot responds only in a private test channel before adding real users or production workflows.

Next useful actions

After the daemon and model provider work, run one small local task, back up the OpenClaw state directory, and add only one messaging integration at a time. Do not enable public channels, broad file access, or auto-updates until rollback and credential rotation are clear.

Background, planning, and caveats

What OpenClaw is

OpenClaw is an open-source local agent framework that connects an AI model to tools, files, and messaging channels. It is designed to run on your machine or server as a local daemon, with optional integrations for channels such as Discord, Telegram, Slack, WhatsApp, and others.

That makes it more powerful than a chat UI. It also means you should treat installation as an automation runtime, not just an app install.

Questions to answer before installing

  • Do you need local-only models at launch, or will you use remote APIs from day one?
  • Will messaging integrations be enabled immediately or after baseline validation?
  • Is this a personal machine or a shared build host with multiple worker accounts?
  • Do you have a plan for rollback if a gateway or daemon update breaks jobs?
  • Which model/provider costs are already budgeted for this use case?

Approximate U.S. planning cost

  • OpenClaw software itself is open-source and typically free to install.
  • Local hardware: model hosting and task load can require stronger CPU/RAM over time.
  • API/model spend: local Ollama is local compute; remote model providers are usage billed.
  • Optional cloud/VPS: add hourly machine charges and egress if you need remote operation.
  • Developer time: a 30 to 90 minute first-run loop plus ongoing daemon and credential checks.

Cost breakdown

  • Install: $0 software spend
  • Model: local provider compute or provider billed usage
  • Hosting: optional VPS or cloud runtime costs
  • Storage: local workspace and logs
  • Operations: time for updates, onboarding, and rollback rehearsals

Official-source caveats

OpenClaw installation commands are split across installer, npm, and from-source paths. Verify current defaults before scripting:

If openclaw install paths or service names differ from older notes, use the current docs before continuing.

Configuration and local state

OpenClaw uses local configuration and state paths. The docs mention environment variables for custom paths:

  • OPENCLAW_HOME
  • OPENCLAW_STATE_DIR
  • OPENCLAW_CONFIG_PATH

Use defaults unless you have a clear reason to customize. Before major changes, back up your OpenClaw state and config.

If you run OpenClaw as a service account, make sure the service has the right file permissions and does not have access to sensitive directories it does not need.

Credential handling

  • Store bot tokens in secure channel-specific managers, not plain shell history.
  • Rotate tokens when an integration is added or removed.
  • Keep different tokens for local and remote environments if both exist.
  • Avoid pasting full token values into artifacts or bug reports.
  • Limit token scope to the channels and guilds/chats defined for testing.

Filesystem permissions

OpenClaw service behavior depends on writable runtime paths such as:

  • ~/.openclaw (default)
  • OPENCLAW_STATE_DIR
  • OPENCLAW_CONFIG_PATH

Best practice is least-privilege access:

  • Keep service identity and data paths scoped to one user.
  • Verify write access before running openclaw onboard.
  • If the service account is used, confirm read/write scope is restricted to agent state and workspace locations.

Rollback and update guidance

Update guidance from OpenClaw docs:

  • openclaw update
  • openclaw doctor
  • openclaw gateway restart
  • openclaw health

For hard rollback:

  • pin an npm version with npm view openclaw version and install a known version, or
  • pin a git commit in source mode and restart the gateway.

Before enabling auto-update, test update flow with a small noncritical workflow.

Updating OpenClaw

If installed with npm:

npm update -g openclaw

Then check:

openclaw --version
openclaw status

Because local agents can run tools and interact with files, updates matter. Keep the runtime current, especially if you enable messaging integrations or skills.

Security checklist

Before using OpenClaw for real workflows:

  • Start with a private test channel.
  • Use a non-admin account.
  • Limit file access.
  • Review skills before installing them.
  • Do not expose the gateway publicly unless you know what you are doing.
  • Keep bot tokens private.
  • Use local models for sensitive experiments when possible.
  • Keep OpenClaw updated.
  • Back up configuration and state before changing providers.

OpenClaw can execute real actions. Treat it like an automation system with access to your machine.

Red flags

  • Enabling all messaging integrations before a backup and restore strategy is in place.
  • Using root-owned npm installs without checking service write directories.
  • Running daemon updates on a machine with no restore point.
  • Copying bot credentials into project docs or shared shell profiles.

Common problems

openclaw command not found

Check Node and npm:

node -v
npm prefix -g
echo "$PATH"

Add the global npm bin directory to your PATH.

Onboarding cannot reach Ollama

Test from the same environment where OpenClaw runs:

curl http://localhost:11434/api/tags
curl http://host.docker.internal:11434/api/tags

Use whichever endpoint returns your models.

Daemon does not start

Check:

openclaw status

Then rerun:

openclaw onboard --install-daemon

If permissions changed, confirm the service account can read and write the OpenClaw state directory.

Discord or Telegram does not respond

Check the bot token, channel permissions, and whether the gateway is running. Start with one integration at a time before adding more.

Bottom line

The simplest reliable setup is: install OpenClaw with the official script or npm install -g openclaw@latest, run openclaw onboard --install-daemon, connect Ollama through its native base URL, and test with one private messaging channel before expanding.

Keep the daemon, tokens, config files, and skills under control. OpenClaw is useful because it can act locally; that same capability makes careful setup important.

For predictable operations:

  • run openclaw update first on a disposable path,
  • verify openclaw doctor results,
  • then run onboarding or integrations in a controlled project.