---
sidebar_label: "101: Your First Agent"
---

# 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](https://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:

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

Verify the installation:

```bash
$ 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:

```bash
$ 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](../guides/host-setup.md) for the full reference), then continue.

## Step 3: Re-run to Register the Host

```bash
$ 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:

```bash
$ 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:

```bash
$ 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:

```bash
$ 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:

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

## Step 8: Chat with Your Agent

Start a conversation:

```bash
$ 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:

```bash
$ 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

- [Fleet Management Guide](/docs/guides/fleet-management) - Manage multiple agents
- [Agent Onboarding Guide](/docs/guides/agent-onboarding) - Detailed agent configuration
- [Channels](/docs/agent-support/channels) - Connect agents to Discord, Slack, etc.
