OpenClaw CLI Commands: Complete Cheat Sheet & Reference Guide

Quick Start: Your First 4 Commands

If you are new to OpenClaw, these four commands get you from zero to a working agent. Run them in order and you will have an AI agent ready to chat in under two minutes.

# 1. Create a new OpenClaw project
npx openclaw init

# 2. Set your AI provider API key
openclaw models auth paste-token --provider anthropic

# 3. Register your agent
openclaw agents add my-agent --workspace ./agents/my-agent --non-interactive

# 4. Start the gateway
openclaw gateway start

After running these commands, your agent is live at localhost:18789 and ready to receive messages.

Project Initialization

npx openclaw init

Creates a new OpenClaw project in the current directory. This scaffolds the folder structure with a default agent, SOUL.md template, and configuration files. Use this when starting a brand new agent project.

# Create a new project in the current directory
npx openclaw init

# Create in a specific directory
mkdir my-ai-team && cd my-ai-team
npx openclaw init

This creates a agents/ directory with a starter SOUL.md, plus configuration files for the gateway and model providers.

Configuration

openclaw configure

Launches the interactive configuration wizard. This walks you through setting up model providers, API keys, gateway settings, and agent defaults. Useful for first-time setup or when switching between providers.

# Interactive configuration wizard
openclaw configure

openclaw models auth paste-token

Sets the API key for a specific model provider. This is the most commonly searched command because it is required before any agent can run. OpenClaw supports multiple providers — you only need to configure the one you plan to use.

# Set Anthropic (Claude) API key
openclaw models auth paste-token --provider anthropic

# Set OpenAI (GPT) API key
openclaw models auth paste-token --provider openai

# Set a local Ollama instance (no API key needed)
openclaw models auth paste-token --provider ollama

After running this command, paste your API key when prompted. The key is stored locally and never sent anywhere except to the provider during agent execution.

Agent Management

These commands handle your agent registry — adding, listing, and removing agents. Every agent needs a workspace directory containing at minimum a SOUL.md file that defines the agent's identity and behavior.

openclaw agents list

Shows all registered agents with their names, workspace paths, and status. Use this to verify your agents are properly registered before starting the gateway.

# List all registered agents
openclaw agents list

openclaw agents add

Registers a new agent with OpenClaw. This is the command most people search for when setting up their second or third agent. The agent name must be unique, and the workspace must contain a valid SOUL.md file.

# Add an agent with interactive prompts
openclaw agents add content-writer --workspace ./agents/content-writer

# Add without prompts (for scripts and automation)
openclaw agents add content-writer --workspace ./agents/content-writer --non-interactive

# Add multiple agents
openclaw agents add seo-analyst --workspace ./agents/seo-analyst --non-interactive
openclaw agents add researcher --workspace ./agents/researcher --non-interactive

The --non-interactive flag is recommended when you are adding multiple agents or automating setup. Without it, OpenClaw asks confirmation questions for each agent.

openclaw agents remove

Unregisters an agent from OpenClaw. This removes the agent from the registry but does not delete the workspace files. Your SOUL.md and configuration files remain intact.

# Remove an agent
openclaw agents remove content-writer

Sending Messages to Agents

openclaw agent --agent

Sends a message directly to a specific agent and returns the response. This is the primary way to interact with agents from the command line. Note that the command is agent (singular), not agents (plural).

# Send a message to an agent
openclaw agent --agent content-writer --message "Write a blog post about AI agents"

# Send to a different agent
openclaw agent --agent seo-analyst --message "Analyze keywords for ai2sql.io"

# Multi-word agent names use hyphens
openclaw agent --agent project-manager --message "Create a sprint plan"

Gateway Management

The gateway is the central server that routes messages to your agents. It exposes a web interface, handles Telegram bot connections, and manages agent sessions.

openclaw gateway start

# Start the gateway (default port 18789)
openclaw gateway start

# The gateway runs at http://localhost:18789

openclaw gateway restart

# Restart the gateway (picks up config changes)
openclaw gateway restart

Restart the gateway after editing SOUL.md files, adding new agents, or changing model provider settings. The gateway does not hot-reload configuration changes.

Session Management

OpenClaw stores conversation history in session files. If an agent starts behaving unexpectedly or you want a fresh start, clearing sessions resets the conversation context.

# Clear all agent sessions (fresh start)
rm ~/.openclaw/agents/*/sessions/sessions.json

# Clear sessions for a specific agent
rm ~/.openclaw/agents/content-writer/sessions/sessions.json

Clearing sessions is useful when an agent accumulates too much context or when you significantly change the SOUL.md and want the agent to start fresh without prior conversation history.

Agent Workspace File Structure

Each agent lives in a workspace directory. The only required file is SOUL.md, but you can add additional configuration files to fine-tune behavior.

agents/content-writer/
├── SOUL.md          # Required — agent identity, personality, rules
├── TOOLS.md         # Optional — available tools and when to use them
├── AGENTS.md        # Optional — other agents this agent knows about
├── HEARTBEAT.md     # Optional — periodic task instructions
├── MEMORY.md        # Optional — persistent knowledge
├── IDENTITY.md      # Optional — extended identity details
├── BOOTSTRAP.md     # Optional — startup instructions
└── USER.md          # Optional — user context and preferences

SOUL.md is the only file you must create. It defines who the agent is, how it behaves, what rules it follows, and what tone it uses. The other files let you add capabilities like tool access, team awareness, and scheduled tasks. For ready-to-use SOUL.md templates, visit the CrewClaw SOUL.md Generator.

Full Command Reference Table

Common Errors and Fixes

Frequently Asked Questions