Prerequisites

  • Python 3.10+
  • An API key for OpenAI, Anthropic, or a compatible LLM provider
  • 5 minutes for install; 10 minutes for your first working agent

Install and Configure

pip install openclaw
 
# Set your LLM API key
export ANTHROPIC_API_KEY=sk-ant-...  # or OPENAI_API_KEY
 

Minimal Working Agent

from openclaw import Agent
 
agent = Agent(model='claude-sonnet-4-6')
 
result = agent.run('What is the square root of 144?')
print(result.output)  # '12'
 

This creates an agent with no tools — it can only reason with the model's built-in knowledge. Useful for confirming your API key works.

Adding Built-in Tools

from openclaw import Agent
 
# Available built-in tools: 'browser', 'code', 'files', 'shell'
agent = Agent(
    model='claude-sonnet-4-6',
    tools=['browser', 'files'],  # enable only what you need
    max_steps=10,               # safety limit
    working_dir='./agent_workspace',  # where file tools write
)
 
result = agent.run(
    'Go to https://pypi.org/project/requests/ and save the '
    'package description to a file called requests_info.txt'
)
 
print(f'Completed in {result.steps_taken} steps')
print(f'Output file: {result.output}')
 
Do not enable the 'shell' tool for agents that process untrusted input. Shell access allows arbitrary command execution. If you need shell access, restrict it to a sandboxed environment and validate all inputs.

Adding a Custom Tool

Custom tools are Python functions decorated with @tool. The docstring tells OpenClaw when and how to use the tool.

from openclaw import Agent, tool
import requests
 
@tool
def get_weather(city: str) -> str:
    'Get the current weather for a city. Returns temperature and conditions.'
    # Replace with a real weather API call
    response = requests.get(
        f'https://wttr.in/{city}?format=3',
        headers={'User-Agent': 'weather-agent/1.0'}
    )
    return response.text if response.ok else f'Could not fetch weather for {city}'
 
agent = Agent(
    model='claude-sonnet-4-6',
    tools=[get_weather],  # pass the function, not a string
)
 
result = agent.run('What is the weather like in Paris right now?')
print(result.output)
 

Inspecting Agent Steps

After a run, inspect what the agent actually did using result.steps. This is essential for debugging unexpected behaviour.

result = agent.run('Research Python web frameworks and summarise the top 3')
 
for i, step in enumerate(result.steps, 1):
    print(f'Step {i}: {step.type}')
    print(f'  Action: {step.action}')
    if step.tool_used:
        print(f'  Tool: {step.tool_used}')
        print(f'  Result preview: {str(step.tool_result)[:100]}')
    print()
 

Key Configuration Options

Parameter Default What it does
max_steps 20 Maximum steps before the agent stops. Set lower (5-10) during development.
working_dir ./ Directory for file tool read/write operations. Set to a dedicated folder.
memory True Enable in-session memory. Disable for stateless single-query agents.
verbose False Print step-by-step progress to stdout. Useful for debugging.
timeout 300 Maximum seconds for the entire run. Prevents runaway agents.

Next Steps

  • Explore the built-in tool options: browser tool for web navigation, code tool for Python execution
  • Check the OpenClaw Discord for community workflows and patterns
  • Read the GitHub issues — many common problems and their workarounds are documented there
  • Consider LangGraph if you need checkpointing, human-in-the-loop, or multi-agent coordination