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