Skip to main content

101: Your First Agent

Install an openclaw agent on a target host and have your first conversation.

Prerequisites​

Before starting, you need:

  • Control machine: Your local computer with Python 3.10+ and uv installed
  • Target host: A Linux machine (Ubuntu 24.04 recommended) accessible via SSH
  • SSH access: Ability to SSH to the target as a user with sudo privileges
  • API key: An Anthropic API key (get one at console.anthropic.com)

What You'll Build​

┌─────────────────────┐                    ┌─────────────────────┐
│   Control Machine   │                    │    Target Host      │
│                     │                    │                     │
│  ┌───────────────┐  │      SSH           │  ┌───────────────┐  │
│  │   clawctl CLI     │──┼────────────────────┼──│   openclaw    │  │
│  └───────────────┘  │                    │  │   (agent)     │  │
│                     │                    │  └───────────────┘  │
│  You type here      │                    │  Runs here          │
└─────────────────────┘                    └─────────────────────┘

Step 1: Install Clawrium​

On your control machine, install the clawctl CLI:

$ uv tool install clawrium
Resolved 1 package in 2.34s
Installed 1 executable: clawctl

Verify the installation:

$ clawctl --version
clawctl 26.6.3

Step 2: Register the Host (first run — surface the manual setup)​

clawctl host create generates a per-host keypair and verifies SSH access as xclm. On a fresh host that user doesn't exist yet, so the first invocation prints the manual setup commands (Linux + macOS, with your public key inlined) and exits non-zero:

$ clawctl host create 192.168.1.100 --user xclm --alias mybox
Generating SSH keypair for '192.168.1.100'...
Keypair created: /home/you/.config/clawrium/keys/192.168.1.100/xclm_ed25519.pub
xclm SSH verification failed: Authentication failed - check SSH keys

Manual setup required. Log into the host with a sudo-capable user and
run the block that matches its OS:

## Linux
sudo useradd -m -s /bin/bash xclm
…

## macOS
sudo dscl . -create /Users/xclm
…
sudo dseditgroup -o edit -a xclm -t user com.apple.access_ssh

Then re-run: clawctl host create 192.168.1.100 --user xclm

Paste the appropriate block on the host (see the Host Setup guide for the full reference), then continue.

Step 3: Re-run to Register the Host​

$ clawctl host create 192.168.1.100 --user xclm --alias mybox
Detecting hardware capabilities...
Hardware detected: x86_64, 4 cores, 8192MB RAM

Host 'mybox' added successfully!

Step 4: Add Your API Provider​

Configure Anthropic as your AI provider:

$ clawctl provider registry create anthropic --type anthropic
Enter your Anthropic API key: sk-ant-api03-...
Provider 'anthropic' added successfully!

Step 5: Install the Agent​

Install openclaw on your target host:

$ clawctl agent create --type openclaw --host mybox
Creating user 'oc-default' on 'mybox'...
Installing openclaw for user 'oc-default'...
Configuring systemd service...

Agent 'oc-default-mybox' installed successfully!

Step 6: Configure the Agent​

Link the agent to your provider and set preferences:

$ clawctl agent configure oc-default-mybox
Configuring agent 'oc-default-mybox'...

Provider: anthropic
Model: claude-sonnet-4-20250514

Configuration saved!

Step 7: Start the Agent​

Start the agent service:

$ clawctl agent start oc-default-mybox
Starting agent 'oc-default-mybox'...
Agent started successfully!

Step 8: Chat with Your Agent​

Start a conversation:

$ clawctl agent chat oc-default-mybox
Connected to oc-default-mybox

You: Hello! What can you help me with?

Agent: Hello! I'm an AI assistant running on your server. I can help you with:
- Answering questions on various topics
- Writing and reviewing code
- Explaining concepts
- Brainstorming ideas

What would you like to explore?

You: /exit
Disconnected.

Verification​

Check that everything is running:

$ clawctl agent get
                        Fleet Status
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Agent              ┃ Host   ┃ Type      ┃ Status     ┃ Provider    ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ oc-default-mybox   │ mybox  │ openclaw  │ running    │ anthropic   │
└────────────────────┴────────┴───────────┴────────────┴─────────────┘

Troubleshooting​

SSH Connection Failed​

If clawctl host create keeps failing the xclm SSH check after you run the manual commands:

  1. Verify you can SSH manually: ssh myuser@192.168.1.100
  2. Check that the user has sudo access: sudo whoami should return root
  3. Ensure port 22 is open: nc -zv 192.168.1.100 22

Agent Won't Start​

If clawctl agent start fails:

  1. Check agent logs: clawctl agent logs oc-default-mybox
  2. Verify provider is configured: clawctl provider registry get
  3. Test host connectivity: clawctl host describe mybox

Chat Disconnects Immediately​

If the chat session closes:

  1. Ensure the agent is running: clawctl agent get
  2. Check the agent's systemd logs on the host directly via SSH (e.g. ssh xclm@mybox -- journalctl --user -u openclaw-oc-default-mybox -n 200); clawctl agent logs is not yet available.

Next Steps​