openclaw/docs/cli/agents.md

summary	read_when	title
CLI reference for `openclaw agents` (roles, teams, workspaces, routing, and identity)	You want multiple isolated agents (workspaces + routing + auth) You want to create an agent from a role or set up a coordinated team	Agents

openclaw agents

Manage isolated agents (workspaces + auth + routing). Running openclaw agents with no subcommand is equivalent to openclaw agents list.

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 add research --role researcher --non-interactive
openclaw agents team create --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

Options: --json, --bindings (include full routing rules, not only per-agent counts/summaries).

For an explicit multi-agent roster, the default badge and JSON isDefault field use agents.defaults.systemAgent.agentId. Doctor preserves the migrated default there across restarts. Without a designation, every entry reports isDefault: false; set one with openclaw config set agents.defaults.systemAgent.agentId <id>. The Control UI's Set Default action writes the same designation.

Provider-status labels include optional account display names beside account IDs. Routing rules continue to identify accounts by channel and account ID.

An agent whose database belongs to another agent appears as degraded, with the refusal reason and repair guidance. The Gateway can continue serving healthy agents when a secondary agent is refused. Follow Doctor's database recovery guidance, then restart the Gateway after repairing the files.

Provider rows summarize local account status for the displayed binding scopes. A wildcard includes each locally known account once; message routing still applies peer and account precedence. Stored bindings with an omitted or blank account id refer to the literal default account key, independently of a channel's preferred account for commands. Use --json --bindings to include provider rows in JSON.

Identity fields saved in config take precedence. Fields that are not configured fall back to IDENTITY.md in the agent's workspace. Unsupported avatar values and unreadable local images also fall back to the workspace avatar.

agents add [name]

Options: --role <role>, --workspace <dir>, --model <id>, --agent-dir <dir>, --bind <channel[:accountId]> (repeatable), --non-interactive, --json.

• The automation flags --workspace, --model, --agent-dir, --bind, and --non-interactive select the non-interactive path. Non-interactive mode requires an agent name and, unless --role is supplied, --workspace.
• --json alone keeps the guided wizard interactive. Prompts and status are written to stderr, and stdout contains one JSON summary after setup completes.
• Non-interactive --json reports normalized agent IDs in the summary without extra stdout status messages.
• main is an ordinary agent id. Recreating it after another agent owns the installation can require openclaw doctor --fix to repair legacy session or shared-auth ownership first.
• Interactive mode offers optional auth copying. When the fleet has no default agent, choose a source agent or Skip copying auth profiles (the default). Selecting a source still requires confirmation before copying. Only portable static credentials (api_key and static token profiles) are copied unless a credential opts out with copyToAgents: false; OAuth refresh-token profiles are not copied unless a provider opts in with copyToAgents: true. Without a copy, OAuth stays available through the shared auth base. If the source agent has its own local OAuth profile, sign in separately for the new agent.
• An agent id whose deletion has finished can be recreated with agents add. Creation claims the finished deletion record when it publishes the new agent, including when the wizard copies or configures auth. An id whose deletion cleanup is still pending is refused until that deletion is retried.

Role templates

--role works in interactive and non-interactive creation, including --json. Bundled roles are Claw sources: each role directory contains a CLAW.md manifest with identity and SOUL.md content, plus its operating program in workspace/AGENTS.md. Available roles:

Role	Title	Purpose
coordinator	Chief of staff	Coordinate specialists as your single point of contact.
researcher	Researcher	Gather evidence and return a cited research brief.
writer	Writer	Turn a brief and source material into a usable draft.
reviewer	Reviewer	Check artifacts against requirements and return actionable findings.

A role seeds AGENTS.md, SOUL.md, and a complete IDENTITY.md; USER.md still uses the standard template. Existing workspace files are preserved. The role's name, emoji, and theme are saved in agent config, and new role workspaces skip the identity ceremony: no BOOTSTRAP.md is created. The bundled roles leave skills unchanged. Role delegation settings are also applied. A standalone chief of staff targets the standard specialist ids; use the team command to create and wire all four agents. When creating an agent through Ask OpenClaw, you can give a display name separately from its id, such as “QA Writer” with id qa-writer. The approval includes both. An explicit display name replaces the role's default name while keeping its emoji, theme, and operating instructions. Unknown roles are rejected with the available role names. A workspace with an unfinished bootstrap cannot adopt a role. OpenClaw checks completion before adding role files; rejected adoption leaves workspace files and agent config unchanged. Complete its bootstrap or choose a new workspace.

With the experimental Claws surface enabled, the equivalent source path is openclaw claws add docs/reference/templates/roles/<role> from a source checkout. Follow the Claw preview and consent flow to add it. Use agents team create to wire the agents into a team.

agents team create

Options: --preset <name> (default and only bundled preset: team), --coordinator <id> (default: coordinator), --prefix <p>, --workspace-root <dir>, --non-interactive, --json.

Creates a chief of staff (coordinator) plus researcher, writer, and reviewer from the role templates. Each workspace lives at <workspace-root>/<agentId>; the default root is the installation's default workspace directory. --prefix editorial namespaces every id, producing editorial-coordinator, editorial-researcher, editorial-writer, and editorial-reviewer. It also prefixes a custom --coordinator id. If any resulting id exists, the command reports the conflicts and adds no agents.

Existing agents remain in place, including an implicit main on an already configured installation.

openclaw agents team create --prefix editorial --workspace-root ~/agents --non-interactive --json
openclaw agent --agent editorial-coordinator --message "Research this topic and draft a brief."

The coordinator's subagents.allowAgents names the three specialist ids and delegationMode is "prefer". Specialists receive subagents.allowAgents: [] and instructions to return results without further delegation. This does not change global delegation defaults or tool policy. See Team preset. Delegation remains team wiring in config; the role Claws will carry these settings once the separate Claw profile support lands.

The coordinator is an explicit chat target. If agents.defaults.systemAgent.agentId is unset, team creation sets it to the coordinator for ambient system work and default-compatible operations. An existing owner is preserved and reported. Channel bindings take precedence over this default. With --json, the summary includes coordinatorId, the created agents and their paths, ambientOwnerId, and a note when another ambient owner is retained.

agents bindings

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

agents bind

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

agents unbind

Options: --agent <id> (defaults to the current default agent), --bind <channel[:accountId]> (repeatable), --all, --json. Accepts either --all or one or more --bind values, not both.

agents set-identity

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

agents delete <id>

Options: --force, --json.

• The only configured agent cannot be deleted.
• Without --force, interactive confirmation is required (fails in a non-TTY session; re-run with --force).
• Workspace, agent state, and session transcript directories move to Trash, not hard-deleted. If Trash is unavailable, agent config deletion still succeeds and reports paths requiring manual cleanup; --json exposes path outcomes in removed and failed arrays.
• If session-store cleanup fails, the agent is removed from config but its files and pending cleanup are retained. Resolve the reported storage error, then retry the same deletion command; --json reports purgeFailed: true until the purge succeeds.
• On installations that have not migrated shared auth yet, the legacy owner cannot be deleted. Run openclaw doctor --fix; after relocation into shared state SQLite, main follows the same deletion rules as any other agent.
• An agent that owns a session database still used by another configured agent cannot be deleted, even when retaining files. Keep that owner configured; moving shared history to another owner requires a supported migration, which is not currently available.
• When the Gateway is reachable, deletion routes through the Gateway so config and session-store cleanup share the same writer as runtime traffic. If the configured local Gateway cannot be reached before connecting, the CLI falls back to the offline local path and removes the agent's scheduled jobs transactionally. If local Gateway credentials are unavailable before the CLI can test reachability, deletion still falls back locally but warns that cron cleanup was skipped because a live scheduler may own the store.
• If another agent's workspace is the same path, inside this workspace, or contains this workspace, the workspace is retained, and --json reports workspaceRetained, workspaceRetainedReason, and workspaceSharedWith.
• Cleanup also retains directories containing another agent's registered database, so deleting a parent directory cannot discard the survivor's history.
• Cleanup resolves symlink targets using their filesystem meaning, including .. segments, so a dangling workspace link cannot select an unrelated neighboring directory.

Automatic local fallback never applies to a remote Gateway or an OPENCLAW_GATEWAY_URL override, including loopback SSH tunnels. Connection or credential failures exit with an error and leave local config, workspace, and session state alone. Restore the Gateway connection and credentials, or run the command on the Gateway host.

Routing bindings

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

If you also want different visible skills per agent, configure agents.defaults.skills and agents.entries.*.skills in openclaw.json. See 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

You can also add bindings when creating an agent:

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

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

If you omit --agent for bind or unbind, OpenClaw targets the current default agent.

--bind format

Format	Meaning
--bind <channel>:*	Match all accounts on the channel.
--bind <channel>:<account>	Match one account.
--bind <channel>	Match the default account only, unless the CLI can safely resolve a plugin-specific account scope.

Binding scope behavior

• A stored binding without accountId matches the literal default account key only.
• accountId: "*" is 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. If you also want 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

Each agent workspace can include 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 resolve relative to the workspace root and cannot escape 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 selects the target agent. If --workspace matches more than one agent, the command fails and asks you to pass --agent.
• --workspace and --identity-file only select the agent or identity file. They do not change agents.entries.*.workspace. For --json, workspace is the resolved identity directory: the --workspace locator, the parent of --identity-file, or the agent's workspace when identity is read from there. It is null only when identity is supplied through flags with no identity directory. storedWorkspace reports the agent's persisted workspace.
• Relocate an existing agent with openclaw config set agents.entries.<id>.workspace <dir>, then follow the CLI restart hint and confirm with openclaw agents list.
• Local workspace-relative avatar image files are limited to 2 MB. HTTP(S) URLs and data: URIs are not checked against the local file-size limit.
• When no explicit identity fields are provided, 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

Relocate the stored workspace:

openclaw config set agents.entries.work.workspace ~/.openclaw/workspace-work
openclaw agents list

Config sample:

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

Related

• CLI reference
• Multi-agent routing
• Agent workspace
• Skills config: skill visibility configuration.