Getting Started with OpenClaw Setup - CLI Configuration and Workspace Initialisation

Getting an AI agent framework running locally shouldn't take more than a few minutes. One of the things I appreciate about OpenClaw is that the initial setup is genuinely simple - a single command gets you a working environment. No Docker compose files to wrestle with, no Kubernetes manifests, no cloud account provisioning. Just a config file and a workspace directory.

That said, there are a few decisions in the setup process that are worth thinking about before you run the command. Especially if you're setting up OpenClaw for a team rather than just yourself.

The OpenClaw setup documentation covers the command syntax. I want to add context around when to use each option and what the choices mean for your workflow.

The Basics - What openclaw setup Actually Does

Running openclaw setup does two things:

1. Creates (or updates) your configuration file at ~/.openclaw/openclaw.json
2. Initialises your agent workspace directory

That's it. No services started, no ports opened, no background processes. It's pure configuration.

The config file holds your defaults - where your agent workspace lives, which mode you're running in, connection details for remote gateways. The workspace directory is where your agents store their files, logs, and state.

If you've used other AI agent frameworks, you'll notice OpenClaw keeps its footprint small. There's no database to initialise, no message queue to set up. The workspace is just a directory on your filesystem. Agents read from it and write to it. Simple.

Local vs. Remote Mode - Choosing Your Architecture

The most important decision during setup is whether to run in local mode or remote mode.

Local mode means your agents run on the same machine where you're running the CLI. The workspace directory is local. Agent execution happens locally. This is the right choice for development, testing, and single-developer setups.

openclaw setup --wizard --mode local

Remote mode connects your CLI to a Gateway server running somewhere else - your own server, a cloud VM, a shared team instance. Agents execute on the remote host, and the CLI communicates over WebSocket.

openclaw setup --non-interactive --mode remote --remote-url wss://gateway-host:18789 --remote-token <token>

For teams, remote mode is almost always the right call. Here's why: if five developers are each running agents locally, they're each maintaining their own state, their own workspace, and their own set of running agents. When someone goes home for the day and closes their laptop, their agents stop. With a shared Gateway, agents persist regardless of who's connected.

We've set up both models for clients. Local mode works well for prototyping and personal automation. Remote mode is what you want for anything that needs to run reliably or be accessed by multiple people.

The Wizard vs. Non-Interactive Setup

OpenClaw gives you two paths through the setup:

The wizard (--wizard) walks you through each configuration option interactively. It asks questions, validates your inputs, and explains what each setting does. Good for first-time setup or when you're not sure what you need.

The non-interactive flag (--non-interactive) skips all prompts and uses the values you provide on the command line. This is what you want for scripted deployments, CI/CD pipelines, or team provisioning where you're setting up the same configuration across multiple machines.

A pattern we use frequently - run the wizard once on your own machine to figure out the right settings, then write a non-interactive setup script for the rest of the team:

#!/bin/bash
# Team OpenClaw setup script
openclaw setup --non-interactive \
  --mode remote \
  --remote-url wss://openclaw.internal.company.com:18789 \
  --remote-token "${OPENCLAW_TOKEN}"

Store the token in your team's secrets manager, not in the script. I know that sounds obvious, but I've seen tokens committed to Git repositories more times than I care to admit.

Workspace Configuration

The workspace directory defaults to ~/.openclaw/workspace unless you specify otherwise. For most individual developers, this is fine. But there are situations where you'd want to change it.

Shared filesystems. If your team uses a shared NFS mount or a network drive, pointing the workspace there means agents can share state. This only applies to local mode - in remote mode, the workspace lives on the Gateway host.

Disk space constraints. Some agents generate significant output - log files, intermediate data, model artifacts. If your home directory is on a small SSD, pointing the workspace to a larger volume saves headaches later.

Multiple projects. You might want separate workspaces for different clients or projects to keep agent state isolated:

openclaw setup --workspace ~/openclaw-workspaces/client-a

The workspace path gets stored in your config file under agents.defaults.workspace, so you'd need to update your config when switching between projects. OpenClaw doesn't currently support workspace profiles, so if you're juggling multiple projects, you'll need a script or alias to swap configs.

What Happens After Setup

Once setup completes, you've got a config file and an empty workspace. The next steps depend on what you're building:

• Running an agent means defining an agent configuration (what model it uses, what tools it has access to, what its instructions are) and starting it through the CLI.
• Connecting plugins adds capabilities like messaging platform integrations, tool access, or external API connections.
• Setting up hooks lets you trigger automations based on agent events.

The setup command deliberately doesn't do any of this. It just prepares the ground. I think that's the right design choice - it means setup is fast and predictable, and you don't end up with a half-configured agent running before you're ready.

Common Setup Issues

A few things we've run into on client projects:

Port conflicts in remote mode. The default Gateway port is 18789. If something else is using that port, the WebSocket connection fails silently - you just get connection timeouts with no helpful error message. Check the port is available before assuming OpenClaw is broken.

Token format. Remote mode requires a token for authentication. The token needs to match exactly what the Gateway expects. Trailing whitespace, newline characters from copy-paste, or encoding issues will cause authentication failures. If you're getting "unauthorised" errors, check the token byte-for-byte before debugging anything else.

Permissions on the workspace directory. On Linux and macOS, the workspace directory needs to be readable and writable by the user running OpenClaw. If you've set up the workspace in a shared location, make sure file permissions are correct. We've seen agents fail to start because the workspace directory was owned by root from a previous sudo installation attempt.

Upgrading OpenClaw. Running openclaw setup on an existing installation is safe - it updates the config without destroying existing workspace data. But check the release notes for any config format changes between versions. Occasionally a new version adds required fields that the setup command will prompt you for.

Fitting OpenClaw into Your AI Stack

OpenClaw is one piece of a bigger picture. It handles agent orchestration and execution, but your agents still need models, tools, and integrations to do useful work.

We typically see OpenClaw paired with:

• LLM providers like Azure OpenAI or Anthropic for the underlying model
• MCP servers for tool access - giving agents the ability to query databases, call APIs, or interact with business systems
• Messaging platforms as the user-facing interface - Slack, Teams, or custom web interfaces

The setup process gets you ready to start connecting these pieces. The actual integration work is where most of the effort goes - and where the value is.

If you're evaluating OpenClaw for your organisation, or if you've done the basic setup and need help building out the agent layer, our AI agent development team has experience with OpenClaw and other agent frameworks. We also offer managed services for OpenClaw if you'd rather have us handle the infrastructure while you focus on building agents.

For the complete CLI reference, check the OpenClaw setup documentation. And if you're just getting started with AI agents more broadly, our agentic automations practice can help you figure out where agents make sense in your business before you start writing code.