agents

`remoteclaw agents`

Manage isolated agents (workspaces + auth + routing).

Multi-agent routing: Multi-Agent Routing
Agent workspace: Agent workspace
Skill visibility config: Skills config

Examples

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

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.list[].skills in remoteclaw.json. See Skills config and Configuration Reference.

List bindings:

remoteclaw agents bindings
remoteclaw agents bindings --agent work
remoteclaw agents bindings --json

Add bindings:

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

If you omit accountId (--bind <channel>), RemoteClaw resolves it from channel defaults and plugin setup hooks when available.

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

Binding scope behavior

A binding without accountId matches the channel default account 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, RemoteClaw upgrades that existing binding in place instead of adding a duplicate.

Example:

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

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

After the upgrade, routing for that binding is scoped to telegram:ops. If you also want default-account routing, add it explicitly (for example --bind telegram:default).

Remove bindings:

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

unbind accepts either --all or one or more --bind values, not both.

Command surface

`agents`

Running remoteclaw agents with no subcommand is equivalent to remoteclaw agents list.

`agents list`

Options:

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

`agents add [name]`

Options:

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

Notes:

Passing any explicit add flags switches the command into the non-interactive path.
Non-interactive mode requires both an agent name and --workspace.
main is reserved and cannot be used as the new agent id.

`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

`agents delete <id>`

Options:

--force
--json

Notes:

main cannot be deleted.
Without --force, interactive confirmation is required.
Workspace, agent state, and session transcript directories are moved to Trash, not hard-deleted.

Identity files

Each agent workspace can include an IDENTITY.md at the workspace root:

Example path: ~/.remoteclaw/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.

Set identity

set-identity writes fields into agents.list[].identity:

name
theme
emoji
avatar (workspace-relative path, http(s) URL, or data URI)

Options:

--agent <id>
--workspace <dir>
--identity-file <path>
--from-identity
--name <name>
--theme <theme>
--emoji <emoji>
--avatar <value>
--json

Notes:

--agent or --workspace can be used to select the target agent.
If you rely on --workspace and multiple agents share that workspace, the command fails and asks you to pass --agent.
When no explicit identity fields are provided, the command reads identity data from IDENTITY.md.

Load from IDENTITY.md:

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

Override fields explicitly:

remoteclaw agents set-identity --agent main --name "RemoteClaw" --emoji "🦞" --avatar avatars/remoteclaw.png

Config sample:

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