Openclaw Agents Commands Guide

Complete subcommand reference for openclaw agents, covering agent lifecycle, channel routing bindings, and identity configuration.

What is Openclaw Agents?

It’s the management surface for named agent configurations, isolated runtimes that each carry their own workspace, model settings, and channel routing rules.

Think of an agent as a persistent worker: you create it once with agents add, bind it to one or more chat channels so inbound traffic routes to it automatically, then optionally give it an identity (name, emoji, avatar) so users on those channels see something other than a blank sender. The openclaw agent dispatch command (separate doc) is how you talk to an agent; these commands are how you manage them.

Finding the Right Subcommand

If you’re setting up a new agent from scratch, start with agents add. If you already have agents and need to wire or rewire which channels they respond to, jump to agents bind / unbind. Use agents bindings to inspect what’s currently routed where before making changes, it’ll save you from accidental double-binds. The agents set-identity subcommand is optional cosmetic config, but becomes important when your agent is customer-facing.

Subcommand Overview

All subcommands follow the pattern openclaw agents <subcommand>. The table below maps subcommands to their function at a glance.

shell

openclaw agents list          # list configured agents
openclaw agents add           # create a new agent
openclaw agents delete        # remove an agent
openclaw agents bindings      # inspect routing bindings
openclaw agents bind          # add routing bindings
openclaw agents unbind        # remove routing bindings
openclaw agents set-identity  # configure agent name/emoji/avatar

Subcommand Reference

Openclaw Agents List

Lists all configured agents in your OpenClaw setup.

Options

–bindings | –json

–bindings appends associated routing bindings inline for each agent, saves a separate agents bindings call when you want a full picture at once. –json outputs machine-readable JSON, useful for piping into scripts.

Openclaw Agents Add [name]

Adds a new isolated agent. By default, runs an interactive guided wizard. If you want to bypass the wizard, you must pass the –workspace flag along with –non-interactive.

Options

–workspace <dir> | –model <id> | –agent-dir <dir> | –bind <channel[:accountId]> | –non-interactive | –json

--bind <channel[:accountId]> is repeatable, pass it multiple times in the same command to attach the new agent to several channels at creation time, saving a follow-up agents bind call.

Skipping the wizard requires both –workspace and –non-interactive together. Passing only one will still launch the wizard.

Openclaw Agents Delete <name>

Deletes the specified agent from your configuration. This is irreversible, bindings associated with the agent are removed along with it.

Openclaw Agents Bindings

Lists current routing bindings used to pin inbound channel traffic to specific agents.

Options

–agent <id> | –json

Use --agent <id> to scope the output to a single agent. Without it, all bindings across all agents are returned.

Openclaw Agents Bind

Adds routing bindings for an agent, controlling which inbound channel traffic it receives.

Options

–agent <id> | –bind <channel[:accountId]> | –json

Keep the momentum going with these: Openclaw Agent Command List and Openclaw Approvals Commands Guide.

Account ID scope rules:

• Omitting accountId (e.g. –bind telegram) matches the channel’s default account only.
• Using * as accountId (e.g. --bind telegram:*) creates a channel-wide fallback that catches all accounts on that channel.
• Upgrade behaviour: if a channel-only binding already exists and you later add an explicit account binding for the same channel, OpenClaw upgrades the existing binding in-place rather than creating a duplicate.

Openclaw Agents Unbind

Removes routing bindings for an agent.

Options

–agent <id> | –bind <channel[:accountId]> | –all

–all removes every binding for the specified agent in one shot. Use --bind <channel[:accountId]> (repeatable) for surgical removal of individual bindings.

Openclaw Agents Set-Identity

Sets or updates the agent’s identity fields, name, theme, emoji, and avatar, in the configuration. Pass values explicitly via flags, or load them automatically from an IDENTITY.md file located at the workspace root using –from-identity.

Options

–agent <id> | –name <name> | –emoji <emoji> | –avatar <path-or-url> | –workspace <dir> | –from-identity

When using –from-identity, OpenClaw reads the IDENTITY.md file at the workspace root and parses identity fields from it automatically. The –workspace flag tells it where to look. Explicit flags (–name, –emoji, etc.) override anything in the file when both are provided.

Examples

Six copy-paste patterns covering the most common agent management workflows.

01 Adding a new agent manually (non-interactive)

openclaw agents add work --workspace ~/openclaw/workspace-work

Passes –workspace to bypass the guided wizard. The agent name is work.

02 Binding an agent to specific accounts

openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a

Repeatable –bind flag, binds work to the ops Telegram account and the guild-a Discord account in one command.

03 Upgrading a binding (channel-only → account-specific)

# Existing channel-only binding:
openclaw agents bind --agent work --bind telegram

# Upgrade in-place to an explicit account (no duplicate created):
openclaw agents bind --agent work --bind telegram:ops

OpenClaw detects the existing telegram binding and upgrades it to telegram:ops in-place rather than creating a duplicate entry.

04 Removing all bindings for an agent

openclaw agents unbind --agent work --all

Clears every routing binding associated with work in one shot. The agent itself is preserved, only its bindings are removed.

05 Setting an agent’s identity explicitly

openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --avatar avatars/openclaw.png

All three identity fields set inline. The avatars/openclaw.png path is relative to the agent’s workspace root, or use an absolute URL.

06 Loading identity from IDENTITY.md

openclaw agents set-identity --workspace ~/openclaw/workspace --from-identity

Reads the IDENTITY.md file at ~/openclaw/workspace/IDENTITY.md and applies all identity fields found there automatically.

After any binding change, run openclaw agents list --bindings to verify the full routing state across all agents before testing live traffic.