openclaw agents CLI Reference: List, Add, Bind, and Manage Agents

openclaw agents

Agents are managed as isolated units, each combining its own workspace, authentication, and routing. Calling openclaw agents without any subcommand behaves the same as openclaw agents list.

Related material:

• Multi-agent routing
• Agent workspace
• Skills config: controls which skills are visible.

Examples

openclaw agents list
openclaw agents list --bindings
openclaw agents add work --workspace ~/.openclaw/workspace-work
openclaw agents add work --workspace ~/.openclaw/workspace-work --bind telegram:*
openclaw agents add ops --workspace ~/.openclaw/workspace-ops --bind telegram:ops --non-interactive
openclaw agents bindings
openclaw agents bind --agent work --bind telegram:ops
openclaw agents unbind --agent work --bind telegram:ops
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
openclaw agents set-identity --agent main --avatar avatars/openclaw.png
openclaw agents delete work

Command surface

agents list

Flags: --json, --bindings (adds complete routing rules, not just per-agent totals or summaries).

agents add [name]

Flags: --workspace <dir>, --model <id>, --agent-dir <dir>, --bind <channel[:accountId]> (can be repeated), --non-interactive, --json.

• The non-interactive path is chosen through the automation flags --workspace, --model, --agent-dir, --bind, and --non-interactive. For non-interactive operation, both an agent name and --workspace are mandatory.
• Using only --json keeps the guided wizard interactive. Prompts and status messages go to stderr, while stdout receives a single JSON summary once setup finishes.
• main is a standard agent identifier. If another agent already owns the installation, recreating it may call for openclaw doctor --fix to fix legacy session or shared-auth ownership beforehand.
• Interactive mode starts authentication by duplicating only portable static credentials (api_key and static token profiles), unless a credential excludes itself with copyToAgents: false; OAuth refresh-token profiles are duplicated only when a provider opts in via copyToAgents: true. If no copy happens, OAuth remains reachable through the shared auth base. When the configured default agent carries its own local OAuth profile, sign in separately for the new agent.

agents bindings

Flags: --agent <id>, --json.

agents bind

Flags: --agent <id> (falls back to the current default agent), --bind <channel[:accountId]> (repeatable), --json.

agents unbind

Flags: --agent <id> (falls back to the current default agent), --bind <channel[:accountId]> (repeatable), --all, --json. Takes either --all or one or more --bind values, but not both at once.

agents set-identity

Flags: --agent <id>, --workspace <dir>, --identity-file <path>, --from-identity, --name <name>, --theme <theme>, --emoji <emoji>, --avatar <value>, --json. Refer to Set identity below.

agents delete <id>

Flags: --force, --json.

• The sole configured agent is not eligible for deletion.
• In the absence of --force, you will be asked to confirm interactively (this fails when no TTY is present; retry with --force).
• Workspace, agent state, and session transcript folders are sent to Trash rather than permanently erased. When Trash cannot be used, agent config removal still succeeds and lists paths that need manual cleanup; --json surfaces path results through the removed and failed arrays.
• For setups that have not yet migrated shared authentication, the legacy owner stays undeletable. Execute openclaw doctor --fix; once moved into the shared state SQLite, main obeys the same removal rules as any other agent.
• With the Gateway reachable, deletion goes through the Gateway so that config and session-store cleanup share the same writer as live traffic. If the Gateway cannot be reached, the CLI takes the offline local route and transactionally removes the agent's scheduled jobs. Should Gateway credentials be missing before the CLI can check reachability, deletion still falls back locally, but it warns that cron cleanup was skipped because a live scheduler might own the store.
• When another agent's workspace equals this path, sits inside this workspace, or contains this workspace, the workspace is kept, and --json reports workspaceRetained, workspaceRetainedReason, and workspaceSharedWith.

Routing bindings

Use routing bindings to direct inbound channel traffic to a specific agent.

For per-agent visible skills that differ, set agents.defaults.skills and agents.entries.*.skills inside openclaw.json. Refer to Skills config and Configuration reference.

Show bindings:

openclaw agents bindings
openclaw agents bindings --agent work
openclaw agents bindings --json

Add bindings:

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

Bindings can also be added at agent creation time:

openclaw agents add work --workspace ~/.openclaw/workspace-work --bind telegram:* --bind discord:*

When accountId (--bind <channel>) is omitted, OpenClaw derives it from plugin setup hooks, forced account binding, or the account count configured for the channel.

If --agent is left out for bind or unbind, OpenClaw uses the current default agent.

--bind format

Binding scope behavior

• A stored binding lacking accountId matches only the channel's default account.
• accountId: "*" acts as the channel-wide fallback (all accounts) and is less specific than an explicit account binding.
• If the same agent already holds a matching channel binding without accountId, and you later bind with an explicit or resolved accountId, OpenClaw updates that existing binding in place rather than adding a duplicate.

Examples:

# match all accounts on the channel
openclaw agents bind --agent work --bind telegram:*

# match a specific account
openclaw agents bind --agent work --bind telegram:ops

# initial channel-only binding
openclaw agents bind --agent work --bind telegram

# later upgrade to account-scoped binding
openclaw agents bind --agent work --bind telegram:alerts

After that upgrade, routing for the binding is scoped to telegram:alerts. For default-account routing as well, add it explicitly (for instance --bind telegram:default).

Remove bindings:

openclaw agents unbind --agent work --bind telegram:ops
openclaw agents unbind --agent work --all

Identity files

Each agent workspace may contain an IDENTITY.md at its root:

• Example path: ~/.openclaw/workspace/IDENTITY.md
• set-identity --from-identity reads from the workspace root (or an explicit --identity-file).

Avatar paths resolve relative to the workspace root and cannot go beyond it, even through a symlink.

Set identity

set-identity writes fields into agents.entries.*.identity: name, theme, emoji, avatar (workspace-relative path, http(s) URL, or data URI).

• --agent or --workspace picks the target agent. If --workspace matches multiple agents, the command fails and requests --agent.
• Local workspace-relative avatar image files are capped at 2 MB. HTTP(S) URLs and data: URIs are not subject to the local file-size limit.
• With no explicit identity fields supplied, the command pulls identity data from IDENTITY.md.

Load from IDENTITY.md:

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

Override fields explicitly:

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

Config sample:

{
  agents: {
    entries: {
      main: {
        default: true,
        identity: {
          name: "OpenClaw",
          theme: "space lobster",
          emoji: "🦞",
          avatar: "avatars/openclaw.png",
        },
      },
    },
  },
}

Related

• Command line interface reference
• Directing traffic between multiple agents
• Where agents do their work