Quickstart
Deploy your first OpenClaw instance in under 5 minutes. This guide walks through the complete workflow from installation to a running agent.
What You'll Need
Before you start, verify you have:
| Requirement | How to Check |
|---|---|
| Python 3.10+ | python3 --version |
| uv installed | uv --version |
| Target host ready | Ubuntu 22.04/24.04 with SSH access |
| API key | OpenAI or Anthropic API key |
You can still follow along through Step 3 to set up Clawrium locally. You'll need a target host (VM, Raspberry Pi, spare machine) for the agent deployment steps.
Step 1: Install Clawrium
Install on your control machine:
uv tool install clawrium
Resolved 1 package in 523ms
Installed 1 package in 12ms
+ clawrium==26.6.0
Verify installation:
clawctl --help
Usage: clawctl [OPTIONS] COMMAND [ARGS]...
clawctl — manage your AI assistant fleet, kubectl-style.
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ service System-level lifecycle ops (init, snapshot, ...) │
│ host Manage hosts in your fleet │
│ provider Manage inference providers (LLM APIs) │
│ integration Manage external service integrations │
│ channel Manage chat-channel attachables (Discord, Slack, ...) │
│ skill Browse the skills catalog │
│ agent Manage agents in your fleet │
│ tui Launch the interactive TUI dashboard │
│ gui Launch the local web GUI dashboard │
│ version Show clawctl version and exit │
│ completion Emit a shell-completion script │
╰──────────────────────────────────────────────────────────────────────────────╯
Step 2: Initialize Clawrium
Create the configuration directory and validate dependencies:
clawctl service init
✓ Configuration directory created at ~/.config/clawrium/
✓ Ansible found: ansible [core 2.15.0]
✓ SSH client found: OpenSSH_9.0p1
✓ Dependencies validated
Clawrium is ready! Next: clawctl host create <hostname> --user xclm --alias <name>
Step 3: Prepare a Host
Register the target host. On first run Clawrium generates a per-host
keypair and prints the manual xclm setup commands you need to paste on
the host (see the Host Setup guide for full
Linux + macOS instructions):
clawctl host create 192.168.1.100 --user xclm --alias mybox
Replace 192.168.1.100 with your target host's IP or hostname and
mybox with a friendly alias.
Generating SSH keypair for 192.168.1.100...
✓ Keypair saved to ~/.config/clawrium/keys/192.168.1.100/
Connecting to 192.168.1.100 as myuser...
Password for myuser@192.168.1.100: ********
Configuring xclm user on remote host...
Creating user 'xclm'...
Configuring passwordless sudo...
Adding SSH public key...
✓ Host initialization complete
Next: clawctl host create 192.168.1.100 --alias <friendly-name>
If automatic setup fails (e.g., password authentication disabled), Clawrium shows manual setup instructions. Follow them on the target host, then continue to the next step.
Step 4: Add the Host
Add the initialized host to your fleet:
clawctl host create 192.168.1.100 --alias homelab
Connecting to 192.168.1.100 as xclm...
Unknown host key for 192.168.1.100
Fingerprint: SHA256:abc123def456...
Accept this host key? [y/N]: y
✓ Host key saved
Detecting hardware capabilities...
CPU: 4 cores (x86_64)
Memory: 16 GB
GPU: None detected
✓ Host 'homelab' added to fleet
Verify with:
clawctl host get
Alias Host Architecture Cores Memory (GB) Tags
──────────────────────────────────────────────────────────────────────
homelab 192.168.1.100 x86_64 4 16.0 -
Step 5: Install the Agent
Install OpenClaw on your host:
clawctl agent create my-assistant --type openclaw --host homelab
Fetching openclaw manifest...
✓ Manifest loaded: openclaw v1.2.0
Installing on homelab...
Installing system dependencies...
Creating agent user 'oc-my-assistant'...
Deploying agent files...
Creating systemd service...
✓ Agent 'my-assistant' installed
Next: clawctl agent configure my-assistant
Step 6: Configure the Agent
Run the configuration wizard:
clawctl agent configure my-assistant
═══════════════════════════════════════════════════════════
OpenClaw Configuration: my-assistant
═══════════════════════════════════════════════════════════
Stage 1/4: Provider Setup
─────────────────────────
Select primary LLM provider:
1. OpenAI
2. Anthropic
3. OpenRouter
> 2
Enter Anthropic API key: ********
Testing connection... ✓ Connected
Stage 2/4: Identity
───────────────────
Agent name [my-assistant]:
Description [A helpful AI assistant]: My homelab assistant
Stage 3/4: Channels
──────────────────
Enable CLI channel? [Y/n]: y
Enable Discord channel? [y/N]: n
Stage 4/4: Validation
────────────────────
✓ Provider: Anthropic (claude-3-5-sonnet)
✓ Channels: CLI
✓ Configuration valid
Configuration complete. Run 'clawctl agent start my-assistant' to start your agent.
Step 7: Check Fleet Status
Verify your fleet:
clawctl agent get
HOST AGENT TYPE PROVIDER STATUS UPTIME
──────────────────────────────────────────────────────────────────
homelab my-assistant openclaw anthropic running 1m
Step 8: Chat with Your Agent
Test your agent:
clawctl agent chat my-assistant
Connected to my-assistant (openclaw) on homelab
Type 'exit' to quit, 'help' for commands
You: Hello! What can you help me with?
my-assistant: Hello! I'm your homelab assistant running on OpenClaw.
I can help you with:
- Answering questions and research
- Writing and editing text
- Brainstorming ideas
- General assistance
What would you like to work on today?
You: exit
Disconnected.
What's Next?
- Host Setup Guide - Detailed host preparation options
- Agent Onboarding - Deep dive into agent configuration
- OpenClaw Support Matrix - Providers, channels, integrations
- Fleet Management - Managing multiple agents
Troubleshooting
Connection refused during clawctl host create
SSH isn't running or is blocked by firewall on the target host:
# On target host
sudo systemctl status sshd
sudo ufw allow ssh
Permission denied during clawctl host create
The xclm management user hasn't been created on the target, or the per-host
public key hasn't been added to ~xclm/.ssh/authorized_keys. Follow the
manual setup commands printed by clawctl host create on its first run, or
see the Host Setup guide for the full Linux + macOS steps.
Agent won't start
Check the agent logs:
clawctl agent logs my-assistant
Common issues:
- Invalid API key (re-run
clawctl agent configure my-assistant --stage providers) - Port already in use (check with
clawctl agent describe my-assistant)