​

Referência de configuração

​

Canais

​

Acesso a DM e grupos

​

Substituições de modelo por canal

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

​

Padrões de canal e heartbeat

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy: política de grupo de fallback quando groupPolicy no nível do provedor não está definido.
• channels.defaults.contextVisibility: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: all (padrão, inclui todo o contexto citado/thread/histórico), allowlist (inclui apenas contexto de remetentes na allowlist), allowlist_quote (igual a allowlist, mas mantém contexto explícito de citação/resposta). Substituição por canal: channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk: inclui status íntegros de canal na saída do heartbeat.
• channels.defaults.heartbeat.showAlerts: inclui status degradados/com erro na saída do heartbeat.
• channels.defaults.heartbeat.useIndicator: renderiza saída de heartbeat compacta em estilo indicador.

​

WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // tique azul (false em modo de chat consigo mesmo)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

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

​

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (padrão: off; habilite explicitamente para evitar limites de taxa de pré-visualização/edição)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Token do bot: channels.telegram.botToken ou channels.telegram.tokenFile (somente arquivo regular; symlinks são rejeitados), com TELEGRAM_BOT_TOKEN como fallback para a conta padrão.
• channels.telegram.defaultAccount opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.
• Em configurações com múltiplas contas (2+ ids de conta), defina um padrão explícito (channels.telegram.defaultAccount ou channels.telegram.accounts.default) para evitar roteamento por fallback; openclaw doctor avisa quando isso está ausente ou inválido.
• configWrites: false bloqueia gravações de configuração iniciadas pelo Telegram (migrações de ID de supergrupo, /config set|unset).
• Entradas bindings[] de nível superior com type: "acp" configuram bindings ACP persistentes para tópicos de fórum (use chatId:topic:topicId canônico em match.peer.id). A semântica dos campos é compartilhada em ACP Agents.
• Pré-visualizações de streaming no Telegram usam sendMessage + editMessageText (funciona em chats diretos e em grupo).
• Política de repetição: consulte Retry policy.

​

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress (progress mapeia para partial no Discord)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in para sessions_spawn({ thread: true })
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• Token: channels.discord.token, com DISCORD_BOT_TOKEN como fallback para a conta padrão.
• Chamadas diretas de saída que fornecem um token explícito do Discord usam esse token para a chamada; configurações de repetição/política da conta continuam vindo da conta selecionada no snapshot ativo de runtime.
• channels.discord.defaultAccount opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.
• Use user:<id> (DM) ou channel:<id> (canal de guild) para destinos de entrega; IDs numéricos simples são rejeitados.
• Slugs de guild ficam em minúsculas com espaços substituídos por -; chaves de canal usam o nome em slug (sem #). Prefira IDs de guild.
• Mensagens criadas por bot são ignoradas por padrão. allowBots: true as habilita; use allowBots: "mentions" para aceitar apenas mensagens de bot que mencionem o bot (mensagens próprias continuam filtradas).
• channels.discord.guilds.<id>.ignoreOtherMentions (e substituições de canal) descarta mensagens que mencionam outro usuário ou role, mas não o bot (excluindo @everyone/@here).
• maxLinesPerMessage (padrão 17) divide mensagens altas mesmo quando abaixo de 2000 caracteres.
• channels.discord.threadBindings controla o roteamento vinculado a threads do Discord:
  • enabled: substituição do Discord para recursos de sessão vinculados a thread (/focus, /unfocus, /agents, /session idle, /session max-age e entrega/roteamento vinculados)
  • idleHours: substituição do Discord para desfoco automático por inatividade em horas (0 desabilita)
  • maxAgeHours: substituição do Discord para idade máxima rígida em horas (0 desabilita)
  • spawnSubagentSessions: chave opt-in para criação/binding automáticos de thread por sessions_spawn({ thread: true })
• Entradas bindings[] de nível superior com type: "acp" configuram bindings ACP persistentes para canais e threads (use o id de canal/thread em match.peer.id). A semântica dos campos é compartilhada em ACP Agents.
• channels.discord.ui.components.accentColor define a cor de destaque para contêineres Discord components v2.
• channels.discord.voice habilita conversas em canais de voz do Discord e substituições opcionais de auto-join + TTS.
• channels.discord.voice.daveEncryption e channels.discord.voice.decryptionFailureTolerance são repassados para opções DAVE de @discordjs/voice (padrão true e 24).
• O OpenClaw também tenta recuperação de recepção de voz saindo/reentrando em uma sessão de voz após falhas repetidas de descriptografia.
• channels.discord.streaming é a chave canônica do modo de streaming. Os valores legados streamMode e booleanos streaming são migrados automaticamente.
• channels.discord.autoPresence mapeia a disponibilidade em runtime para presença do bot (íntegro => online, degradado => idle, exausto => dnd) e permite substituições opcionais de texto de status.
• channels.discord.dangerouslyAllowNameMatching reabilita correspondência mutável de nome/tag (modo de compatibilidade break-glass).
• channels.discord.execApprovals: entrega nativa de aprovações de exec no Discord e autorização de aprovadores.
  • enabled: true, false ou "auto" (padrão). No modo auto, aprovações de exec são ativadas quando aprovadores podem ser resolvidos a partir de approvers ou commands.ownerAllowFrom.
  • approvers: IDs de usuário do Discord autorizados a aprovar solicitações de exec. Usa commands.ownerAllowFrom como fallback quando omitido.
  • agentFilter: allowlist opcional de ID de agente. Omita para encaminhar aprovações para todos os agentes.
  • sessionFilter: padrões opcionais de chave de sessão (substring ou regex).
  • target: onde enviar prompts de aprovação. "dm" (padrão) envia para DMs do aprovador, "channel" envia para o canal de origem, "both" envia para ambos. Quando o alvo inclui "channel", os botões só podem ser usados por aprovadores resolvidos.
  • cleanupAfterResolve: quando true, exclui DMs de aprovação após aprovação, negação ou timeout.

​

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• JSON da conta de serviço: inline (serviceAccount) ou baseado em arquivo (serviceAccountFile).
• SecretRef de conta de serviço também é compatível (serviceAccountRef).
• Fallbacks por env: GOOGLE_CHAT_SERVICE_ACCOUNT ou GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Use spaces/<spaceId> ou users/<userId> para destinos de entrega.
• channels.googlechat.dangerouslyAllowNameMatching reabilita correspondência mutável de principal de e-mail (modo de compatibilidade break-glass).

​

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: "partial", // off | partial | block | progress (modo de pré-visualização)
      nativeStreaming: true, // usa API nativa de streaming do Slack quando streaming=partial
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• Socket mode requer botToken e appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN para fallback por env da conta padrão).
• HTTP mode requer botToken mais signingSecret (na raiz ou por conta).
• botToken, appToken, signingSecret e userToken aceitam strings em texto simples ou objetos SecretRef.
• Snapshots de conta do Slack expõem campos por credencial de origem/status, como botTokenSource, botTokenStatus, appTokenStatus e, em HTTP mode, signingSecretStatus. configured_unavailable significa que a conta está configurada por SecretRef, mas o caminho atual de comando/runtime não pôde resolver o valor do segredo.
• configWrites: false bloqueia gravações de configuração iniciadas pelo Slack.
• channels.slack.defaultAccount opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.
• channels.slack.streaming é a chave canônica de modo de streaming. Os valores legados streamMode e booleanos streaming são migrados automaticamente.
• Use user:<id> (DM) ou channel:<id> para destinos de entrega.

• typingReaction adiciona uma reação temporária à mensagem recebida do Slack enquanto uma resposta está em andamento e a remove na conclusão. Use um shortcode de emoji do Slack como "hourglass_flowing_sand".
• channels.slack.execApprovals: entrega nativa de aprovações de exec no Slack e autorização de aprovadores. Mesmo schema do Discord: enabled (true/false/"auto"), approvers (IDs de usuário do Slack), agentFilter, sessionFilter e target ("dm", "channel" ou "both").

​

Mattermost

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      commands: {
        native: true, // opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // URL explícita opcional para implantações com proxy reverso/públicas
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

• commands.callbackPath deve ser um caminho (por exemplo /api/channels/mattermost/command), não uma URL completa.
• commands.callbackUrl deve resolver para o endpoint do gateway do OpenClaw e ser acessível pelo servidor Mattermost.
• Callbacks nativos de slash são autenticados com os tokens por comando retornados pelo Mattermost durante o registro do slash command. Se o registro falhar ou nenhum comando for ativado, o OpenClaw rejeitará callbacks com Unauthorized: invalid command token.
• Para hosts privados/tailnet/internos de callback, o Mattermost pode exigir que ServiceSettings.AllowedUntrustedInternalConnections inclua o host/domínio do callback. Use valores de host/domínio, não URLs completas.
• channels.mattermost.configWrites: permite ou nega gravações de configuração iniciadas pelo Mattermost.
• channels.mattermost.requireMention: exige @mention antes de responder em canais.
• channels.mattermost.groups.<channelId>.requireMention: substituição de controle por menção por canal ("*" para padrão).
• channels.mattermost.defaultAccount opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.

​

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // binding opcional de conta
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

• channels.signal.account: fixa a inicialização do canal em uma identidade específica de conta Signal.
• channels.signal.configWrites: permite ou nega gravações de configuração iniciadas pelo Signal.
• channels.signal.defaultAccount opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.

​

BlueBubbles

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, controles de grupo e ações avançadas:
      // consulte /channels/bluebubbles
    },
  },
}

• Caminhos de chave principais cobertos aqui: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• channels.bluebubbles.defaultAccount opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.
• Entradas bindings[] de nível superior com type: "acp" podem vincular conversas do BlueBubbles a sessões ACP persistentes. Use um handle BlueBubbles ou string de alvo (chat_id:*, chat_guid:*, chat_identifier:*) em match.peer.id. Semântica compartilhada dos campos: ACP Agents.
• A configuração completa do canal BlueBubbles está documentada em BlueBubbles.

​

iMessage

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• channels.imessage.defaultAccount opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.
• Requer Full Disk Access para o banco de dados do Messages.
• Prefira alvos chat_id:<id>. Use imsg chats --limit 20 para listar chats.
• cliPath pode apontar para um wrapper SSH; defina remoteHost (host ou user@host) para buscar anexos via SCP.
• attachmentRoots e remoteAttachmentRoots restringem caminhos de anexos recebidos (padrão: /Users/*/Library/Messages/Attachments).
• SCP usa verificação estrita de chave do host, então garanta que a chave do host de relay já exista em ~/.ssh/known_hosts.
• channels.imessage.configWrites: permite ou nega gravações de configuração iniciadas pelo iMessage.
• Entradas bindings[] de nível superior com type: "acp" podem vincular conversas do iMessage a sessões ACP persistentes. Use um handle normalizado ou alvo explícito de chat (chat_id:*, chat_guid:*, chat_identifier:*) em match.peer.id. Semântica compartilhada dos campos: ACP Agents.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

​

Matrix

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

• Autenticação por token usa accessToken; autenticação por senha usa userId + password.
• channels.matrix.proxy roteia tráfego HTTP do Matrix por um proxy HTTP(S) explícito. Contas nomeadas podem substituí-lo com channels.matrix.accounts.<id>.proxy.
• channels.matrix.allowPrivateNetwork permite homeservers privados/internos. proxy e allowPrivateNetwork são controles independentes.
• channels.matrix.defaultAccount seleciona a conta preferida em configurações com múltiplas contas.
• channels.matrix.execApprovals: entrega nativa de aprovações de exec no Matrix e autorização de aprovadores.
  • enabled: true, false ou "auto" (padrão). No modo auto, aprovações de exec são ativadas quando aprovadores podem ser resolvidos de approvers ou commands.ownerAllowFrom.
  • approvers: IDs de usuário do Matrix (por exemplo @owner:example.org) autorizados a aprovar solicitações de exec.
  • agentFilter: allowlist opcional de ID de agente. Omita para encaminhar aprovações para todos os agentes.
  • sessionFilter: padrões opcionais de chave de sessão (substring ou regex).
  • target: onde enviar prompts de aprovação. "dm" (padrão), "channel" (sala de origem) ou "both".
  • Substituições por conta: channels.matrix.accounts.<id>.execApprovals.
• Sondagens de status do Matrix e consultas ao diretório em tempo real usam a mesma política de proxy do tráfego em runtime.
• Configuração completa do Matrix, regras de destino e exemplos de configuração estão documentados em Matrix.

​

Microsoft Teams

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, políticas de time/canal:
      // consulte /channels/msteams
    },
  },
}

• Caminhos de chave principais cobertos aqui: channels.msteams, channels.msteams.configWrites.
• A configuração completa do Teams (credenciais, webhook, política de DM/grupo, substituições por time/canal) está documentada em Microsoft Teams.

​

IRC

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "bot@example.com",
      },
    },
  },
}

• Caminhos de chave principais cobertos aqui: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• channels.irc.defaultAccount opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.
• A configuração completa do canal IRC (host/porta/TLS/canais/allowlists/controle por menção) está documentada em IRC.

​

Múltiplas contas (todos os canais)

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• default é usado quando accountId é omitido (CLI + roteamento).
• Tokens por env só se aplicam à conta default.
• Configurações base do canal se aplicam a todas as contas, a menos que sejam substituídas por conta.
• Use bindings[].match.accountId para rotear cada conta para um agente diferente.
• Se você adicionar uma conta não padrão via openclaw channels add (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de conta única de nível superior, o OpenClaw primeiro promove os valores de conta única de nível superior com escopo de conta para o mapa de contas do canal, para que a conta original continue funcionando. A maioria dos canais os move para channels.<channel>.accounts.default; Matrix pode preservar um alvo nomeado/padrão existente correspondente em vez disso.
• Bindings existentes apenas de canal (sem accountId) continuam correspondendo à conta padrão; bindings com escopo de conta continuam opcionais.
• openclaw doctor --fix também repara formas mistas movendo valores de conta única de nível superior com escopo de conta para a conta promovida escolhida para esse canal. A maioria dos canais usa accounts.default; Matrix pode preservar um alvo nomeado/padrão existente correspondente em vez disso.

​

Outros canais de extensão

​

Controle por menção em chats de grupo

• Menções por metadados: @-mentions nativas da plataforma. Ignoradas no modo de chat consigo mesmo do WhatsApp.
• Padrões de texto: padrões regex seguros em agents.list[].groupChat.mentionPatterns. Padrões inválidos e repetições aninhadas inseguras são ignorados.
• O controle por menção é aplicado apenas quando a detecção é possível (menções nativas ou pelo menos um padrão).

{
  messages: {
    groupChat: { historyLimit: 50 },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

​

Limites de histórico de DM

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

​

Modo de chat consigo mesmo

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

​

Commands (tratamento de comandos de chat)

{
  commands: {
    native: "auto", // registrar comandos nativos quando compatível
    text: true, // analisar /commands em mensagens de chat
    bash: false, // permitir ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // permitir /config
    debug: false, // permitir /debug
    restart: false, // permitir /restart + ferramenta gateway restart
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

​

Padrões do agente

​

agents.defaults.workspace

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

​

agents.defaults.repoRoot

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

​

agents.defaults.skills

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" }, // herda github, weather
      { id: "docs", skills: ["docs-search"] }, // substitui padrões
      { id: "locked-down", skills: [] }, // sem Skills
    ],
  },
}

• Omita agents.defaults.skills para Skills irrestritas por padrão.
• Omita agents.list[].skills para herdar os padrões.
• Defina agents.list[].skills: [] para nenhuma Skill.
• Uma lista não vazia em agents.list[].skills é o conjunto final para aquele agente; ela não é mesclada com os padrões.

​

agents.defaults.skipBootstrap

{
  agents: { defaults: { skipBootstrap: true } },
}

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

{
  agents: { defaults: { bootstrapTotalMaxChars: 150000 } },
}

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": nunca injeta texto de aviso no prompt do sistema.
• "once": injeta o aviso uma vez por assinatura única de truncamento (recomendado).
• "always": injeta aviso em toda execução quando houver truncamento.

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always
}

​

agents.defaults.imageMaxDimensionPx

{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}

​

agents.defaults.userTimezone

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

​

agents.defaults.timeFormat

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

​

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-1",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-i2v"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      params: { cacheRetention: "long" }, // parâmetros globais padrão do provedor
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: aceita string ("provider/model") ou objeto ({ primary, fallbacks }).
  • A forma string define apenas o modelo primário.
  • A forma objeto define o primário mais modelos de failover ordenados.
• imageModel: aceita string ("provider/model") ou objeto ({ primary, fallbacks }).
  • Usado pelo caminho da ferramenta image como configuração do modelo de visão.
  • Também usado como roteamento de fallback quando o modelo selecionado/padrão não aceita entrada de imagem.
• imageGenerationModel: aceita string ("provider/model") ou objeto ({ primary, fallbacks }).
  • Usado pela capacidade compartilhada de geração de imagens e qualquer futura superfície de ferramenta/plugin que gere imagens.
  • Valores típicos: google/gemini-3.1-flash-image-preview para geração nativa de imagem do Gemini, fal/fal-ai/flux/dev para fal, ou openai/gpt-image-1 para OpenAI Images.
  • Se você selecionar diretamente um provider/model, configure também a autenticação/chave de API correspondente do provedor (por exemplo GEMINI_API_KEY ou GOOGLE_API_KEY para google/*, OPENAI_API_KEY para openai/*, FAL_KEY para fal/*).
  • Se omitido, image_generate ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os provedores restantes de geração de imagem registrados na ordem de provider-id.
• videoGenerationModel: aceita string ("provider/model") ou objeto ({ primary, fallbacks }).
  • Usado pela capacidade compartilhada de geração de vídeo.
  • Valores típicos: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash ou qwen/wan2.7-r2v.
  • Defina isso explicitamente antes de usar a geração compartilhada de vídeo. Diferentemente de imageGenerationModel, o runtime de geração de vídeo ainda não infere um provedor padrão.
  • Se você selecionar diretamente um provider/model, configure também a autenticação/chave de API correspondente do provedor.
  • O provedor empacotado de geração de vídeo Qwen atualmente suporta até 1 vídeo de saída, 1 imagem de entrada, 4 vídeos de entrada, duração de 10 segundos e opções no nível do provedor size, aspectRatio, resolution, audio e watermark.
• pdfModel: aceita string ("provider/model") ou objeto ({ primary, fallbacks }).
  • Usado pela ferramenta pdf para roteamento de modelo.
  • Se omitido, a ferramenta PDF usa imageModel como fallback, depois o modelo de sessão/padrão resolvido.
• pdfMaxBytesMb: limite padrão de tamanho de PDF para a ferramenta pdf quando maxBytesMb não é passado no momento da chamada.
• pdfMaxPages: máximo padrão de páginas consideradas pelo modo de fallback de extração na ferramenta pdf.
• verboseDefault: nível padrão de verbose para agentes. Valores: "off", "on", "full". Padrão: "off".
• elevatedDefault: nível padrão de saída elevada para agentes. Valores: "off", "on", "ask", "full". Padrão: "on".
• model.primary: formato provider/model (por exemplo openai/gpt-5.4). Se você omitir o provedor, o OpenClaw tenta primeiro um alias, depois uma correspondência única de provedor configurado para aquele id exato de modelo, e só então usa o provedor padrão configurado como fallback (comportamento de compatibilidade obsoleto, então prefira provider/model explícito). Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw usa como fallback o primeiro provedor/modelo configurado em vez de expor um padrão obsoleto de provedor removido.
• models: catálogo de modelos configurado e allowlist para /model. Cada entrada pode incluir alias (atalho) e params (específicos do provedor, por exemplo temperature, maxTokens, cacheRetention, context1m).
• params: parâmetros globais padrão do provedor aplicados a todos os modelos. Defina em agents.defaults.params (por exemplo { cacheRetention: "long" }).
• Precedência de mesclagem de params (config): agents.defaults.params (base global) é substituído por agents.defaults.models["provider/model"].params (por modelo), depois agents.list[].params (id de agente correspondente) substitui por chave. Consulte Prompt Caching para detalhes.
• Escritores de configuração que alteram esses campos (por exemplo /models set, /models set-image e comandos de adicionar/remover fallback) salvam a forma canônica de objeto e preservam listas de fallback existentes quando possível.
• maxConcurrent: máximo de execuções paralelas de agente entre sessões (cada sessão ainda é serializada). Padrão: 4.

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• Backends de CLI são orientados a texto; ferramentas sempre ficam desabilitadas.
• Sessões são compatíveis quando sessionArg está definido.
• Pass-through de imagem é compatível quando imageArg aceita caminhos de arquivo.

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m desabilita
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        lightContext: false, // padrão: false; true mantém apenas HEARTBEAT.md dos arquivos bootstrap do workspace
        isolatedSession: false, // padrão: false; true executa cada heartbeat em uma sessão nova (sem histórico de conversa)
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (padrão) | block
        target: "none", // padrão: none | opções: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
      },
    },
  },
}

• every: string de duração (ms/s/m/h). Padrão: 30m (autenticação por chave de API) ou 1h (autenticação OAuth). Defina 0m para desabilitar.
• suppressToolErrorWarnings: quando true, suprime cargas de aviso de erro de ferramenta durante execuções de heartbeat.
• directPolicy: política de entrega direta/DM. allow (padrão) permite entrega para alvo direto. block suprime entrega para alvo direto e emite reason=dm-blocked.
• lightContext: quando true, execuções de heartbeat usam contexto bootstrap leve e mantêm apenas HEARTBEAT.md dos arquivos bootstrap do workspace.
• isolatedSession: quando true, cada heartbeat é executado em uma sessão nova sem histórico anterior de conversa. Mesmo padrão de isolamento de cron sessionTarget: "isolated". Reduz o custo por heartbeat de ~100K para ~2-5K tokens.
• Por agente: defina agents.list[].heartbeat. Quando qualquer agente define heartbeat, somente esses agentes executam heartbeats.
• Heartbeats executam turnos completos do agente — intervalos menores consomem mais tokens.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // usado quando identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] desabilita reinjeção
        model: "openrouter/anthropic/claude-sonnet-4-6", // substituição opcional de modelo apenas para compactação
        notifyUser: true, // envia um aviso breve quando a compactação começa (padrão: false)
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode: default ou safeguard (sumarização em blocos para históricos longos). Consulte Compaction.
• timeoutSeconds: máximo de segundos permitidos para uma única operação de compactação antes que o OpenClaw a aborte. Padrão: 900.
• identifierPolicy: strict (padrão), off ou custom. strict antepõe instruções embutidas de retenção de identificadores opacos durante a sumarização de compactação.
• identifierInstructions: texto opcional personalizado de preservação de identificadores usado quando identifierPolicy=custom.
• postCompactionSections: nomes opcionais de seções H2/H3 de AGENTS.md para reinjetar após a compactação. Padrão ["Session Startup", "Red Lines"]; defina [] para desabilitar a reinjeção. Quando não definido ou explicitamente definido para esse par padrão, os cabeçalhos antigos Every Session/Safety também são aceitos como fallback legado.
• model: substituição opcional provider/model-id apenas para sumarização de compactação. Use quando a sessão principal deve manter um modelo, mas os resumos de compactação devem usar outro; quando não definido, a compactação usa o modelo primário da sessão.
• notifyUser: quando true, envia um aviso breve ao usuário quando a compactação começa (por exemplo, “Compacting context…”). Desabilitado por padrão para manter a compactação silenciosa.
• memoryFlush: turno agêntico silencioso antes da autocompactação para armazenar memórias duráveis. Ignorado quando o workspace é somente leitura.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duração (ms/s/m/h), unidade padrão: minutos
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

​

Block streaming

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200 },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs)
    },
  },
}

• Canais que não sejam Telegram exigem *.blockStreaming: true explícito para habilitar respostas em bloco.
• Substituições por canal: channels.<channel>.blockStreamingCoalesce (e variantes por conta). Signal/Slack/Discord/Google Chat usam por padrão minChars: 1500.
• humanDelay: pausa aleatória entre respostas em bloco. natural = 800–2500ms. Substituição por agente: agents.list[].humanDelay.

​

Indicadores de digitação

{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}

• Padrões: instant para chats diretos/menções, message para chats de grupo sem menção.
• Substituições por sessão: session.typingMode, session.typingIntervalSeconds.

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // SecretRefs / conteúdos inline também são compatíveis:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

{
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          mode: "mirror", // mirror | remote
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // opcional
          gatewayEndpoint: "https://lab.example", // opcional
          policy: "strict", // id opcional da política OpenShell
          providers: ["openai"], // opcional
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # imagem principal do sandbox
scripts/sandbox-browser-setup.sh   # imagem opcional do navegador

​

agents.list (substituições por agente)

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // ou { primary, fallbacks }
        thinkingDefault: "high", // substituição de nível de thinking por agente
        reasoningDefault: "on", // substituição de visibilidade de reasoning por agente
        fastModeDefault: false, // substituição de fast mode por agente
        params: { cacheRetention: "none" }, // substitui defaults.models correspondentes por chave
        skills: ["docs-search"], // substitui agents.defaults.skills quando definido
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: id estável do agente (obrigatório).
• default: quando vários são definidos, o primeiro vence (aviso em log). Se nenhum estiver definido, a primeira entrada da lista é o padrão.
• model: a forma string substitui apenas primary; a forma objeto { primary, fallbacks } substitui ambos ([] desabilita fallbacks globais). Jobs de cron que substituem apenas primary ainda herdam fallbacks padrão, a menos que você defina fallbacks: [].
• params: parâmetros de stream por agente mesclados sobre a entrada de modelo selecionada em agents.defaults.models. Use para substituições específicas do agente como cacheRetention, temperature ou maxTokens sem duplicar todo o catálogo de modelos.
• skills: allowlist opcional de Skills por agente. Se omitido, o agente herda agents.defaults.skills quando definido; uma lista explícita substitui os padrões em vez de mesclar, e [] significa nenhuma Skill.
• thinkingDefault: padrão opcional de nível de thinking por agente (off | minimal | low | medium | high | xhigh | adaptive). Substitui agents.defaults.thinkingDefault para esse agente quando nenhuma substituição por mensagem ou sessão estiver definida.
• reasoningDefault: padrão opcional de visibilidade de reasoning por agente (on | off | stream). Aplica-se quando não há substituição de reasoning por mensagem ou sessão.
• fastModeDefault: padrão opcional de fast mode por agente (true | false). Aplica-se quando não há substituição por mensagem ou sessão.
• runtime: descritor opcional de runtime por agente. Use type: "acp" com padrões em runtime.acp (agent, backend, mode, cwd) quando o agente deve usar por padrão sessões de harness ACP.
• identity.avatar: caminho relativo ao workspace, URL http(s) ou URI data:.
• identity deriva padrões: ackReaction de emoji, mentionPatterns de name/emoji.
• subagents.allowAgents: allowlist de ids de agente para sessions_spawn (["*"] = qualquer um; padrão: apenas o mesmo agente).
• Proteção de herança de sandbox: se a sessão solicitante estiver em sandbox, sessions_spawn rejeita alvos que seriam executados sem sandbox.
• subagents.requireAgentId: quando true, bloqueia chamadas de sessions_spawn que omitem agentId (força seleção explícita de perfil; padrão: false).

​

Roteamento multiagente

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

​

Campos de correspondência de binding

• type (opcional): route para roteamento normal (tipo ausente usa route como padrão), acp para bindings persistentes de conversa ACP.
• match.channel (obrigatório)
• match.accountId (opcional; * = qualquer conta; omitido = conta padrão)
• match.peer (opcional; { kind: direct|group|channel, id })
• match.guildId / match.teamId (opcional; específicos do canal)
• acp (opcional; somente para type: "acp"): { mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (exato, sem peer/guild/team)
5. match.accountId: "*" (para todo o canal)
6. Agente padrão

​

Perfis de acesso por agente

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: [
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
        tools: {
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
            "whatsapp",
            "telegram",
            "slack",
            "discord",
            "gateway",
          ],
          deny: [
            "read",
            "write",
            "edit",
            "apply_patch",
            "exec",
            "process",
            "browser",
            "canvas",
            "nodes",
            "cron",
            "gateway",
            "image",
          ],
        },
      },
    ],
  },
}

​

Sessão

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    parentForkMaxTokens: 100000, // ignora fork da thread pai acima dessa contagem de tokens (0 desabilita)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // duração ou false
      maxDiskBytes: "500mb", // orçamento rígido opcional
      highWaterBytes: "400mb", // alvo opcional de limpeza
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // padrão de desfoco automático por inatividade em horas (`0` desabilita)
      maxAgeHours: 0, // padrão de idade máxima rígida em horas (`0` desabilita)
    },
    mainKey: "main", // legado (o runtime sempre usa "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

Mensagens

{
  messages: {
    responsePrefix: "🦞", // ou "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 desabilita
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Prefixo de resposta

​

Reação de ack

• Usa por padrão identity.emoji do agente ativo; caso contrário "👀". Defina "" para desabilitar.
• Substituições por canal: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Ordem de resolução: conta → canal → messages.ackReaction → fallback de identidade.
• Escopo: group-mentions (padrão), group-all, direct, all.
• removeAckAfterReply: remove o ack após a resposta em Slack, Discord e Telegram.
• messages.statusReactions.enabled: habilita reações de status do ciclo de vida em Slack, Discord e Telegram. No Slack e Discord, quando não definido, mantém reações de status habilitadas quando reações de ack estão ativas. No Telegram, defina explicitamente como true para habilitar reações de status do ciclo de vida.

​

Debounce de entrada

​

TTS (text-to-speech)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
      openai: {
        apiKey: "openai_api_key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}

• auto controla auto-TTS. /tts off|always|inbound|tagged substitui por sessão.
• summaryModel substitui agents.defaults.model.primary para auto-summary.
• modelOverrides é habilitado por padrão; modelOverrides.allowProvider usa false como padrão (opt-in).
• Chaves de API usam como fallback ELEVENLABS_API_KEY/XI_API_KEY e OPENAI_API_KEY.
• openai.baseUrl substitui o endpoint de TTS da OpenAI. A ordem de resolução é config, depois OPENAI_TTS_BASE_URL, depois https://api.openai.com/v1.
• Quando openai.baseUrl aponta para um endpoint que não é da OpenAI, o OpenClaw o trata como um servidor TTS compatível com OpenAI e flexibiliza a validação de modelo/voz.

​

Talk

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
    },
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
}

• talk.provider precisa corresponder a uma chave em talk.providers quando vários provedores Talk estiverem configurados.
• Chaves planas legadas de Talk (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) são apenas de compatibilidade e são migradas automaticamente para talk.providers.<provider>.
• IDs de voz usam como fallback ELEVENLABS_VOICE_ID ou SAG_VOICE_ID.
• providers.*.apiKey aceita strings em texto simples ou objetos SecretRef.
• O fallback ELEVENLABS_API_KEY só se aplica quando nenhuma chave de API de Talk estiver configurada.
• providers.*.voiceAliases permite que diretivas de Talk usem nomes amigáveis.
• silenceTimeoutMs controla quanto tempo o modo Talk aguarda após o silêncio do usuário antes de enviar a transcrição. Quando não definido, mantém a janela padrão de pausa da plataforma (700 ms no macOS e Android, 900 ms no iOS).

​

Ferramentas

​

Perfis de ferramenta

​

Grupos de ferramentas

​

tools.allow / tools.deny

{
  tools: { deny: ["browser", "canvas"] },
}

​

tools.byProvider

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },
    },
  },
}