OpenClaw: A Practical Guide to Running a Local Autonomous AI Agent

You are only young once, but you can stay immature indefinitely, Ogden Nash

Introduction

OpenClaw is a free, open-source autonomous AI agent that runs on your own hardware and connects to messaging platforms through a centralized Gateway. It is not a chat UI bolted onto an API: it is a persistent agent runtime with a workspace, skills, scheduled jobs, and tool access. This guide focuses on the native Windows path with Ollama as the local model provider, because that is the most common “run it on my own machine” setup and the one your notes target.

1. Prerequisites and choosing a host

OpenClaw runs on macOS, Linux, and Windows. You have three hosting options:

The rest of this guide assumes local Windows.

Software prerequisites

• Node.js 24.16+ or 26.1+ (Node 26 recommended). Node 22, 23, and 25 are unsupported since v2026.9.3. The installer script provisions a supported Node automatically if one is missing.

It is a free, open-source, cross-platform JavaScript runtime environment that lets developers create servers, web apps, command line tools and scripts.

• Ollama installed and running locally, if you want local models.

Windows-specific recommendation: The official docs list WSL2 as the most Linux-compatible Gateway runtime and strongly recommend it for Windows users in several places. Native Windows works, but WSL2 avoids a class of path, signal, and permission quirks. If you hit strange failures on native Windows, try WSL2 before debugging deeply.

2. Installation

The fastest and most reliable Windows installation is the native Windows Hub companion app. It is a signed installer that provides setup, tray status, chat, and node mode. Download it from the Windows Hub releases page. Run the installer and launch the app. On first run it can provision a local Gateway or connect to a remote one.

Verify the CLI

openclaw --version
# OpenClaw 2026.10.4 (383c124)

3. Connecting Ollama as the model provider

OpenClaw talks to Ollama through Ollama’s OpenAI-compatible API at http://127.0.0.1:11434. There are two ways to wire it up.

3.1 The automatic way: ollama launch openclaw

If Ollama is installed, the simplest path is:

ollama launch openclaw

Let’s install a local native gateway. This installs/configures a local component that lets OpenClaw talk to Ollama. Ollama acts as the gateway/provider: it receives OpenClaw’s requests and forwards them to a selected model. PC capabilities: Balanced. This is Ollama’s resource profile for my machine. “Balanced” means it will try to use a sensible mix of CPU, RAM, and GPU rather than maximizing speed or minimizing resource use. Connect your AI, Ollama. This links OpenClaw to Ollama. Once connected, you can choose models available in Ollama—either models stored locally on your PC or models served through Ollama Cloud.

Ollama will:

1. Install OpenClaw via npm if it is missing.
2. Show a security notice about tool access.
3. Let you pick a model.
4. Configure the provider, install the gateway daemon, set your model as the primary, and enable Ollama’s bundled web search.
5. Start the Gateway in the background and open the TUI.

To change the model without launching the TUI:

ollama launch openclaw --config
# or
ollama launch openclaw --model kimi-k2.5:cloud

3.2 The manual way: configure Ollama explicitly

If you prefer to configure OpenClaw yourself:

ollama pull qwen3.8:27b
openclaw config set models.providers.ollama.apiKey "ollama-local"
openclaw config set agents.defaults.model "ollama/qwen3.8:27b"

The apiKey value can be any non-empty string; Ollama does not validate it for local use.

3.3 Context length is not optional

OpenClaw requires a large context window. The official recommendation is at least 64k tokens for local models, because the agent handles multi-turn tool calling and long conversations. A model that advertises 256k but is capped at 8k usable context will fail in practice. When you choose a model, verify its usable context and set it explicitly if your provider configuration allows it:

openclaw config set agents.defaults.model "ollama/qwen3.8:27b"

If you use a model with a smaller window, expect compaction and tool-loop failures.

4. The Gateway: lifecycle, status, and the Windows service

The Gateway is the long-lived daemon that holds sessions, runs the scheduler, connects channels, and serves the Control UI. On native Windows it normally runs as a Windows Scheduled Task named OpenClaw Gateway (or OpenClaw Gateway (profile)), with a per-user Startup-folder login item as a fallback if Scheduled Task creation is denied.

4.1 Check status

openclaw gateway status

If you see Service: Scheduled Task (missing), the gateway is not registered to start automatically. That is expected before onboarding or before clawctl setup.

4.2 Lifecycle commands

# Install the Windows service / Scheduled Task
openclaw gateway install

# Gateway Lifecycle: Start, stop, restart
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

Always restart the gateway after changing configuration. Changes to openclaw.json are not hot-reloaded by every subsystem; a restart is the reliable way to apply them.

4.3 The packaged supervisor: clawctl

On Windows, the packaged supervisor is clawctl. It checks that the package, its isolated Node runtime, the recovery mechanism, and the session are intact:

clawctl setup
# A healthy output looks like:
Package:     ✓ ready
Runtime:     ✓ Node.js 24.21.0 installed in the isolated session
Recovery:    ✓ configured - the gateway starts when you sign in
Session:     ✓ ready
# Then, start the service:
clawctl gateway-service start

On Windows, OpenClaw normally uses a Scheduled Task named OpenClaw Gateway to start and supervise the gateway after login/boot. clawctl is the Windows-native supervisor. openclaw gateway is the cross-platform CLI. They operate on the same Gateway but from different layers; use clawctl when you want the packaged Windows service behavior, and openclaw gateway for day-to-day cross-platform commands.

# This confirms the CLI is installed and working. 
openclaw --version
OpenClaw 2026.10.4 (383c124)

# OpenClaw status
# This says OpenClaw has not registered its Windows Scheduled Task. 
# Because it is missing, OpenClaw is not yet set up to run automatically in the background.
openclaw gateway status
Service: Scheduled Task (missing)

Status & Diagnostics

# Full status (all components)
openclaw status --all
# Live channel probes (WhatsApp, Telegram, Discord, etc.)
openclaw status --deep
# Provider usage (quota remaining)
openclaw status --usage
# 💡 "openclaw logs --follow" is your first stop when something isn't working
openclaw logs --follow

# Logs and configuration
# The log file records what the gateway did today. Check it if something later fails.
File logs: ~\AppData\Local\Temp\openclaw\openclaw-2026-10-19.log
# The configuration file is in your user profile. C:\Users\YOUR_NAME\.openclaw\openclaw.json.
Config (cli): ~\.openclaw\openclaw.json
Config (service): ~\.openclaw\openclaw.json
logs/ — runtime logs
models/ — local model cache (if used)

# Gateway address and security
Gateway: bind=loopback (127.0.0.1), port=52640
# 127.0.0.1 is your own computer only.
# Port 52640 is the local WebSocket/HTTP port.
# ws:// is the WebSocket endpoint used for gateway communication.
# “Loopback-only” means other devices on your LAN or the internet cannot connect directly to this gateway.
Probe target: ws://127.0.0.1:52640
Dashboard: http://127.0.0.1:52640/
Probe note: Loopback-only gateway; only local clients can connect.

# It means the CLI successfully reached a live gateway at 127.0.0.1:52640. So a gateway is currently listening and responding.
Connectivity probe: ok

openclaw dashboard opens the Control UI in your browser (or open http://127.0.0.1:18789/). Type in the terminal openclaw gateway auth-token --show and paste the token in the given URL (http://127.0.0.1:52640/chat/main).

openclaw dashboard creates a short-lived, one-time pairing URL, opens it in your browser, and copies it to the clipboard. After you approve/use it, that specific browser receives a durable administrator device credential, so future dashboard visits do not need the shared gateway token.

# This is the Windows package supervisor checking that everything required to run OpenClaw is present:
PS C:\WINDOWS\system32> clawctl setup
🦀 clawctl setup
# The OpenClaw Windows package and its required files are intact.
  Package:     ✓ ready
# OpenClaw has its own isolated Node.js runtime, version 24.21.0; 
# it does not depend on a Node.js installation you manage yourself.
  Runtime:     ✓ Node.js 24.21.0 installed in the isolated session
# A startup/recovery mechanism is registered so the gateway starts after you sign in to Windows.
# That resolves the earlier “Scheduled Task (missing)” concern: the packaged supervisor owns startup/recovery  
  Recovery:    ✓ configured - the gateway starts when you sign in
# The isolated OpenClaw session that hosts the gateway is available and usable
  Session:     ✓ ready

  When you're ready, you may want to configure OpenClaw:
  Optional:    openclaw onboard

# This starts—or verifies and starts—the gateway through the package-owned supervisor. 
clawctl gateway-service start
🦀 clawctl gateway-service start

# The result means the gateway process is now actively listening on:
# 127.0.0.1:52640
# Because it is loopback-only, it is accessible from your own Windows machine, not from other devices on your network  
  Gateway:            ✓ listening
  Port:               52640

# Run: `clawctl open` when you are ready to configure OpenClaw itself—providers/models, 
# workspace, channels, skills, and health checks.
  Open Control UI:    clawctl open
PS C:\WINDOWS\system32> clawctl gateway-service status
🦀 clawctl gateway-service status

  Gateway:            ✓ listening
  Port:               52640

5. Configuration: the openclaw.json file

All configuration lives in C:\Users\YOUR_NAME\.openclaw\openclaw.json. The canonical shape is JSON. The most important top-level keys are:

5.1 Setting values

Use the CLI rather than editing the file by hand when possible:

# Set model via CLI
openclaw config set agents.defaults.model "ollama/qwen3.8:27b"

# Set system instructions
openclaw config set agents.defaults.instructions "You are MyPi, my helpful assistant."

# Workspace
openclaw config set agents.defaults.workspace "C:\Users\YOUR_NAME\.openclaw\workspace"

# Telegram
openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.botToken "YOUR_BOT_TOKEN"

# Re-run the full configuration wizard
openclaw configure
# Configure a specific section
# Set up provider + API key interactively
openclaw configure --section model
openclaw configure --section channels   # Connect to a messaging channel
openclaw configure --section web        # Web UI / Canvas settings
openclaw configure --section security   # Auth, tokens, trust
# Always restart the gateway after config changes — they don't apply until restart

5.2 Model fallbacks

agents.defaults.model accepts either a string (primary only) or an object with a fallback chain:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/qwen3.8:27b",
        "fallbacks": ["ollama/qwen2.5-coder:1.5b"]
      }
    }
  }
}

Each fallback gets a fresh timeout budget. The default timeout per attempt is 48 hours, which is almost never what you want for a chat agent; set agents.defaults.timeoutSeconds explicitly if you care about responsiveness.

5.3 Utility model

OpenClaw uses a separate utility model for short internal tasks: session titles, Telegram topic titles, Discord thread titles, activity recaps, progress narration, and transcript summaries. If you do not set it, OpenClaw derives the provider’s declared small-model default when one exists; otherwise those tasks fall back to the primary model. For a local setup, this is usually fine, but on a slow local model you may want to pin a tiny model:

openclaw config set agents.defaults.utilityModel "ollama/qwen2.5-coder:1.5b"

6. Channels: connecting messaging platforms

OpenClaw bridges popular messaging platforms — WhatsApp, Telegram, Slack, Discord, iMessage, Matrix, and others — to your agent, letting it receive and respond to messages on any connected channel. Each channel runs as an isolated adapter with its own credentials, permission policy, and message routing rules.

# Run the interactive configurator to register credentials and per-channel options:
openclaw configure --section channels
# This walks you through API tokens, webhook URLs, and permission scopes for each platform you want to enable. 
# Settings are persisted to openclaw.json.

# Send outbound messages from the CLI — useful for testing, scheduled nudges, or scripted workflows:
openclaw message send \
  --channel WhatsApp \
  --target "+65 9353 5210" \
  --message "Hi! This is your OpenClaw assistant." 

# openclaw.json
# Each channel has its own entry under channels in openclaw.json:
# enabled — Master switch for the channel adapter.
# selfChatMode — When true, the agent responds to messages you send to your own number 
# dmPolicy — Controls who can DM the agent:
# "allowlist" — Only numbers in allowFrom may interact.
# "open" — Anyone can reach the agent (use with caution; pair with rate limits).
# "denylist" — Everyone except entries in denyFrom.
# allowFrom — List of E.164-formatted phone numbers or platform IDs permitted under allowlist policy.
# For example, a Spanish number becomes +34612345678, not +34 (Spain) MyPhoneNumber.
# fallbackToAgent — Routes unrecognized intents back to the agent's default handler instead of dropping the message.
"channels": {
    "whatsapp": {
      "enabled": true,
      "selfChatMode": true,
      "dmPolicy": "allowlist",
      "allowFrom": [
        "+34(Spain)MyPhoneNumber"
      ]
    }
  },

7. Security

A fresh local install binds the Gateway to 127.0.0.1 (loopback). That means only processes on the same machine can connect; other devices on your LAN or the internet cannot reach it directly. Keep this default unless you have a specific reason to expose the Gateway.

Even on loopback, the onboarding wizard generates a Gateway token by default. The token lives in gateway.auth.token or the OPENCLAW_GATEWAY_TOKEN environment variable. The Control UI sends it during the WebSocket handshake.

# To see the token:
openclaw gateway auth-token --show

# Open the dashboard
openclaw dashboard
# This creates a **short-lived, one-time pairing URL**, opens it in your browser, and copies it to the clipboard. 
# After you approve it, that browser receives a durable administrator device credential, 
# so future visits do not need the shared token.
# However, if the dashboard prompts for auth instead. Run
openclaw gateway auth-token --show
# ... and paste the token into the Control UI settings.

The Gateway token protects the control plane. The agent’s tool policy protects your machine. OpenClaw can be given shell, file, browser, and web tools. What the agent can actually do is set by tool policy in openclaw.json, not by skills. Review tools before connecting a channel that other people can message.