Getting Started with OpenClaw AI

What is OpenClaw AI?

OpenClaw AI is an open-source framework for building and running autonomous AI agents. Think of it as giving a large language model (LLM) hands and feet — the ability to take real actions in the world: reading and writing files, running code, browsing the web, calling APIs, and completing multi-step tasks without constant human intervention.

Unlike a simple chatbot or one-shot LLM call, an OpenClaw agent plans, executes, observes results, and adapts. You describe a goal in plain English, and the agent figures out the steps needed to reach it.

Key Concepts

Before diving into installation, let's clarify the terminology you'll encounter throughout this documentation.

Agent

An agent is the core entity in OpenClaw. It receives a goal, uses an LLM to reason about what to do, selects and calls tools, observes the results, and continues until the goal is met or a stopping condition is reached.

Task

A task is the goal you give to an agent — expressed in natural language. For example: "Find all Python files in /src that import requests and generate a security audit report." Tasks can be simple (single action) or complex (multi-step workflows).

Tool

A tool is a capability the agent can invoke. OpenClaw ships with a rich built-in tool library:

• file_read / file_write — Read and write local files
• shell_exec — Execute terminal commands (sandboxed)
• web_search — Query the web via a search API
• web_scrape — Fetch and parse webpage content
• code_run — Execute Python code in a safe sandbox
• http_request — Call REST APIs
• db_query — Query SQLite, PostgreSQL, MySQL

You can also write custom tools as Python functions with a single decorator.

Memory

Agents in OpenClaw maintain memory across steps. Short-term memory holds the current conversation context. Long-term memory (optional) allows agents to persist facts across runs using vector storage or SQLite.

Provider (LLM Backend)

A provider is the LLM powering the agent's reasoning. OpenClaw supports:

• OpenAI (GPT-4o, GPT-4, GPT-3.5)
• Anthropic Claude (3.5 Sonnet, Claude 3 Opus)
• Ollama (local: LLaMA 3, Mistral, Phi-3, Gemma)
• Groq, Together AI, Fireworks (fast inference)
• Any OpenAI-compatible endpoint

Before You Begin

Make sure you have the following ready before starting. Each item takes less than a minute to verify:

System Requirements

OpenClaw is lightweight and runs on most modern hardware. Here are the minimum and recommended specifications:

How OpenClaw Works

Understanding the execution loop helps you write better tasks and debug issues faster. Here's the core ReAct loop OpenClaw uses:

1. 1

   Receive Task

   You provide a task via CLI, Python API, or bot interface. OpenClaw parses it into a structured goal object.

2. 2

   Plan

   The agent sends the goal + available tools + conversation history to the LLM, which responds with a thought + action: what it thinks needs to happen and which tool to call.

3. 3

   Execute

   OpenClaw calls the chosen tool with the provided parameters. The result (file content, shell output, API response, etc.) is captured.

4. 4

   Observe

   The tool result is fed back into the LLM as an observation. The agent now decides: is the goal reached, or does it need another action?

5. 5

   Finish

   When the LLM determines the goal is complete, it outputs a final answer. OpenClaw returns this to you with a full execution trace.

Architecture at a Glance

The diagram below shows how OpenClaw's components interact. Every task flows through this pipeline — from your terminal command to the final result.

The ReAct loop runs until the agent produces a final answer or hits a max-steps limit.

Your First Agent — Step by Step

Let's put theory into practice. We'll install OpenClaw, configure a provider, and run a simple file-summarization task.

Step 1: Install

pip install openclaw

# Verify installation
openclaw --version
# OpenClaw AI v1.0.0

Step 2: Configure a Provider

For this example we'll use OpenAI. If you prefer a local model, see the Local LLM section.

openclaw config set provider openai
openclaw config set api_key sk-...your-key...

# Verify the config
openclaw config show

Step 3: Run Your First Task

openclaw run "Create a file called hello.txt with the content 'Hello from OpenClaw!'"

🤖 OpenClaw Agent v1.0.0
📋 Task: Create a file called hello.txt with the content 'Hello from OpenClaw!'

🧠 Thinking...
  → Action: file_write
  → Path: ./hello.txt
  → Content: Hello from OpenClaw!

✅ Task completed in 1 step (1.2s)
📄 File created: ./hello.txt

OpenClaw vs Other Frameworks

How does OpenClaw compare to other popular autonomous AI agent tools? Here's a quick side-by-side for developers evaluating their options:

Glossary of Key Terms

New to AI agents? Here are the core concepts you'll encounter throughout this documentation:

Agent

An autonomous program that perceives its environment, makes decisions, and takes actions to achieve a defined goal. In OpenClaw, an agent receives your task, plans sub-steps, calls tools, and returns results.

Task

A natural language instruction you give to the agent (e.g., "Summarize all files in ~/reports"). Tasks can be simple (one-step) or complex (multi-step with tool calls).

Tool

A function the agent can invoke to interact with the world: read files, run shell commands, search the web, call APIs, write code, etc. You can also write custom tools in Python.

Memory

The agent's ability to retain context across steps (short-term memory) or across sessions (long-term memory via vector stores). Enables multi-turn conversations and persistent state.

Pipeline

A pre-defined sequence of agent steps. Pipelines are useful for automating repeatable workflows — e.g., daily: fetch news → summarize → send Telegram message.

Provider

The LLM service OpenClaw uses for reasoning: OpenAI (GPT-4), Anthropic (Claude), Ollama (local), Google (Gemini), Mistral, or any OpenAI-compatible endpoint. Configured via openclaw config set provider.

ReAct Loop

Reasoning + Acting pattern. The agent alternates between thinking about what to do (reasoning) and actually doing it (acting via tools), iterating until the goal is achieved.

Recommended Learning Path

New to OpenClaw? Follow this reading order to build understanding progressively:

1. You are here — Getting Started (concepts + first run)
2. Installation — Set up OpenClaw on your platform
3. API Keys or Local LLM Setup — Connect a model
4. The run command — Master task execution
5. AI Coding use case — Typical real-world workflow
6. File Automation — Build practical automations
7. Telegram Bot — Deploy your agent externally
8. Advanced CLI — Pipelines, dry-run, multi-step
9. Config Examples — Production-ready setups
10. Sample Projects — Full working examples

What's Next?

You've successfully run your first OpenClaw agent. From here, explore: