openclaw agents

Gerencie agentes isolados (espaços de trabalho + autenticação + roteamento). Executar openclaw agents sem um subcomando equivale a openclaw agents list.

Relacionado:

• Roteamento multiagente
• Espaço de trabalho do agente
• Configuração de Skills: configuração da visibilidade de Skills.

Exemplos

openclaw agents listopenclaw agents list --bindingsopenclaw agents add work --workspace ~/.openclaw/workspace-workopenclaw agents add work --workspace ~/.openclaw/workspace-work --bind telegram:*openclaw agents add ops --workspace ~/.openclaw/workspace-ops --bind telegram:ops --non-interactiveopenclaw agents bindingsopenclaw agents bind --agent work --bind telegram:opsopenclaw agents unbind --agent work --bind telegram:opsopenclaw agents set-identity --workspace ~/.openclaw/workspace --from-identityopenclaw agents set-identity --agent main --avatar avatars/openclaw.pngopenclaw agents delete work

Superfície de comandos

agents list

Opções: --json, --bindings (inclui as regras de roteamento completas, não apenas contagens/resumos por agente).

agents add [name]

Opções: --workspace <dir>, --model <id>, --agent-dir <dir>, --bind <channel[:accountId]> (repetível), --non-interactive, --json.

• Passar qualquer opção explícita de adição faz o comando usar o fluxo não interativo.
• O modo não interativo exige o nome do agente e --workspace.
• main é reservado e não pode ser usado como o ID do novo agente.
• O modo interativo inicializa a autenticação copiando apenas credenciais estáticas portáteis (perfis api_key e token estático), a menos que uma credencial desative essa cópia com copyToAgents: false; perfis OAuth com token de atualização não são copiados, a menos que um provedor habilite a cópia com copyToAgents: true. Sem uma cópia, o OAuth permanece disponível apenas por herança com leitura indireta do armazenamento real do agente main. Se o agente padrão configurado não for main, faça login separadamente nos perfis OAuth do novo agente.

agents bindings

Opções: --agent <id>, --json.

agents bind

Opções: --agent <id> (o padrão é o agente padrão atual), --bind <channel[:accountId]> (repetível), --json.

agents unbind

Opções: --agent <id> (o padrão é o agente padrão atual), --bind <channel[:accountId]> (repetível), --all, --json. Aceita --all ou um ou mais valores de --bind, mas não ambos.

agents set-identity

Opções: --agent <id>, --workspace <dir>, --identity-file <path>, --from-identity, --name <name>, --theme <theme>, --emoji <emoji>, --avatar <value>, --json. Consulte Definir identidade abaixo.

agents delete <id>

Opções: --force, --json.

• main não pode ser excluído.
• Sem --force, é necessária uma confirmação interativa (falha em uma sessão sem TTY; execute novamente com --force).
• Os diretórios do espaço de trabalho, do estado do agente e das transcrições de sessão são movidos para a Lixeira, não excluídos permanentemente.
• Quando o Gateway está acessível, a exclusão é roteada pelo Gateway para que a limpeza da configuração e do armazenamento de sessões use o mesmo gravador que o tráfego de execução. Se o Gateway estiver inacessível, a CLI recorre ao fluxo local offline.
• Se o espaço de trabalho de outro agente for o mesmo caminho, estiver dentro deste espaço de trabalho ou contiver este espaço de trabalho, o espaço de trabalho será mantido, e --json informará workspaceRetained, workspaceRetainedReason e workspaceSharedWith.

Vínculos de roteamento

Use vínculos de roteamento para direcionar o tráfego de entrada de um canal a um agente específico.

Se você também quiser Skills visíveis diferentes para cada agente, configure agents.defaults.skills e agents.list[].skills em openclaw.json. Consulte Configuração de Skills e Referência de configuração.

Liste os vínculos:

openclaw agents bindingsopenclaw agents bindings --agent workopenclaw agents bindings --json

Adicione vínculos:

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

Você também pode adicionar vínculos ao criar um agente:

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

Se você omitir accountId (--bind <channel>), o OpenClaw o determina com base nos hooks de configuração do plugin, no vínculo obrigatório de conta ou na quantidade de contas configuradas do canal.

Se você omitir --agent em bind ou unbind, o OpenClaw usa o agente padrão atual como destino.

Formato de --bind

Comportamento do escopo dos vínculos

• Um vínculo armazenado sem accountId corresponde apenas à conta padrão do canal.
• accountId: "*" é a alternativa para todo o canal (todas as contas) e é menos específica que um vínculo explícito de conta.
• Se o mesmo agente já tiver um vínculo de canal correspondente sem accountId e, posteriormente, você criar um vínculo com um accountId explícito ou determinado, o OpenClaw atualizará esse vínculo existente no local em vez de adicionar uma duplicata.

Exemplos:

# match all accounts on the channelopenclaw agents bind --agent work --bind telegram:* # match a specific accountopenclaw agents bind --agent work --bind telegram:ops # initial channel-only bindingopenclaw agents bind --agent work --bind telegram # later upgrade to account-scoped bindingopenclaw agents bind --agent work --bind telegram:alerts

Após a atualização, o roteamento desse vínculo fica restrito a telegram:alerts. Se você também quiser roteamento para a conta padrão, adicione-o explicitamente (por exemplo, --bind telegram:default).

Remova vínculos:

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

Arquivos de identidade

Cada espaço de trabalho de agente pode incluir um arquivo IDENTITY.md na raiz do espaço de trabalho:

• Exemplo de caminho: ~/.openclaw/workspace/IDENTITY.md
• set-identity --from-identity lê a partir da raiz do espaço de trabalho (ou de um --identity-file explícito).

Os caminhos de avatar são resolvidos em relação à raiz do espaço de trabalho e não podem sair dela, nem mesmo por meio de um link simbólico.

Definir identidade

set-identity grava campos em agents.list[].identity: name, theme, emoji, avatar (caminho relativo ao espaço de trabalho, URL http(s) ou URI de dados).

• --agent ou --workspace seleciona o agente de destino. Se --workspace corresponder a mais de um agente, o comando falhará e solicitará que você passe --agent.
• Arquivos locais de imagem de avatar com caminho relativo ao espaço de trabalho são limitados a 2 MB. URLs HTTP(S) e URIs data: não são verificadas em relação ao limite de tamanho de arquivo local.
• Quando nenhum campo de identidade explícito é fornecido, o comando lê os dados de identidade de IDENTITY.md.

Carregue a partir de IDENTITY.md:

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

Substitua campos explicitamente:

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

Exemplo de configuração:

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

Relacionado

• Referência da CLI
• Roteamento multiagente
• Espaço de trabalho do agente