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

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:

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

Verify the installation:

$ clm --version
clm 26.4.5

Step 2: Initialize the Target Host​

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

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

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

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

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

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

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

Step 8: Chat with Your Agent​

Start a conversation:

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

$ 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​