clawctl agent

Manage agent lifecycle: install, configure, start, stop, and monitor agents.

Synopsis

clawctl agent <command> [options]

Commands

install

Install an agent on a host.

clawctl agent create <agent-type> --host <host> --name <agent-name> [options]

Arguments:

agent-type - Type of agent to install (e.g., openclaw, zeroclaw, nanoclaw)

Options:

--host <hostname> - Target host (required)
--name <name> - Agent instance name (required)
--version <version> - Specific version to install (default: latest)
--user <username> - User to run the agent as (default: from manifest)

Examples:

# Install latest openclaw
clawctl agent create openclaw --host lab1 --name opc-work

# Install specific version
clawctl agent create zeroclaw --host pi4 --name zc-edge --version 2026.3.0

# Install with custom user
clawctl agent create openclaw --host lab2 --name opc-dev --user alice

What happens:

Verifies host compatibility
Downloads agent package
Deploys to host
Initializes onboarding (state: PENDING)
Returns installation summary

Success output:

✓ Installed openclaw v2026.4.2 on lab1
✓ Agent: opc-work
✓ Status: PENDING (onboarding required)

Next step: clawctl agent configure opc-work

Related:

clawctl agent registry describe - Check agent requirements before install
clawctl agent configure - Configure the installed agent

configure

Configure an agent through interactive onboarding wizard.

clawctl agent configure <agent-name> [options]

Arguments:

agent-name - Name of the agent to configure

Options:

--stage <stage> / -s - Configure specific stage only (providers, identity, channels, validate)
--yes / -y - Accept defaults and skip confirmations
--file <path> / -f - Import identity file (SOUL.md, AGENTS.md, TOOLS.md, IDENTITY.md). Repeatable. Only valid with --stage identity
--skip-health - Skip OpenClaw gateway health verification during validate stage
--edit-config - Open agent config file in editor for direct editing. Cannot be combined with --stage, --file, or --skip-health
--editor <command> - Editor command for --edit-config (e.g., vim, nano). Falls back to VISUAL, then EDITOR, then vi

Examples:

# Full interactive wizard
clawctl agent configure opc-work

# Configure specific stage
clawctl agent configure opc-work --stage providers
clawctl agent configure opc-work --stage identity

# Non-interactive (use defaults)
clawctl agent configure opc-work --yes

# Import identity file
clawctl agent configure opc-work --stage identity --file ~/SOUL.md

# Edit config directly in default editor
clawctl agent configure opc-work --edit-config

# Edit config with specific editor
clawctl agent configure opc-work --edit-config --editor nano

Stages:

Stage	Purpose	Skippable?
providers	Assign inference provider	No
identity	Configure personality/behavior	Depends on agent type
channels	Set up communication methods	Depends on agent type
validate	Verify configuration	No

Interactive wizard flow:

$ clawctl agent configure opc-work

Starting onboarding for 'opc-work' (openclaw)
Current state: PENDING

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[1/4] PROVIDERS - Select Inference Provider
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Available providers:
  1. openai-prod (OpenAI GPT-4)
  2. local-ollama (Ollama - llama3:latest)

Select provider [1-2]: 1
✓ Provider 'openai-prod' assigned

[... continues through remaining stages ...]

✓ Onboarding complete! 'opc-work' is ready to start.

Related:

Agent Onboarding Guide - Detailed onboarding walkthrough
clawctl agent describe - Check configuration progress

start

Start a configured agent.

clawctl agent start <agent-name> [options]

Arguments:

agent-name - Name of the agent to start

Options:

--wait - Wait for agent to be fully running before returning
--timeout <seconds> - Max wait time (default: 30)

Examples:

# Start agent
clawctl agent start opc-work

# Start and wait for confirmation
clawctl agent start opc-work --wait

# Start with custom timeout
clawctl agent start opc-work --wait --timeout 60

Requirements:

Agent must be in READY state (onboarding complete)
Host must be reachable
Required secrets must be set

Success output:

✓ Starting 'opc-work' on lab1...
✓ Agent started successfully

Error: Onboarding incomplete:

✗ Cannot start 'opc-work' - onboarding incomplete

Status: ONBOARDING (2/4 stages)

Remaining stages:
  - channels
  - validate

Complete onboarding: clawctl agent configure opc-work

Related:

clawctl agent stop - Stop a running agent
clawctl agent describe - Check if agent is running

stop

Stop a running agent.

clawctl agent stop <agent-name> [options]

Arguments:

agent-name - Name of the agent to stop

Options:

--force - Force stop (send SIGKILL instead of graceful shutdown)
--timeout <seconds> - Wait time before force kill (default: 10)

Examples:

# Graceful stop
clawctl agent stop opc-work

# Force stop immediately
clawctl agent stop opc-work --force

# Graceful with custom timeout
clawctl agent stop opc-work --timeout 30

Success output:

✓ Stopping 'opc-work' on lab1...
✓ Agent stopped successfully

Related:

clawctl agent start - Start a stopped agent
clawctl agent restart - Restart a running agent

restart

Restart a running agent (stop + start).

clawctl agent restart <agent-name> [options]

Arguments:

agent-name - Name of the agent to restart

Options:

--wait - Wait for agent to be fully running after restart
--force - Force stop before restart

Examples:

# Restart agent
clawctl agent restart opc-work

# Force restart
clawctl agent restart opc-work --force

# Restart and wait for confirmation
clawctl agent restart opc-work --wait

Success output:

✓ Stopping 'opc-work' on lab1...
✓ Agent stopped
✓ Starting 'opc-work' on lab1...
✓ Agent started successfully

status

Display agent status and health information.

clawctl agent describe [agent-name] [options]

Arguments:

agent-name - Specific agent to check (optional - shows all if omitted)

Options:

--verbose - Show detailed information including onboarding progress
--json - Output in JSON format

Examples:

# Show all agents
clawctl agent describe

# Show specific agent
clawctl agent describe opc-work

# Detailed view with onboarding progress
clawctl agent describe opc-work --verbose

# JSON output for scripting
clawctl agent describe --json

Output (all agents):

Agent Status:
┌──────────┬──────┬───────┬─────────────┬──────────┐
│ Name     │ Host │ Type  │ Status      │ Progress │
├──────────┼──────┼───────┼─────────────┼──────────┤
│ opc-work │ lab1 │ opc   │ RUNNING     │ 4/4      │
│ zc-edge  │ pi4  │ zc    │ READY       │ 4/4      │
│ opc-home │ lab1 │ opc   │ ONBOARDING  │ 2/4      │
│ nc-test  │ lab2 │ nc    │ PENDING     │ 0/4      │
└──────────┴──────┴───────┴─────────────┴──────────┘

Output (verbose):

$ clawctl agent describe opc-work --verbose

Agent: opc-work
Host: lab1 (192.168.1.100)
Type: openclaw v2026.4.2
Status: RUNNING
Process ID: 12345
Uptime: 2d 5h 32m

Onboarding: COMPLETE (4/4 stages)
  ✓ PROVIDERS  (completed 2026-04-05 10:02:00 UTC)
    Provider: openai-prod (OpenAI GPT-4)

  ✓ IDENTITY   (completed 2026-04-05 10:05:00 UTC)
    Files: SOUL.md, IDENTITY.md

  ✓ CHANNELS   (completed 2026-04-05 10:07:00 UTC)
    Default: CLI

  ✓ VALIDATE   (completed 2026-04-05 10:08:00 UTC)

Resource Usage:
  CPU: 2.3%
  Memory: 245 MB
  Disk: 1.2 GB

Health: HEALTHY
  Last check: 2026-04-07 15:30:00 UTC
  Response time: 120ms

Status values:

Status	Description	Can Start?
`PENDING`	Installed, onboarding not started	❌ No
`ONBOARDING`	Configuration in progress	❌ No
`READY`	Configured, not running	✅ Yes
`RUNNING`	Active and operational	-
`STOPPED`	Previously running, now stopped	✅ Yes
`ERROR`	Configuration or runtime error	❌ No

Related:

clawctl agent logs - View agent logs
Agent Onboarding Guide - Understanding onboarding states

logs

View agent logs.

clawctl agent logs <agent-name> [options]

Arguments:

agent-name - Name of the agent

Options:

--follow / -f - Stream logs in real-time
--lines <n> / -n <n> - Number of lines to show (default: 50)
--since <time> - Show logs since timestamp (e.g., "2h", "30m", "2024-01-01")
--level <level> - Filter by log level (debug, info, warn, error)

Examples:

# Show last 50 lines
clawctl agent logs opc-work

# Show last 200 lines
clawctl agent logs opc-work --lines 200

# Follow logs in real-time
clawctl agent logs opc-work --follow

# Show logs from last 2 hours
clawctl agent logs opc-work --since 2h

# Show only errors
clawctl agent logs opc-work --level error

Output:

2026-04-07 15:30:15 [INFO] Agent started successfully
2026-04-07 15:30:16 [INFO] Connected to provider: openai-prod
2026-04-07 15:30:17 [INFO] Ready to accept requests
2026-04-07 15:32:45 [INFO] Processing request: "What's the weather?"
2026-04-07 15:32:47 [INFO] Request completed (2.1s)

Related:

clawctl agent describe - Check agent health
Troubleshooting Guide - Debugging common issues

remove

Remove an agent from a host.

clawctl agent delete <agent-name> [options]

Arguments:

agent-name - Name of the agent to remove

Options:

--force - Skip confirmation prompt
--keep-data - Preserve agent data and configuration files

Examples:

# Remove with confirmation
clawctl agent delete opc-work

# Force remove (no prompt)
clawctl agent delete opc-work --force

# Remove but keep data
clawctl agent delete opc-work --keep-data

Interactive prompt:

Remove agent 'opc-work' from host 'lab1'?
This will:
  - Stop the agent (if running)
  - Remove the installation
  - Delete configuration and data

Are you sure? [y/N]: y

✓ Stopping agent...
✓ Removing installation...
✓ Cleaning up data...
✓ Agent 'opc-work' removed from lab1

Warning: By default, removal is permanent and deletes all agent data including:

Configuration files
Identity files (SOUL.md, IDENTITY.md)
Logs and session history
Cache and temporary files

Use --keep-data to preserve these files for later reinstallation.

list

List all installed agents across the fleet.

clawctl agent list [options]

Options:

--host <hostname> - Filter by host
--type <agent-type> - Filter by agent type
--status <status> - Filter by status (pending, onboarding, ready, running, stopped, error)
--json - Output in JSON format

Examples:

# List all agents
clawctl agent list

# List agents on specific host
clawctl agent list --host lab1

# List all openclaw instances
clawctl agent list --type openclaw

# List running agents only
clawctl agent list --status running

# JSON output
clawctl agent list --json

Output:

Installed Agents (4):

┌──────────┬──────┬─────────┬─────────────┬────────────┐
│ Name     │ Host │ Type    │ Version     │ Status     │
├──────────┼──────┼─────────┼─────────────┼────────────┤
│ opc-work │ lab1 │ openclaw│ 2026.4.2    │ RUNNING    │
│ opc-home │ lab1 │ openclaw│ 2026.4.2    │ READY      │
│ zc-edge  │ pi4  │ zeroclaw│ 2026.3.1    │ RUNNING    │
│ nc-test  │ lab2 │ nanoclaw│ 2026.2.0    │ ONBOARDING │
└──────────┴──────┴─────────┴─────────────┴────────────┘

upgrade

Upgrade an agent to the registry's max supported version for the host's hardware. Forward-only: there is no --version pin and no downgrade path — the manifest is the contract.

clawctl agent upgrade <agent-name> [options]

Arguments:

agent-name - Name of the agent to upgrade

Options:

--yes, -y - Skip confirmation prompt
--skip-drift-check - Bypass the drift pre-flight gate (hidden; escape hatch)
-o, --output <fmt> - Output format: table (default) or json

Examples:

# Upgrade to the manifest's max supported version
clawctl agent upgrade opc-work

# Non-interactive
clawctl agent upgrade opc-work --yes

# JSON output (implies --yes-equivalent: no confirmation prompt)
clawctl agent upgrade opc-work -o json

Pre-flight rejection cases:

Already at max — exits 0 with already at latest (<version>). No work is performed.
Downgrade refused — if the manifest's max is older than the installed version (only possible if entries were removed from the manifest), the command exits non-zero. Restore the manifest entries or reinstall.
Drift refused — if any rendered config file differs from the on-host state, the command lists the changed files and exits non-zero. Run clawctl agent sync first, or re-run with --skip-drift-check to bypass.
Drift bypass — --skip-drift-check proceeds without comparing rendered vs. on-host files. The upgrade is force-installed in place.

Notes:

Onboarding configuration, secrets, and identity files are preserved.
For zeroclaw agents, the gateway bearer is rotated as part of the canonical lifecycle (see AGENTS.md §"Gateway Token Lifecycle"). Remote clawctl agent chat sessions must reconnect after upgrade.

clawctl provider

Manage inference providers used by agents.

clawctl provider registry get          # List configured providers
clawctl provider registry create           # Add new provider
clawctl provider registry delete        # Remove provider

See clawctl provider for full reference.

clawctl agent secret

Manage agent secrets and API keys.

clawctl agent secret create <agent> <key>     # Set secret value
clawctl agent secret get --agent <agent>          # List required secrets
clawctl agent secret delete <agent> <key>  # Remove secret

See clawctl agent secret for full reference.

clawctl agent registry

Browse available agent types.

clawctl agent registry get          # List available agents
clawctl agent registry describe <type>   # Show agent details

See clawctl agent registry for full reference.

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	Agent not found
4	Host unreachable
5	Onboarding incomplete
6	Permission denied

Example usage in scripts:

#!/bin/bash
clawctl agent start opc-work
if [ $? -eq 5 ]; then
  echo "Onboarding required"
  clawctl agent configure opc-work --yes
  clawctl agent start opc-work
fi

Environment Variables

Variable	Description	Default
`CLAWRIUM_CONFIG`	Config directory path	`~/.config/clawrium`
`CLAWRIUM_LOG_LEVEL`	Logging verbosity	`info`
`CLAWRIUM_TIMEOUT`	Default operation timeout (seconds)	`30`

Synopsis​

Commands​

install​

configure​

start​

stop​

restart​

status​

logs​

remove​

list​

upgrade​

Related Commands​

clawctl provider​

clawctl agent secret​

clawctl agent registry​

Exit Codes​

Environment Variables​

See Also​

Synopsis

Commands

install

configure

start

stop

restart

status

logs

remove

list

upgrade

Related Commands

clawctl provider

clawctl agent secret

clawctl agent registry

Exit Codes

Environment Variables

See Also