How to Set Up OpenClaw AI Agent: Complete Installation Guide (2026)
Knowing how to set up OpenClaw AI agent gives you 24/7 automation for messaging, code execution, and proactive task management. This step-by-step guide walks you through installation, configuration, and deployment of your first OpenClaw agent from scratch in 2026.
OpenClaw is an open-source, self-hosted AI agent framework that runs on macOS, Linux, Windows, and WSL2. Unlike cloud-hosted alternatives, you control the infrastructure, data privacy, and cost structure. When you set up OpenClaw AI agent properly, you create an autonomous assistant that monitors channels, executes commands, and responds to events without human intervention.
What Is OpenClaw and Why Set It Up?
OpenClaw transforms language models (Claude, Gemini, local LLMs) into persistent agents with skills like file system access, web browsing, API integration, and scheduled tasks. When you set up OpenClaw AI agent instances, you unlock:
- 24/7 availability: Daemon-based operation ensures uptime even after reboots
- Multi-channel support: Telegram, Discord, WhatsApp, Signal, web dashboard
- Extensible skills: npm-based skill system (email, calendar, cameras, SSH)
- Proactive automation: Heartbeat mechanism for periodic checks and alerts
- Privacy-first: Self-hosted with no third-party data exfiltration
OpenClaw competes with commercial platforms like n8n, Make.com, and Zapier but offers deeper AI integration, conversational control, and zero subscription fees. For technical users comfortable with command-line tools, learning how to set up OpenClaw AI agent systems delivers unmatched flexibility.
Prerequisites to Set Up OpenClaw AI Agent
Before installation, gather these requirements:
1. Supported Operating System
- macOS 11+ (Big Sur or newer)
- Linux (Ubuntu 20.04+, Debian 11+, Fedora, Arch)
- Windows 10/11 (PowerShell as Administrator)
- WSL2 (Windows Subsystem for Linux)
2. AI Model Provider (Choose One)
| Provider | Recommended Model | Cost | Setup Link |
|---|---|---|---|
| Anthropic | Claude 3 Sonnet | $3 per million tokens | Get API Key |
| OpenRouter | Kimi K2.5 | $0.10 per million tokens | Get API Key |
| Gemini 1.5 Pro | Free tier available | Get API Key | |
| LM Studio (Local) | Qwen 2.5, Llama 3.1 | Free (local compute) | Download |
Recommendation: Anthropic Claude 3 Sonnet balances quality and cost for most users. OpenRouter provides budget-friendly access to dozens of models. Google Gemini offers a generous free tier for testing.
3. Messaging Channel (Optional but Recommended)
To interact with your agent, configure at least one channel:
- Telegram: Create a bot via @BotFather, run
1/newbot
, copy the bot token
- Discord: Create application at Discord Developer Portal, add bot, copy token
- Web Dashboard: Built-in with OpenClaw, no external setup needed
Telegram is the fastest to configure and works excellently for personal automation.
Step 1: Install OpenClaw with One-Liner
The easiest method to set up OpenClaw AI agent is the official installer, which detects your OS, installs Node.js if missing, and configures the daemon.
macOS / Linux / WSL2
Open terminal and run:
1 curl -fsSL https://openclaw.ai/install.sh | bash
The script will:
- Check for Node.js 22+ (install via nvm if absent)
- Install OpenClaw globally via npm
- Prompt for daemon installation (select Yes)
- Launch configuration wizard
Windows (PowerShell as Administrator)
1 iwr -useb https://openclaw.ai/install.ps1 | iex
Accept the security warning when prompted (OpenClaw requires system access for skills like file operations).
Manual Installation (Alternative)
If you prefer manual control:
1
2 npm install -g openclaw@latest
openclaw onboard --install-daemon
Verify installation:
1
2 openclaw version
openclaw doctor
The
1 | doctor |
command diagnoses configuration issues and suggests fixes.
Step 2: Configure AI Model Provider
After installation, the onboarding wizard launches automatically. If you skipped it, run:
1 openclaw onboard
Select Quick Start mode for guided setup.
Anthropic Claude Configuration
- Choose Anthropic from the provider list
- Paste your API key from console.anthropic.com/settings/keys
- Select model:
1claude-3-5-sonnet-20241022
(recommended)
- Save configuration
OpenRouter Configuration
- Choose OpenRouter
- Paste API key from openrouter.ai/keys
- Select model:
1anthropic/claude-3.5-sonnet
or
1qwen/kimi-k2.5 - Add credits to your OpenRouter account
Local LLM with LM Studio
- Download and install LM Studio
- Download model (e.g.,
1Qwen2.5-Coder-7B-Instruct
)
- Start local server (default:
1http://127.0.0.1:1234
)
- In OpenClaw wizard, select Custom/LM Studio
- Enter base URL:
1http://127.0.0.1:1234/v1
- API key:
1lm-studio
(placeholder)
Test the connection:
1 openclaw models status
Successful output shows model availability and latency.
Step 3: Add Messaging Channel (Telegram)
To interact with your agent, configure Telegram as the primary channel.
Create Telegram Bot
- Open Telegram and message @BotFather
- Send
1/newbot
- Choose bot name (e.g., “My Assistant”)
- Choose username (must end in
1bot
, e.g.,
1myassistant_bot)
- Copy the bot token (format:
1123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
)
Configure in OpenClaw
- In onboarding wizard, select Telegram
- Paste the bot token
- Save configuration
Alternative: Configure via dashboard:
1 openclaw dashboard
Navigate to Channels → Telegram → Paste token → Save.
Test the Bot
- Open Telegram
- Search for your bot username
- Send
1/start
- Send a message like “What’s the current time?”
Your agent should respond immediately. If not, check logs:
1 openclaw logs --follow
Step 4: Define Agent Personality with SOUL.md
When you set up OpenClaw AI agent systems, defining personality is critical for consistent behavior. The
1 | SOUL.md |
file loads on every agent boot, establishing core traits, tone, and decision-making rules.
Chat with your agent (Telegram or dashboard) and send:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 Update your SOUL.md with the following:
You are Alex, a friendly technical assistant.
## Personality
- Concise, technical, helpful
- Use examples and code snippets
- Proactive: suggest solutions before asked
## Tone
- Professional but approachable
- Avoid jargon unless appropriate
## Rules
- Always ask for confirmation before destructive actions
- Prioritize privacy and security
- When uncertain, clarify before acting
The agent will update
1 | workspace/SOUL.md |
and reload automatically. For related automation guides, see our tutorial on automating tasks with AI agents.
Step 5: Enable Essential Skills
Skills extend your agent’s capabilities. Enable them via chat or config file.
Via Chat
Send to your agent:
1
2
3
4 Enable the following skills:
- npm (Node.js package management)
- brave_search (web search)
- filesystem (file operations)
Via Configuration File
Edit
1 | ~/.openclaw/openclaw.json |
:
1
2
3
4
5
6
7
8
9
10
11 {
"agents": {
"defaults": {
"skills": [
"npm",
"brave_search",
"filesystem"
]
}
}
}
Restart the agent:
1 openclaw gateway restart
Recommended Skills for Beginners
- npm: Install Node.js packages on the fly
- brave_search: Web search for real-time information
- filesystem: Read/write files in workspace
- calendar: Google Calendar integration (requires OAuth)
- email: Send emails via SMTP
For a full list:
1 openclaw skills list
Step 6: Configure Heartbeat for Proactive Tasks
Heartbeats enable your agent to check for updates, monitor services, and alert you proactively. When you set up OpenClaw AI agent automation, heartbeats transform passive assistants into active monitors.
Basic Heartbeat Configuration
Edit
1 | ~/.openclaw/openclaw.json |
:
1
2
3
4
5
6
7
8
9
10 {
"agents": {
"defaults": {
"heartbeat": {
"every": "1h",
"prompt": "Check: Any urgent emails, calendar events in next 2 hours, or system alerts?"
}
}
}
}
Restart gateway:
1 openclaw gateway restart
Advanced: Rotate Tasks with HEARTBEAT.md
Create
1 | workspace/HEARTBEAT.md |
:
1
2
3
4
5
6
7
8
9
10
11
12
13 ## Heartbeat Checklist (Rotate Daily)
### Morning (08:00-12:00)
- Check unread emails
- Review calendar for today
### Afternoon (12:00-18:00)
- Monitor GitHub notifications
- Check server status
### Evening (18:00-23:00)
- Summarize today's activity
- Prepare tomorrow's tasks
Your agent reads this file on each heartbeat and executes appropriate checks based on the current time.
Step 7: Verify Daemon and Persistence
Ensure OpenClaw survives reboots by verifying daemon configuration.
Check Daemon Status
1 openclaw gateway status
Expected output:
1
2
3 Gateway Status: running
PID: 12345
Uptime: 2 hours
Enable Daemon (If Not Active)
1 openclaw onboard --install-daemon
On Linux/macOS, this creates a systemd or launchd service. On Windows, it registers a scheduled task.
Test Persistence
Reboot your machine, then check status:
1 openclaw gateway status
If the gateway is running, daemon configuration is correct. If not:
1 openclaw gateway start
Step 8: Customize Workspace and Memory
OpenClaw maintains a workspace directory at
1 | ~/.openclaw/workspace |
. Key files:
-
1SOUL.md
: Agent personality (already covered)
-
1USER.md
: Information about you (name, preferences, timezone)
-
1TOOLS.md
: Local notes (SSH hosts, camera names, API keys)
-
1MEMORY.md
: Long-term memory (decisions, learnings, context)
-
1memory/YYYY-MM-DD.md
: Daily activity logs
Create USER.md
1
2
3
4
5
6
7
8 cat > ~/.openclaw/workspace/USER.md << EOF
# USER.md
- Name: Your Name
- Timezone: America/New_York
- Pronouns: they/them
- Preferred communication style: Direct, technical
EOF
Initialize Memory
Send to your agent:
1 Remember: I prefer concise responses with code examples. I work remotely from 9 AM to 5 PM EST. I dislike notifications after 10 PM.
The agent writes this to
1 | MEMORY.md |
and recalls it in future sessions.
Advanced Configuration: Multiple Agents
When you set up OpenClaw AI agent infrastructure at scale, you can run multiple specialized agents.
Create Second Agent
1 openclaw agents create --name code-reviewer --model anthropic/claude-3-5-sonnet
Configure personality:
1 openclaw chat code-reviewer "Update your SOUL.md: You are a code reviewer. Analyze pull requests, suggest improvements, enforce style guides."
Route Messages to Specific Agents
In Telegram, prefix messages with agent name:
1 @code-reviewer Review this function: [code]
For more multi-agent patterns, check our guide on orchestrating multiple AI agents.
Troubleshooting Common Issues
Issue 1: Agent Not Responding
Symptoms: Messages to Telegram bot go unanswered.
Solutions:
- Check gateway status:
1openclaw gateway status
- View logs:
1openclaw logs --follow
- Verify bot token:
1openclaw config get channels.telegram.token
- Test model:
1openclaw models status
Issue 2: Daemon Not Starting After Reboot
Symptoms:
1 | openclaw gateway status |
shows “not running” after restart.
Solutions:
- Reinstall daemon:
1openclaw onboard --install-daemon
- Check system service:
- Linux:
1systemctl status openclaw-gateway
- macOS:
1launchctl list | grep openclaw
- Linux:
- Start manually:
1openclaw gateway start
Issue 3: High API Costs
Symptoms: Unexpected charges from AI provider.
Solutions:
- Switch to cheaper model: OpenRouter’s Kimi K2.5 ($0.10/M tokens)
- Reduce heartbeat frequency: Change
1every: "1h"
to
1every: "6h" - Use local LLM for non-critical tasks
- Monitor usage:
1openclaw usage --last 7d
Issue 4: Skills Not Working
Symptoms: Agent says “I don’t have access to that skill.”
Solutions:
- Verify skill installation:
1openclaw skills list
- Enable skill:
1openclaw config set agents.defaults.skills[+] skill_name
- Restart gateway:
1openclaw gateway restart
- Check permissions: Some skills need extra setup (e.g., OAuth for calendar)
Security Best Practices
When you set up OpenClaw AI agent deployments, security is paramount:
- Use dedicated accounts: Create secondary Google/email accounts for agent integrations
- Enable prompt injection protection:
1openclaw config set security.promptInjection.enabled true
- Restrict file access: Sandbox skills to specific directories
- Rotate API keys: Regenerate provider keys quarterly
- Monitor logs: Review
1openclaw logs
weekly for suspicious activity
- Backup workspace:
1tar -czf openclaw-backup.tar.gz ~/.openclaw/workspace
Monitoring and Maintenance
Weekly Tasks
- Check usage:
1openclaw usage --last 7d
- Review logs:
1openclaw logs | grep ERROR
- Update OpenClaw:
1npm update -g openclaw
Monthly Tasks
- Audit memory files: Review
1workspace/memory/*.md
for stale data
- Test failover: Simulate API outage, verify fallback models
- Backup workspace:
1rsync -av ~/.openclaw/workspace /backup/
Essential Commands
1
2
3
4
5
6
7
8
9
10
11
12
13
14 # Show agent status
openclaw status
# View real-time logs
openclaw logs --follow
# Check model health
openclaw models status
# List active sessions
openclaw sessions list
# Run diagnostics
openclaw doctor
Real-World Use Cases
After you set up OpenClaw AI agent infrastructure, explore these automation scenarios:
1. DevOps Monitoring
- Monitor server logs for errors
- Alert on failed deployments
- Auto-restart crashed services
2. Personal Productivity
- Summarize unread emails every morning
- Remind about calendar events 15 minutes before
- Track time spent on projects
3. Content Creation
- Draft blog posts from outlines
- Generate social media posts from articles
- Proofread documents for grammar and style
4. Smart Home Integration
- Control lights via voice commands (Telegram)
- Monitor security cameras for motion
- Adjust thermostat based on weather forecasts
Conclusion: Your OpenClaw Agent Is Ready
You’ve successfully learned how to set up OpenClaw AI agent from installation to advanced configuration. Here’s your setup checklist:
- ✅ OpenClaw installed with daemon enabled
- ✅ AI model provider configured (Anthropic, OpenRouter, or local)
- ✅ Telegram bot created and connected
- ✅ SOUL.md personality defined
- ✅ Essential skills enabled (npm, search, filesystem)
- ✅ Heartbeat configured for proactive monitoring
- ✅ Workspace initialized with USER.md and MEMORY.md
- ✅ Daemon persistence verified across reboots
Your agent now operates 24/7, responding to messages, executing tasks, and monitoring for alerts. As you gain experience, layer additional skills, create specialized agents, and build complex automation workflows.
OpenClaw’s power lies in its flexibility. Whether you automate DevOps pipelines, manage personal projects, or control smart home devices, you’ve built the foundation for limitless automation.
For advanced topics, explore our tutorials on AI agent skill development and self-hosted AI infrastructure.
- About the Author
- Latest Posts
Mark is a senior content editor at Text-Center.com and has more than 20 years of experience with linux and windows operating systems. He also writes for Biteno.com