---
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.11+ 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           │  ┌───────────────┐  │
│  │   clm CLI     │──┼────────────────────┼──│   openclaw    │  │
│  └───────────────┘  │                    │  │   (agent)     │  │
│                     │                    │  └───────────────┘  │
│  You type here      │                    │  Runs here          │
└─────────────────────┘                    └─────────────────────┘
```

## Step 1: Install Clawrium

On your control machine, install the `clm` CLI:

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

Verify the installation:

```bash
$ clm --version
clm 26.5.2
```

## Step 2: Initialize the Target Host

Generate SSH keys and configure the management user on your target host:

```bash
$ clm host init 192.168.1.100 --user myuser
Generating SSH keypair for '192.168.1.100'...
Keypair created: /home/you/.config/clawrium/keys/192.168.1.100.pub

Attempting connection to 192.168.1.100 as myuser...
Connection successful!
Setting up xclm management user...

Verifying xclm access...
xclm user configured successfully!

Next step: clm host add 192.168.1.100
```

Replace `192.168.1.100` with your target host's IP and `myuser` with your SSH username.

## Step 3: Add the Host to Your Fleet

Register the host with an alias:

```bash
$ clm host add 192.168.1.100 --alias mybox
Testing connection to 192.168.1.100:22 as xclm...
Connection successful!
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
$ clm provider add 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
$ clm agent install --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
$ clm 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
$ clm agent start oc-default-mybox
Starting agent 'oc-default-mybox'...
Agent started successfully!
```

## Step 8: Chat with Your Agent

Start a conversation:

```bash
$ clm 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
$ clm ps
                        Fleet Status
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Agent              ┃ Host   ┃ Type      ┃ Status     ┃ Provider    ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ oc-default-mybox   │ mybox  │ openclaw  │ running    │ anthropic   │
└────────────────────┴────────┴───────────┴────────────┴─────────────┘
```

## Troubleshooting

### SSH Connection Failed

If `clm host init` fails:

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 `clm agent start` fails:

1. Check agent logs: `clm agent logs oc-default-mybox`
2. Verify provider is configured: `clm provider list`
3. Test host connectivity: `clm host status mybox`

### Chat Disconnects Immediately

If the chat session closes:

1. Ensure the agent is running: `clm agent status oc-default-mybox`
2. Check for API key issues in logs: `clm agent logs oc-default-mybox --tail 20`

## 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.
