Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Execute vários agentes isolados — cada um com seu próprio workspace, diretório de estado (agentDir) e histórico de sessão — além de várias contas de canal (por exemplo, dois WhatsApps) em um único Gateway em execução. Mensagens de entrada são roteadas para o agente correto por meio de vínculos. Um agente aqui é o escopo completo por persona: arquivos do workspace, perfis de autenticação, registro de modelos e armazenamento de sessões. agentDir é o diretório de estado em disco que contém esta configuração por agente em ~/.openclaw/agents/<agentId>/. Um vínculo mapeia uma conta de canal (por exemplo, um workspace do Slack ou um número do WhatsApp) para um desses agentes.

​
O que é “um agente”?

Um agente é um cérebro totalmente escopado com seu próprio:
  • Workspace (arquivos, AGENTS.md/SOUL.md/USER.md, notas locais, regras de persona).
  • Diretório de estado (agentDir) para perfis de autenticação, registro de modelos e configuração por agente.
  • Armazenamento de sessões (histórico de chat + estado de roteamento) em ~/.openclaw/agents/<agentId>/sessions.
Perfis de autenticação são por agente. Cada agente lê de seu próprio: 
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
sessions_history também é o caminho mais seguro para recordação entre sessões aqui: ele retorna uma visão limitada e sanitizada, não um despejo bruto de transcrição. A recordação do assistente remove tags de pensamento, estruturas <relevant-memories>, payloads XML de chamadas de ferramenta em texto simples (incluindo <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> e blocos truncados de chamadas de ferramenta), estruturas rebaixadas de chamadas de ferramenta, tokens vazados de controle de modelo ASCII/de largura total e XML malformado de chamadas de ferramenta MiniMax antes da redação/truncamento.
Nunca reutilize agentDir entre agentes (isso causa colisões de autenticação/sessão). Agentes podem ler os perfis de autenticação do agente padrão/principal quando não têm um perfil local, mas o OpenClaw não clona tokens de atualização OAuth para o armazenamento do agente secundário. Se você quiser uma conta OAuth independente, faça login a partir desse agente; se copiar credenciais manualmente, copie apenas perfis portáteis estáticos api_key ou token.
Skills são carregadas de cada workspace de agente mais raízes compartilhadas, como ~/.openclaw/skills, e então filtradas pela lista de permissão de Skills efetiva do agente quando configurada. Use agents.defaults.skills para uma linha de base compartilhada e agents.list[].skills para substituição por agente. Veja Skills: por agente vs compartilhadas e Skills: listas de permissão de Skills do agente. O Gateway pode hospedar um agente (padrão) ou muitos agentes lado a lado.
Observação sobre workspace: o workspace de cada agente é o cwd padrão, não uma sandbox rígida. Caminhos relativos são resolvidos dentro do workspace, mas caminhos absolutos podem alcançar outros locais do host, a menos que o isolamento por sandbox esteja ativado. Veja Isolamento por sandbox.

​
Caminhos (mapa rápido)

  • Configuração: ~/.openclaw/openclaw.json (ou OPENCLAW_CONFIG_PATH)
  • Diretório de estado: ~/.openclaw (ou OPENCLAW_STATE_DIR)
  • Workspace: ~/.openclaw/workspace (ou ~/.openclaw/workspace-<agentId>)
  • Diretório do agente: ~/.openclaw/agents/<agentId>/agent (ou agents.list[].agentDir)
  • Sessões: ~/.openclaw/agents/<agentId>/sessions

​
Modo de agente único (padrão)

Se você não fizer nada, o OpenClaw executa um único agente:
  • agentId usa main como padrão.
  • Sessões são indexadas como agent:main:<mainKey>.
  • O workspace usa ~/.openclaw/workspace como padrão (ou ~/.openclaw/workspace-<profile> quando OPENCLAW_PROFILE está definido).
  • O estado usa ~/.openclaw/agents/main/agent como padrão.

​
Assistente de agente

Use o assistente de agentes para adicionar um novo agente isolado: 
openclaw agents add work
Depois adicione bindings (ou deixe o assistente fazer isso) para rotear mensagens de entrada. Verifique com: 
openclaw agents list --bindings

​
Início rápido

1

Crie cada workspace de agente

Use o assistente ou crie workspaces manualmente:
openclaw agents add coding
openclaw agents add social
Cada agente recebe seu próprio workspace com SOUL.md, AGENTS.md e USER.md opcional, além de um agentDir dedicado e armazenamento de sessões em ~/.openclaw/agents/<agentId>.
2

Crie contas de canal

Crie uma conta por agente nos seus canais preferidos:
  • Discord: um bot por agente, habilite Message Content Intent, copie cada token.
  • Telegram: um bot por agente via BotFather, copie cada token.
  • WhatsApp: vincule cada número de telefone por conta.
openclaw channels login --channel whatsapp --account work
Veja os guias de canais: Discord, Telegram, WhatsApp.
3

Adicione agentes, contas e vínculos

Adicione agentes em agents.list, contas de canal em channels.<channel>.accounts e conecte-os com bindings (exemplos abaixo).
4

Reinicie e verifique

openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe

​
Vários agentes = várias pessoas, várias personalidades

Com vários agentes, cada agentId se torna uma persona totalmente isolada:
  • Números de telefone/contas diferentes (por accountId de canal).
  • Personalidades diferentes (arquivos de workspace por agente, como AGENTS.md e SOUL.md).
  • Autenticação + sessões separadas (sem comunicação cruzada, a menos que explicitamente ativada).
Isso permite que várias pessoas compartilhem um servidor Gateway mantendo seus “cérebros” de IA e dados isolados.

​
Busca de memória QMD entre agentes

Se um agente deve pesquisar transcrições de sessão QMD de outro agente, adicione coleções extras em agents.list[].memorySearch.qmd.extraCollections. Use agents.defaults.memorySearch.qmd.extraCollections somente quando todos os agentes devem herdar as mesmas coleções compartilhadas de transcrições. 
{
  agents: {
    defaults: {
      workspace: "~/workspaces/main",
      memorySearch: {
        qmd: {
          extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],
        },
      },
    },
    list: [
      {
        id: "main",
        workspace: "~/workspaces/main",
        memorySearch: {
          qmd: {
            extraCollections: [{ path: "notes" }], // resolves inside workspace -> collection named "notes-main"
          },
        },
      },
      { id: "family", workspace: "~/workspaces/family" },
    ],
  },
  memory: {
    backend: "qmd",
    qmd: { includeDefaultMemory: false },
  },
}
O caminho da coleção extra pode ser compartilhado entre agentes, mas o nome da coleção permanece explícito quando o caminho está fora do workspace do agente. Caminhos dentro do workspace permanecem escopados ao agente, para que cada agente mantenha seu próprio conjunto de busca de transcrições.

​
Um número do WhatsApp, várias pessoas (divisão de DMs)

Você pode rotear DMs diferentes do WhatsApp para agentes diferentes permanecendo em uma conta do WhatsApp. Corresponda pelo remetente E.164 (como +15551234567) com peer.kind: "direct". As respostas ainda vêm do mesmo número do WhatsApp (sem identidade de remetente por agente).
Chats diretos são colapsados para a chave de sessão principal do agente, então o isolamento real exige um agente por pessoa.
Exemplo: 
{
  agents: {
    list: [
      { id: "alex", workspace: "~/.openclaw/workspace-alex" },
      { id: "mia", workspace: "~/.openclaw/workspace-mia" },
    ],
  },
  bindings: [
    {
      agentId: "alex",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } },
    },
    {
      agentId: "mia",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230002" } },
    },
  ],
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551230001", "+15551230002"],
    },
  },
}
Observações:
  • O controle de acesso de DM é global por conta do WhatsApp (pareamento/lista de permissão), não por agente.
  • Para grupos compartilhados, vincule o grupo a um agente ou use Grupos de transmissão.

​
Regras de roteamento (como mensagens escolhem um agente)

Vínculos são determinísticos e o mais específico vence:
1

correspondência de peer

ID exato de DM/grupo/canal.
2

correspondência de parentPeer

Herança de thread.
3

guildId + funções

Roteamento por função do Discord.
4

guildId

Discord.
5

teamId

Slack.
6

correspondência de accountId para um canal

Fallback por conta.
7

Correspondência no nível do canal

accountId: "*".
8

Agente padrão

Fallback para agents.list[].default, caso contrário a primeira entrada da lista, padrão: main.
  • Se vários vínculos corresponderem no mesmo nível, o primeiro na ordem da configuração vence.
  • Se um vínculo definir vários campos de correspondência (por exemplo peer + guildId), todos os campos especificados são obrigatórios (semântica AND).
  • Um vínculo que omite accountId corresponde somente à conta padrão.
  • Use accountId: "*" para um fallback em todo o canal entre todas as contas.
  • Se depois você adicionar o mesmo vínculo para o mesmo agente com um ID de conta explícito, o OpenClaw atualiza o vínculo existente somente de canal para escopado à conta, em vez de duplicá-lo.

​
Várias contas / números de telefone

Canais que oferecem suporte a várias contas (por exemplo, WhatsApp) usam accountId para identificar cada login. Cada accountId pode ser roteado para um agente diferente, então um servidor pode hospedar vários números de telefone sem misturar sessões. Se você quiser uma conta padrão em todo o canal quando accountId for omitido, defina channels.<channel>.defaultAccount (opcional). Quando não definido, o OpenClaw usa default como fallback se estiver presente; caso contrário, usa o primeiro ID de conta configurado (ordenado). Canais comuns que oferecem suporte a este padrão incluem:
  • whatsapp, telegram, discord, slack, signal, imessage
  • irc, line, googlechat, mattermost, matrix, nextcloud-talk
  • zalo, zalouser, nostr, feishu

​
Conceitos

  • agentId: um “cérebro” (workspace, autenticação por agente, armazenamento de sessões por agente).
  • accountId: uma instância de conta de canal (por exemplo, conta do WhatsApp "personal" vs "biz").
  • binding: roteia mensagens de entrada para um agentId por (channel, accountId, peer) e, opcionalmente, IDs de guild/team.
  • Chats diretos colapsam para agent:<agentId>:<mainKey> (“main” por agente; session.mainKey).

​
Exemplos de plataforma

Cada conta de bot do Discord mapeia para um accountId único. Vincule cada conta a um agente e mantenha listas de permissão por bot.
{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "coding", workspace: "~/.openclaw/workspace-coding" },
    ],
  },
  bindings: [
    { agentId: "main", match: { channel: "discord", accountId: "default" } },
    { agentId: "coding", match: { channel: "discord", accountId: "coding" } },
  ],
  channels: {
    discord: {
      groupPolicy: "allowlist",
      accounts: {
        default: {
          token: "DISCORD_BOT_TOKEN_MAIN",
          guilds: {
            "123456789012345678": {
              channels: {
                "222222222222222222": { allow: true, requireMention: false },
              },
            },
          },
        },
        coding: {
          token: "DISCORD_BOT_TOKEN_CODING",
          guilds: {
            "123456789012345678": {
              channels: {
                "333333333333333333": { allow: true, requireMention: false },
              },
            },
          },
        },
      },
    },
  },
}
  • Convide cada bot para a guild e habilite Message Content Intent.
  • Os tokens ficam em channels.discord.accounts.<id>.token (a conta padrão pode usar DISCORD_BOT_TOKEN).
{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "alerts", workspace: "~/.openclaw/workspace-alerts" },
    ],
  },
  bindings: [
    { agentId: "main", match: { channel: "telegram", accountId: "default" } },
    { agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } },
  ],
  channels: {
    telegram: {
      accounts: {
        default: {
          botToken: "123456:ABC...",
          dmPolicy: "pairing",
        },
        alerts: {
          botToken: "987654:XYZ...",
          dmPolicy: "allowlist",
          allowFrom: ["tg:123456789"],
        },
      },
    },
  },
}
  • Crie um bot por agente com o BotFather e copie cada token.
  • Os tokens ficam em channels.telegram.accounts.<id>.botToken (a conta padrão pode usar TELEGRAM_BOT_TOKEN).
Vincule cada conta antes de iniciar o Gateway:
openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account biz
~/.openclaw/openclaw.json (JSON5):
{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        name: "Home",
        workspace: "~/.openclaw/workspace-home",
        agentDir: "~/.openclaw/agents/home/agent",
      },
      {
        id: "work",
        name: "Work",
        workspace: "~/.openclaw/workspace-work",
        agentDir: "~/.openclaw/agents/work/agent",
      },
    ],
  },

  // Deterministic routing: first match wins (most-specific first).
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },

    // Optional per-peer override (example: send a specific group to work agent).
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "1203630...@g.us" },
      },
    },
  ],

  // Off by default: agent-to-agent messaging must be explicitly enabled + allowlisted.
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },

  channels: {
    whatsapp: {
      accounts: {
        personal: {
          // Optional override. Default: ~/.openclaw/credentials/whatsapp/personal
          // authDir: "~/.openclaw/credentials/whatsapp/personal",
        },
        biz: {
          // Optional override. Default: ~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

​
Padrões comuns

Divida por canal: roteie o WhatsApp para um agente rápido do dia a dia e o Telegram para um agente Opus.
{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-6",
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/.openclaw/workspace-opus",
        model: "anthropic/claude-opus-4-6",
      },
    ],
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } },
  ],
}
Observações:
  • Se você tiver várias contas para um canal, adicione accountId ao vínculo (por exemplo, { channel: "whatsapp", accountId: "personal" }).
  • Para rotear uma única DM/grupo para o Opus enquanto mantém o restante no chat, adicione um vínculo match.peer para esse par; correspondências de pares sempre vencem regras de canal inteiro.

​
Configuração de sandbox e ferramentas por agente

Cada agente pode ter seu próprio sandbox e restrições de ferramentas: 
{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off",  // No sandbox for personal agent
        },
        // No tool restrictions - all tools available
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",     // Always sandboxed
          scope: "agent",  // One container per agent
          docker: {
            // Optional one-time setup after container creation
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"],                    // Only read tool
          deny: ["exec", "write", "edit", "apply_patch"],    // Deny others
        },
      },
    ],
  },
}
setupCommand fica em sandbox.docker e é executado uma vez na criação do contêiner. Substituições sandbox.docker.* por agente são ignoradas quando o escopo resolvido é "shared".
Benefícios:
  • Isolamento de segurança: restrinja ferramentas para agentes não confiáveis.
  • Controle de recursos: coloque agentes específicos em sandbox enquanto mantém outros no host.
  • Políticas flexíveis: permissões diferentes por agente.
tools.elevated é global e baseado no remetente; ele não é configurável por agente. Se você precisar de limites por agente, use agents.list[].tools para negar exec. Para direcionamento em grupos, use agents.list[].groupChat.mentionPatterns para que @menções sejam mapeadas claramente para o agente pretendido.
Consulte Sandbox e ferramentas multiagente para exemplos detalhados.

​
Relacionados

  • Agentes ACP — execução de harnesses de codificação externos
  • Roteamento de canais — como as mensagens são roteadas para agentes
  • Presença — presença e disponibilidade do agente
  • Sessão — isolamento e roteamento de sessões
  • Subagentes — criação de execuções de agente em segundo plano