Skip to main content

clawctl agent

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

Synopsis​

clawctl agent <command> [options]

Commands​

create​

Install an agent on a host.

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

Arguments:

  • agent-name - Name for the new agent instance (positional, required)

Options:

  • --type, -t <agent-type> - Agent type, e.g. openclaw, zeroclaw, hermes (required)
  • --host, -H <hostname> - Target host, name or alias (required)
  • --provider, -P <name> - Initial provider to attach (required for openclaw since v26.7.3; see below)
  • --yes, -y - Skip confirmation prompts
  • --force, -f - Reinstall even if the same version is already present
  • --cleanup-failed - Remove a failed installation before retrying

Examples:

# Install hermes
clawctl agent create maurice --type hermes --host lab1

# Install openclaw — provider is mandatory (since v26.7.3)
clawctl agent create opc-work --type openclaw --host lab1 --provider clm-openrouter

# Install zeroclaw
clawctl agent create zc-edge --type zeroclaw --host pi4

# Retry after a failed install
clawctl agent create opc-work --type openclaw --host lab1 --provider clm-openrouter --cleanup-failed

--provider is mandatory for openclaw. Since v26.7.3, every openclaw instance runs inside an NVIDIA NemoClaw sandbox, and the NemoClaw onboarding flow requires a provider at install time. Without --provider, the command exits with a hint to list available providers via clawctl provider registry get. Other agent types (hermes, zeroclaw) still use the split create → configure lifecycle where provider selection happens during clawctl agent configure.

What happens:

  1. Verifies host compatibility
  2. Downloads agent package
  3. Deploys to host
  4. Initializes onboarding (state: PENDING)
  5. 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:

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:

StagePurposeSkippable?
providersAssign inference providerNo
identityConfigure personality/behaviorDepends on agent type
channelsSet up communication methodsDepends on agent type
validateVerify configurationNo

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:

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:

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:

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:

StatusDescriptionCan Start?
PENDINGInstalled, onboarding not started❌ No
ONBOARDINGConfiguration in progress❌ No
READYConfigured, not running✅ Yes
RUNNINGActive and operational-
STOPPEDPreviously running, now stopped✅ Yes
ERRORConfiguration or runtime error❌ No

Related:

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:

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.

get​

List all installed agents across the fleet.

clawctl agent get [options]

Options:

  • --output, -o <format> - Output format: table (default), json, yaml, wide, name
  • --selector, -l <KEY=VALUE> - Filter by host label. Repeatable
  • --no-headers - Omit the header row (table mode only)

Examples:

# List all agents
clawctl agent get

# Filter by host label
clawctl agent get -l env=prod

# Extra columns (address, port, version, install time)
clawctl agent get -o wide

# JSON output
clawctl agent get -o json

Output:

NAME       TYPE       HOST   PROVIDER         STATUS       AGE   RUNTIME
opc-work   openclaw   lab1   clm-openrouter   running      3d    nemoclaw@v0.0.97
opc-home   openclaw   lab1   clm-openrouter   ready        3d    nemoclaw@v0.0.97
zc-edge    zeroclaw   pi4    anthropic        running      12h   -
maurice    hermes     lab2   openrouter       onboarding   1h    -

RUNTIME column (since v26.7.3). The RUNTIME column appears in both the default and -o wide views. For openclaw agents it shows nemoclaw@<version> — every openclaw now runs inside an NVIDIA NemoClaw sandbox. For other agent types it displays -.

chat​

Chat with an agent via the CLI.

clawctl agent chat <agent-name> [options]

Arguments:

  • agent-name - Name of the agent to chat with

Options:

  • --session <key> / -s - Gateway session key (default: main)
  • --timeout <seconds> - Response timeout in seconds (min: 1.0, default: 120.0)
  • --idle-timeout <seconds> - Idle timeout before disconnect (0 disables, default: 300.0)
  • --once <message> - Send one message, print the reply, and exit. Exit code 0 on success, non-zero on transport error.

Examples:

# Interactive chat session
clawctl agent chat opc-work

# Single-shot mode — send one message, get one reply, exit
clawctl agent chat opc-work --once "What is your status?"

# Chat with a specific session
clawctl agent chat opc-work --session direct:my-session

# Single-shot with custom timeout
clawctl agent chat opc-work --once "Reply pong" --timeout 30

Single-shot mode (--once):

The --once flag is designed for scripted callers (CI pipelines, monitoring scripts, automation). It sends a single message, prints the agent's reply to stdout, and exits. Exit code is 0 on success and non-zero on transport error so shell pipelines can gate on it. The --timeout and --idle-timeout values apply as usual.

# Scripted usage
REPLY=$(clawctl agent chat wise-hypatia --once "reply pong")
echo "$REPLY"
# → pong

Related:

doctor​

Diagnose an agent's render bundle (attachments, secrets, files). Local-only — never touches the host. Reports what clawctl would render right now from its own stores (providers, channels, integrations, secrets, hosts).

clawctl agent doctor <agent-name> [options]

Arguments:

  • agent-name - Name of the agent to diagnose

Options:

  • --output <fmt> / -o - Output format: table (default), json, yaml, wide, or name

Examples:

# Default table output
clawctl agent doctor maurice

# JSON output for diffing / scripting
clawctl agent doctor maurice -o json

What it reports:

  • Declared attachments — the providers, channels, integrations, and skills the agent record claims.
  • Resolved provider — name, type, endpoint, region, default model, and the presence status of each credential (present / missing).
  • Resolved channels and integrations — with per-secret presence.
  • Rendered files — every file the renderer would write to the host, with byte count, line count, and a sha256 prefix for deterministic comparison.

If build_render_inputs fails (a missing attach, an unresolved secret, a stale registry record), status is reported as broken and the exact lookup error is printed so the operator can fix the gap.

Exit codes:

  • 0 — Render bundle resolves cleanly
  • 1 — Render bundle is broken (missing attach, secret, or renderer)

Related:

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:

  1. Already at max — exits 0 with already at latest (<version>). No work is performed.
  2. 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.
  3. 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.
  4. Drift bypass — --skip-drift-check proceeds without comparing rendered vs. on-host files. The upgrade is force-installed in place.

Live version probing (openclaw, since v26.7.3). For openclaw agents, clawctl agent upgrade probes the on-host binary over SSH (openclaw --version) and compares that against the manifest's max supported version, instead of trusting the hosts.json snapshot. This closes the false-no-op trap in both directions: if the snapshot says 2026.6.1 but the binary is already 2026.6.8, the command reports "already at latest" rather than reinstalling; if the snapshot is ahead of reality, the upgrade still runs. Other agent types continue to compare against the snapshot. If the probe itself fails, the command errors out rather than guessing.

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​

CodeMeaning
0Success
1General error
2Invalid arguments
3Agent not found
4Host unreachable
5Onboarding incomplete
6Permission 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​

VariableDescriptionDefault
CLAWRIUM_CONFIGConfig directory path~/.config/clawrium
CLAWRIUM_LOG_LEVELLogging verbosityinfo
CLAWRIUM_TIMEOUTDefault operation timeout (seconds)30

See Also​