Manage OpenClaw Agents: Workspaces & Identities

Managing multiple AI agents can quickly become a headache when you are trying to keep your development work separate from your operations tasks. You need a way to handle different workspaces, authentication, and routing without everything turning into a tangled mess.

The openclaw agents command is your tool for managing these isolated environments. It helps you keep your contexts clean and ensures that the right messages always reach the right agent.

Examples

If you want to jump straight in, here are the most common ways to use the command:

openclaw agents list
openclaw agents list --bindings
openclaw agents add work --workspace ~/.openclaw/workspace-work
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

Routing bindings

You can use routing bindings to pin traffic from specific inbound channels to a specific agent. This is helpful when you want to keep your Telegram ops separate from your Discord dev chats.

If you need different visible skills for each agent, you should configure agents.defaults.skills and agents.list[].skills in your openclaw.json. You can find more details in the Skills config and the Configuration Reference.

To see your current bindings, use these commands:

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

To add a new binding:

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

If you leave out the accountId (just using --bind <channel>), OpenClaw will try to resolve it from your channel defaults or plugin setup hooks. If you don’t specify an --agent, the command will target your current default agent.

Binding scope behavior

• A binding without an accountId only matches the default account for that channel.
• Using accountId: "*" acts as a fallback for the entire channel and is less specific than a direct account binding.
• If an agent already has a channel binding without an accountId, and you later add one with a specific accountId, OpenClaw updates the existing binding instead of creating a duplicate.

Here is how an upgrade looks:

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

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

Once you upgrade, the routing is locked to telegram:ops. If you still want routing for the default account, you have to add it back explicitly, like --bind telegram:default.

To remove bindings:

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

Note that unbind lets you use either --all or specific --bind values, but you cannot use both at the same time.

Command surface

agents

If you run openclaw agents without any other words, it just runs openclaw agents list.

agents list

You have a few options here:

• --json: Get the output in JSON format.
• --bindings: This shows you the full routing rules instead of just the basic summaries.

agents add [name]

When creating a new agent, you can use these flags:

• --workspace <dir>
• --model <id>
• --agent-dir <dir>
• --bind <channel[:accountId]> (you can repeat this)
• --non-interactive
• --json

Keep in mind that using any of these flags will skip the interactive prompts. If you go the non-interactive route, you must provide both a name and a --workspace. Also, the name main is reserved, so you cannot use it for new agents.

agents bindings

• --agent <id>: Filter by a specific agent.
• --json: Get JSON output.

agents bind

• --agent <id>: Defaults to your current agent if you skip this.
• --bind <channel[:accountId]>: You can add multiple bindings at once.
• --json: Standard JSON output.

agents unbind

• --agent <id>: Defaults to your current agent.
• --bind <channel[:accountId]>: Specify what to remove.
• --all: Clear everything for that agent.
• --json: Standard JSON output.

agents delete <id>

• --force: Skip the confirmation prompt.
• --json: Standard JSON output.

You cannot delete the main agent. When you delete others, OpenClaw moves the workspace, state, and transcripts to the Trash rather than deleting them forever.

Identity files

You can give each agent a personality by placing an IDENTITY.md file at the root of its workspace.

• Example path: ~/.openclaw/workspace/IDENTITY.md
• The set-identity --from-identity command will look for this file automatically.

If you use avatars, the paths should be relative to that same workspace root.

Set identity

The set-identity command updates the agents.list[].identity section in your config. It handles:

• name
• theme
• emoji
• avatar (this can be a local path, a URL, or a data URI)

You can use these options:

• --agent <id> or --workspace <dir> to pick the target.
• --identity-file <path>
• --from-identity
• --name <name>, --theme <theme>, --emoji <emoji>, --avatar <value>
• --json

If multiple agents share the same workspace and you only use --workspace, the command will ask you to specify the --agent to avoid confusion.

To load everything from your markdown file:

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

Or you can override specific parts manually:

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

Your configuration will end up looking something like this:

{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "OpenClaw",
          theme: "space lobster",
          emoji: "🦞",
          avatar: "avatars/openclaw.png",
        },
      },
    ],
  },
}

Next Steps

• Learn more about Multi-Agent Routing
• Explore the Agent workspace setup
• Configure your Skills config

Need help getting your agents running? Check out the AI Setup Assistant.