Manage Agents with openclaw agents CLI Command

openclaw agents

Manage self-contained agents that combine workspaces, authentication, and routing. Running openclaw agents without a subcommand behaves the same as openclaw agents list.

Related:

• Multi-agent routing
• Agent workspace
• Skills config: configuration that controls skill visibility.

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 (shows complete routing rules, not just per-agent counts or summaries).

agents add [name]

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

• Supplying any explicit add flag forces the command into the non-interactive path.
• Non-interactive mode requires an agent name and --workspace.
• The identifier main is reserved and cannot serve as the new agent id.
• Interactive mode seeds authentication by copying only portable static credentials (api_key and static token profiles), unless a credential opts out with copyToAgents: false. OAuth refresh-token profiles are not copied unless a provider opts in with copyToAgents: true. When no copy occurs, OAuth remains available only through read-through inheritance from the real main agent store. If the configured default agent is not main, sign in separately for OAuth profiles on the new agent.

agents bindings

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

agents bind

Flags: --agent <id> (defaults to the current default agent), --bind <channel[:accountId]> (can be specified multiple times), --json.

agents unbind

Flags: --agent <id> (defaults to the current default agent), --bind <channel[:accountId]> (can be specified multiple times), --all, --json. Accepts either --all or one or more --bind values, but not both.

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.

• Deleting main is not permitted.
• Without --force, the operation demands interactive confirmation (it will fail in a non-TTY session; retry with --force).
• Workspace, agent state, and session transcript directories are sent to Trash rather than being permanently erased. If Trash is unavailable, agent config deletion still completes successfully and indicates which paths need manual removal.
• When the Gateway is reachable, deletion goes through the Gateway so that config and session-store cleanup use the same writer as runtime traffic. If the Gateway is unreachable, the CLI falls back to the offline local path.
• If another agent's workspace shares the same path, is located 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 particular agent.

If you also want each agent to expose different visible skills, set agents.defaults.skills and agents.entries.*.skills inside openclaw.json. Refer to Skills config and Configuration reference.

List 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 during agent creation:

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

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

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

--bind format

Binding scope behavior

• A stored binding that lacks accountId matches only the channel 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 has a matching channel binding without accountId, and you later bind with an explicit or resolved accountId, OpenClaw upgrades that existing binding in place instead of 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 the upgrade, routing for that binding is scoped to telegram:alerts. For default-account routing, add it explicitly (for example --bind telegram:default).

Remove bindings:

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

Identity files

Every agent workspace can contain an IDENTITY.md at the workspace root:

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

Avatar paths are resolved relative to the workspace root and cannot leave it, even via 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 more than one agent, the command fails and requires you to provide --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.
• When no explicit identity fields are supplied, the command reads 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: {
    list: [
      {
        id: "main",
        identity: {
          name: "OpenClaw",
          theme: "space lobster",
          emoji: "🦞",
          avatar: "avatars/openclaw.png",
        },
      },
    ],
  },
}

Related

• CLI reference
• Multi-agent routing
• Agent workspace