When you ask a chatbot a question, it generates a response and stops. An agent, by contrast, enters a perceive → reason → act → observe loop. It receives a goal, figures out what steps are needed, executes those steps using tools, observes the results, and then plans its next move — repeating this cycle until the task is complete.
The LLM core that plans, decides, and interprets results at each step.
Functions the agent can call — web search, file I/O, calculators, APIs.
Short-term context within a run and long-term storage across sessions.
The ability to make real changes — write files, send requests, trigger automations.
Real-world uses for personal agents include automated research pipelines, coding assistants that can run and test their own code, personal data analysts that work on your local files, and scheduled bots that monitor services and alert you to changes.
python --version. OpenClaw can be installed in three ways. For most users, the pip install route is the fastest path to a working setup.
# Create and activate a virtual environment
python -m venv openclaw-env
source openclaw-env/bin/activate # Windows: openclaw-env\Scripts\activate
# Install OpenClaw
pip install openclaw
# Verify
openclaw --version
docker pull openclaw/openclaw:latest
docker run -it --rm \
-e OPENAI_API_KEY=your_key_here \
-v $(pwd)/workspace:/workspace \
openclaw/openclaw:latest
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pip install -e ".[dev]"
Create a .env file in your project directory with your credentials:
OPENAI_API_KEY=sk-...
OPENCLAW_MODEL=gpt-4o
SERPAPI_KEY=your_search_key # optional
OPENCLAW_LOG_LEVEL=INFO
Never commit your .env file to version control. Add it to .gitignore immediately. Your API keys are credentials — treat them like passwords.
Before building, it helps to understand OpenClaw’s mental model. Everything revolves around a single YAML config file that describes your agent’s identity, capabilities, and constraints.
An OpenClaw agent is composed of three layers:
When you give your agent a task, it enters a reasoning loop powered by the ReAct pattern (Reasoning + Acting). At each step the model thinks out loud — deciding what action to take — calls a tool, receives the result, and decides what to do next. This loop continues until the agent determines the task is complete.
User Goal → [Reason] → [Act: call tool] → [Observe result]
↑______________↓
(repeat until done)
The active conversation window. Cleared when the session ends.
A vector database (Chroma, Pinecone) that persists between runs.
A scratchpad the agent writes to mid-task for intermediate results.
Create a new directory for your project and add an agent.yaml file. This is the single source of truth for your agent.
name: MyFirstAgent
description: A simple personal assistant agent
model:
provider: openai
name: gpt-4o
temperature: 0.3
tools:
- web_search
- file_writer
- calculator
memory:
short_term: true
long_term: false
max_iterations: 15
verbose: true
Now run it for the first time:
openclaw run agent.yaml \
--task "What are the three most important AI research papers published this month? Summarize each in two sentences."
You’ll see OpenClaw’s planning loop in your terminal — each step labelled with [THINK], [ACT], and [OBSERVE]. Watch as the agent searches the web, reads results, and composes a structured answer.
If you set verbose: true, each reasoning step is printed to stdout. Look for the [THINK] blocks — this is the raw inner monologue of the agent, and it’s the best way to understand why it makes each decision.
Tools are what transform an agent from a text generator into something that can do things. OpenClaw ships with a set of built-in tools you can enable instantly.
Any Python function can become an agent tool with a single decorator:
from openclaw import tool
@tool(
name="get_weather",
description="Get the current weather for a given city."
)
def get_weather(city: str) -> str:
# Your implementation here
response = requests.get(f"https://wttr.in/{city}?format=3")
return response.text
Then reference it by name in your agent.yaml under tools, and OpenClaw will make it available to the agent automatically.
Memory is what separates a one-shot script from a true agent that improves over time. OpenClaw supports two memory backends out of the box.
Enabled by default. The agent keeps the full history of the current run in its context window. When the run ends, this memory is cleared. It’s perfect for multi-step tasks within a single session.
Install the extra dependency and update your config:
pip install openclaw[chroma]
memory:
short_term: true
long_term:
backend: chroma
path: ./agent_memory
top_k: 5 # retrieve 5 most relevant memories per query
With long-term memory enabled, the agent will store key facts and past task outcomes as embeddings. On future runs, it retrieves the most relevant memories and includes them in its reasoning context. Over time, your agent becomes more effective at tasks it has done before.
Use short-term only for one-off tasks and experimentation. Enable long-term memory when you’re building a recurring assistant that should accumulate domain knowledge over weeks and months.
# Run with verbose reasoning shown
openclaw run agent.yaml --task "..." --verbose
# Dry run — plan only, no tool execution
openclaw run agent.yaml --task "..." --dry-run
# Set a token budget to control cost
openclaw run agent.yaml --task "..." --max-tokens 8000
# Save full trace to a log file
openclaw run agent.yaml --task "..." --log-file run.log
It’s important to constrain what your agent is allowed to do, especially when it can write files or make HTTP requests. Add a safety block to your config:
safety:
max_iterations: 20
allowed_file_paths:
- ./workspace/
blocked_domains:
- internal.company.com
require_approval: false # set true to confirm each action
max_iterations or simplify the task..env and review the tool’s error log.top_k memory retrievals or enable summarization.Let’s put everything together and build the agent described at the start of this guide — one that searches the web and saves structured research notes to your filesystem.
name: ResearchAssistant
description: Searches the web and produces structured Markdown research notes.
model:
provider: openai
name: gpt-4o
temperature: 0.2
system_prompt: |
You are a rigorous research assistant. When given a topic:
1. Search for 3-5 authoritative sources.
2. Read each source carefully.
3. Write a structured Markdown report: Summary, Key Findings, and Sources.
4. Save the report to ./workspace/{topic}.md
tools:
- web_search
- http_get
- file_writer
memory:
short_term: true
long_term:
backend: chroma
path: ./memory
safety:
max_iterations: 25
allowed_file_paths:
- ./workspace/
mkdir -p workspace
openclaw run agent.yaml \
--task "Research the current state of quantum error correction" \
--verbose
Watch the agent search for papers, fetch article content, synthesize findings, and write a clean Markdown file to ./workspace/quantum_error_correction.md. The whole process takes about 60–90 seconds with GPT-4o.
If the output isn’t what you wanted, the fastest fix is almost always to improve the system_prompt. Be explicit: specify output format, word count, and what to do when sources are paywalled.
You’ve got a working agent. Here’s where to go next.
MultiAgent class in the docs.cron (Linux/macOS) or Task Scheduler (Windows) to run your agent on a recurring schedule. Morning briefings, weekly summaries, and monitoring bots are all fair game.openclaw plugin install <name>.provider: ollama in your config.openclaw evals to run your agent against benchmark tasks and measure accuracy, cost per run, and iteration counts.docs.openclaw.aidiscord.gg/openclawgithub.com/openclaw/openclaw1. Introduction WordPress 6.9, codenamed "Gene," is the final major release of 2025 and one…
1. Introduction to Containerization 1.1 What Is Containerization and Why It Matters Modern software development…
1. Introduction If you've ever wanted to automate repetitive tasks — like syncing data between…
Introduction Survival games have become one of the most enduring and beloved genres in modern…
1. What is Node.js? Node.js lets you use JavaScript to build the "brain" of a…
1. Introduction If you have ever shopped for a new SSD or tried to upgrade…