​

Referência de configuração

• openclaw config schema imprime o JSON Schema em tempo real usado para validação e para a Control UI, com metadados de bundled/plugin/channel mesclados quando disponíveis
• config.schema.lookup retorna um nó do schema com escopo de caminho para ferramentas de inspeção detalhada
• pnpm config:docs:check / pnpm config:docs:gen validam o hash de baseline da documentação de configuração em relação à superfície atual do schema

• Referência de configuração de memória para agents.defaults.memorySearch.*, memory.qmd.*, memory.citations e configuração de Dreaming em plugins.entries.memory-core.config.dreaming
• Comandos de barra para o catálogo atual de comandos internos + bundled
• páginas do canal/plugin proprietário para superfícies de comando específicas de cada canal

​

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 de citação/thread/histórico), allowlist (inclui contexto apenas de remetentes na lista de permissões), 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 uma saída de Heartbeat compacta no estilo indicador.

​

WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // blue ticks (false in self-chat mode)
      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 | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits)
      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.
• O opcional channels.telegram.defaultAccount substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
• Em configurações com várias 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 emite um aviso 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 de nível superior bindings[] com type: "acp" configuram vínculos persistentes de ACP para tópicos de fórum (use o formato canônico chatId:topic:topicId em match.peer.id). A semântica dos campos é compartilhada em ACP Agents.
• As prévias de streaming do Telegram usam sendMessage + editMessageText (funciona em chats diretos e em grupo).
• Política de retry: consulte Política de retry.

​

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      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 | batched
      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 maps to partial on Discord)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in for 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; as configurações de retry/política da conta ainda vêm da conta selecionada no snapshot ativo em tempo de execução.
• O opcional channels.discord.defaultAccount substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
• Use user:<id> (DM) ou channel:<id> (canal de guild) para alvos de entrega; IDs numéricos sem prefixo são rejeitados.
• Os slugs de guild são em minúsculas com espaços substituídos por -; as chaves de canal usam o nome em slug (sem #). Prefira IDs de guild.
• Mensagens criadas por bots são ignoradas por padrão. allowBots: true as habilita; use allowBots: "mentions" para aceitar apenas mensagens de bots que mencionem o bot (mensagens do próprio bot continuam filtradas).
• channels.discord.guilds.<id>.ignoreOtherMentions (e substituições no nível do canal) descarta mensagens que mencionam outro usuário ou cargo, mas não o bot (excluindo @everyone/@here).
• maxLinesPerMessage (padrão 17) divide mensagens altas mesmo quando estão 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 desativa)
  • maxAgeHours: substituição do Discord para idade máxima rígida em horas (0 desativa)
  • spawnSubagentSessions: chave de ativação para criação/vinculação automática de thread em sessions_spawn({ thread: true })
• Entradas de nível superior bindings[] com type: "acp" configuram vínculos persistentes de ACP para canais e threads (use o ID do 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 de componentes v2 do Discord.
• channels.discord.voice habilita conversas em canais de voz do Discord e substituições opcionais de entrada automática + TTS.
• channels.discord.voice.daveEncryption e channels.discord.voice.decryptionFailureTolerance são repassados para as opções DAVE de @discordjs/voice (true e 24 por padrão).
• O OpenClaw também tenta recuperar o recebimento de voz saindo e entrando novamente 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 tempo de execução para a presença do bot (healthy => online, degraded => idle, exhausted => dnd) e permite substituições opcionais de texto de status.
• channels.discord.dangerouslyAllowNameMatching reabilita a correspondência mutável por nome/tag (modo de compatibilidade break-glass).
• channels.discord.execApprovals: entrega nativa do Discord para aprovações de execução e autorização de aprovadores.
  • enabled: true, false ou "auto" (padrão). No modo automático, as aprovações de execução são ativadas quando os aprovadores podem ser resolvidos a partir de approvers ou commands.ownerAllowFrom.
  • approvers: IDs de usuário do Discord autorizados a aprovar solicitações de execução. Usa commands.ownerAllowFrom como fallback quando omitido.
  • agentFilter: lista de permissões opcional de IDs de agentes. Omita para encaminhar aprovações para todos os agentes.
  • sessionFilter: padrões opcionais de chave de sessão (substring ou regex).
  • target: onde enviar os prompts de aprovação. "dm" (padrão) envia para as DMs dos aprovadores, "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 as DMs de aprovação após aprovação, recusa 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: embutido (serviceAccount) ou baseado em arquivo (serviceAccountFile).
• SecretRef da conta de serviço também é compatível (serviceAccountRef).
• Fallbacks por variável de ambiente: GOOGLE_CHAT_SERVICE_ACCOUNT ou GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Use spaces/<spaceId> ou users/<userId> para alvos de entrega.
• channels.googlechat.dangerouslyAllowNameMatching reabilita a 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 | batched
      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: {
        mode: "partial", // off | partial | block | progress
        nativeTransport: true, // use Slack native streaming API when mode=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 variável de ambiente 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 conseguiu resolver o valor do segredo.
• configWrites: false bloqueia gravações de configuração iniciadas pelo Slack.
• O opcional channels.slack.defaultAccount substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
• channels.slack.streaming.mode é a chave canônica do modo de streaming do Slack. channels.slack.streaming.nativeTransport controla o transporte nativo de streaming do Slack. Os valores legados streamMode, booleanos streaming e nativeStreaming são migrados automaticamente.
• Use user:<id> (DM) ou channel:<id> para alvos de entrega.

• O streaming nativo do Slack mais o status de thread no estilo “is typing…” do assistente do Slack requerem um alvo de resposta em thread. DMs de nível superior ficam fora de thread por padrão, então usam typingReaction ou entrega normal em vez da prévia no estilo thread.
• typingReaction adiciona uma reação temporária à mensagem recebida no Slack enquanto uma resposta está em execução e a remove quando termina. Use um shortcode de emoji do Slack como "hourglass_flowing_sand".
• channels.slack.execApprovals: entrega nativa do Slack para aprovações de execução 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",
        // Optional explicit URL for reverse-proxy/public deployments
        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 a partir do servidor Mattermost.
• Callbacks nativos de slash são autenticados com os tokens por comando retornados pelo Mattermost durante o registro do comando de barra. Se o registro falhar ou nenhum comando for ativado, o OpenClaw rejeitará callbacks com Unauthorized: invalid command token.
• Para hosts de callback privados/tailnet/internos, 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 bloqueio por menção por canal ("*" para padrão).
• O opcional channels.mattermost.defaultAccount substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.

​

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optional account binding
      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 a uma identidade específica de conta Signal.
• channels.signal.configWrites: permite ou nega gravações de configuração iniciadas pelo Signal.
• O opcional channels.signal.defaultAccount substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.

​

BlueBubbles

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, group controls, and advanced actions:
      // see /channels/bluebubbles
    },
  },
}

• Caminhos de chave principais cobertos aqui: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• O opcional channels.bluebubbles.defaultAccount substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
• Entradas de nível superior bindings[] com type: "acp" podem vincular conversas do BlueBubbles a sessões persistentes de ACP. Use um identificador ou string de alvo do BlueBubbles (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",
    },
  },
}

• O opcional channels.imessage.defaultAccount substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
• Requer Acesso Total ao Disco ao banco de dados do Messages.
• Prefira alvos chat_id:<id>. Use imsg chats --limit 20 para listar conversas.
• 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).
• O SCP usa verificação estrita de chave do host, então garanta que a chave do host de retransmissão já exista em ~/.ssh/known_hosts.
• channels.imessage.configWrites: permite ou nega gravações de configuração iniciadas pelo iMessage.
• Entradas de nível superior bindings[] com type: "acp" podem vincular conversas do iMessage a sessões persistentes de ACP. Use um identificador normalizado ou alvo explícito de conversa (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",
        },
      },
    },
  },
}

• A autenticação por token usa accessToken; a autenticação por senha usa userId + password.
• channels.matrix.proxy roteia o 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.network.dangerouslyAllowPrivateNetwork permite homeservers privados/internos. proxy e essa ativação de rede são controles independentes.
• channels.matrix.defaultAccount seleciona a conta preferida em configurações com várias contas.
• channels.matrix.autoJoin usa off por padrão, então salas convidadas e novos convites em estilo DM são ignorados até que você defina autoJoin: "allowlist" com autoJoinAllowlist ou autoJoin: "always".
• channels.matrix.execApprovals: entrega nativa do Matrix para aprovações de execução e autorização de aprovadores.
  • enabled: true, false ou "auto" (padrão). No modo automático, as aprovações de execução são ativadas quando os aprovadores podem ser resolvidos a partir de approvers ou commands.ownerAllowFrom.
  • approvers: IDs de usuário Matrix (por exemplo @owner:example.org) autorizados a aprovar solicitações de execução.
  • agentFilter: lista de permissões opcional de IDs de agentes. Omita para encaminhar aprovações para todos os agentes.
  • sessionFilter: padrões opcionais de chave de sessão (substring ou regex).
  • target: onde enviar os prompts de aprovação. "dm" (padrão), "channel" (sala de origem) ou "both".
  • Substituições por conta: channels.matrix.accounts.<id>.execApprovals.
• channels.matrix.dm.sessionScope controla como DMs do Matrix são agrupadas em sessões: per-user (padrão) compartilha por peer roteado, enquanto per-room isola cada sala de DM.
• Sondas de status do Matrix e pesquisas de diretório ao vivo usam a mesma política de proxy do tráfego de runtime.
• A configuração completa do Matrix, regras de direcionamento e exemplos de configuração estão documentados em Matrix.

​

Microsoft Teams

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // see /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 equipe/por 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.*.
• O opcional channels.irc.defaultAccount substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
• A configuração completa do canal IRC (host/porta/TLS/canais/listas de permissões/bloqueio por menção) está documentada em IRC.

​

Várias 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 de ambiente se aplicam apenas à conta default.
• As configurações básicas 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 no nível superior, o OpenClaw primeiro promove os valores de conta única no 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; o Matrix pode preservar um alvo nomeado/padrão correspondente já existente.
• Os vínculos existentes apenas de canal (sem accountId) continuam correspondendo à conta padrão; vínculos com escopo de conta continuam opcionais.
• openclaw doctor --fix também corrige formatos mistos movendo valores de conta única no nível superior com escopo de conta para a conta promovida escolhida para esse canal. A maioria dos canais usa accounts.default; o Matrix pode preservar um alvo nomeado/padrão correspondente já existente.

​

Outros canais de extensão

​

Bloqueio por menção em conversas de grupo

• Menções por metadados: @-mentions nativas da plataforma. Ignoradas no modo de conversa 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 bloqueio 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 conversa consigo mesmo

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

​

Comandos (tratamento de comandos de chat)

{
  commands: {
    native: "auto", // register native commands when supported
    nativeSkills: "auto", // register native skill commands when supported
    text: true, // parse /commands in chat messages
    bash: false, // allow ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // allow /config
    mcp: false, // allow /mcp
    plugins: false, // allow /plugins
    debug: false, // allow /debug
    restart: true, // allow /restart + gateway restart tool
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    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 os 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 Skills.
• 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.contextInjection

• "continuation-skip": turnos seguros de continuação (após uma resposta concluída do assistente) ignoram a reinjeção do bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de Heartbeat e novas tentativas após Compaction ainda recriam o contexto.

{
  agents: { defaults: { contextInjection: "continuation-skip" } },
}

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 12000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

{
  agents: { defaults: { bootstrapTotalMaxChars: 60000 } },
}

​

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 o aviso em toda execução quando houver truncamento.

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

​

Mapa de propriedade do orçamento de contexto

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: injeção normal de bootstrap do workspace.
• agents.defaults.startupContext.*: prelúdio de inicialização único de /new e /reset, incluindo arquivos recentes memory/*.md diários.
• skills.limits.*: a lista compacta de Skills injetada no prompt do sistema.
• agents.defaults.contextLimits.*: trechos limitados em runtime e blocos injetados pertencentes ao runtime.
• memory.qmd.limits.*: dimensionamento de snippets e injeção de busca de memória indexada.

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextLimits.*

​

agents.defaults.startupContext

{
  agents: {
    defaults: {
      startupContext: {
        enabled: true,
        applyOn: ["new", "reset"],
        dailyMemoryDays: 2,
        maxFileBytes: 16384,
        maxFileChars: 1200,
        maxTotalChars: 2800,
      },
    },
  },
}

​

agents.defaults.contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        memoryGetDefaultLines: 120,
        toolResultMaxChars: 16000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars: limite padrão de trecho de memory_get antes que metadados de truncamento e aviso de continuação sejam adicionados.
• memoryGetDefaultLines: janela padrão de linhas de memory_get quando lines é omitido.
• toolResultMaxChars: limite em tempo real de resultado de ferramenta usado para resultados persistidos e recuperação de overflow.
• postCompactionMaxChars: limite de trecho de AGENTS.md usado durante a injeção de atualização pós-Compaction.

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        toolResultMaxChars: 16000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000,
        },
      },
    ],
  },
}

​

skills.limits.maxSkillsPromptChars

{
  skills: {
    limits: {
      maxSkillsPromptChars: 18000,
    },
  },
}

​

agents.list[].skillsLimits.maxSkillsPromptChars

{
  agents: {
    list: [
      {
        id: "tiny-local",
        skillsLimits: {
          maxSkillsPromptChars: 6000,
        },
      },
    ],
  },
}

​

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
      embeddedHarness: {
        runtime: "auto", // auto | pi | registered harness id, e.g. codex
        fallback: "pi", // pi | none
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: aceita uma string ("provider/model") ou um objeto ({ primary, fallbacks }).
  • A forma string define apenas o modelo principal.
  • A forma objeto define o principal mais modelos ordenados de failover.
• imageModel: aceita uma string ("provider/model") ou um objeto ({ primary, fallbacks }).
  • Usado pelo caminho da ferramenta image como sua configuração de 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 uma string ("provider/model") ou um objeto ({ primary, fallbacks }).
  • Usado pela capacidade compartilhada de geração de imagem e por 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, depois os provedores restantes de geração de imagem registrados na ordem do ID do provedor.
• musicGenerationModel: aceita uma string ("provider/model") ou um objeto ({ primary, fallbacks }).
  • Usado pela capacidade compartilhada de geração de música e pela ferramenta interna music_generate.
  • Valores típicos: google/lyria-3-clip-preview, google/lyria-3-pro-preview ou minimax/music-2.5+.
  • Se omitido, music_generate ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual, depois os provedores restantes de geração de música registrados na ordem do ID do provedor.
  • Se você selecionar diretamente um provider/model, configure também a autenticação/chave de API correspondente do provedor.
• videoGenerationModel: aceita uma string ("provider/model") ou um objeto ({ primary, fallbacks }).
  • Usado pela capacidade compartilhada de geração de vídeo e pela ferramenta interna video_generate.
  • 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.
  • Se omitido, video_generate ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual, depois os provedores restantes de geração de vídeo registrados na ordem do ID do provedor.
  • Se você selecionar diretamente um provider/model, configure também a autenticação/chave de API correspondente do provedor.
  • O provedor bundled de geração de vídeo Qwen oferece suporte a 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 uma string ("provider/model") ou um objeto ({ primary, fallbacks }).
  • Usado pela ferramenta pdf para roteamento de modelo.
  • Se omitido, a ferramenta PDF recorre a imageModel e depois ao modelo padrão/de sessã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 verbose padrão 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 primeiro tenta um alias, depois uma correspondência exclusiva de provedor configurado para esse ID de modelo exato e só então recorre ao provedor padrão configurado (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 recorre ao primeiro provider/model configurado em vez de expor um padrão obsoleto de provedor removido.
• models: o catálogo de modelos configurado e a lista de permissões 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 (configuração): agents.defaults.params (base global) é substituído por agents.defaults.models["provider/model"].params (por modelo), então agents.list[].params (ID do agente correspondente) substitui por chave. Consulte Prompt Caching para detalhes.
• embeddedHarness: política padrão do runtime incorporado de baixo nível do agente. Use runtime: "auto" para permitir que harnesses de Plugin registrados assumam modelos compatíveis, runtime: "pi" para forçar o harness PI interno, ou um ID de harness registrado como runtime: "codex". Defina fallback: "none" para desativar o fallback automático para PI.
• Gravadores 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 agentes entre sessões (cada sessão ainda é serializada). Padrão: 4.

​

agents.defaults.embeddedHarness

{
  agents: {
    defaults: {
      model: "codex/gpt-5.4",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

• runtime: "auto", "pi" ou um ID de harness de Plugin registrado. O Plugin bundled Codex registra codex.
• fallback: "pi" ou "none". "pi" mantém o harness PI interno como fallback de compatibilidade. "none" faz com que a seleção ausente ou não compatível de harness de Plugin falhe em vez de usar PI silenciosamente.
• Substituições por ambiente: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> substitui runtime; OPENCLAW_AGENT_HARNESS_FALLBACK=none desativa o fallback para PI nesse processo.
• Para implantações somente Codex, defina model: "codex/gpt-5.4", embeddedHarness.runtime: "codex" e embeddedHarness.fallback: "none".
• Isso controla apenas o harness de chat incorporado. Geração de mídia, visão, PDF, música, vídeo e TTS ainda usam suas configurações de provider/model.

​

agents.defaults.cliBackends

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

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

​

agents.defaults.systemPromptOverride

{
  agents: {
    defaults: {
      systemPromptOverride: "You are a helpful assistant.",
    },
  },
}

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• 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 desativar.
• includeSystemPromptSection: quando false, omite a seção Heartbeat do prompt do sistema e ignora a injeção de HEARTBEAT.md no contexto bootstrap. Padrão: true.
• suppressToolErrorWarnings: quando true, suprime cargas de aviso de erro de ferramenta durante execuções de Heartbeat.
• timeoutSeconds: tempo máximo em segundos permitido para um turno de agente de Heartbeat antes de ser abortado. Deixe sem definir para usar agents.defaults.timeoutSeconds.
• directPolicy: política de entrega direta/DM. allow (padrão) permite entrega a alvo direto. block suprime entrega a 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 prévio de conversa. Mesmo padrão de isolamento de Cron sessionTarget: "isolated". Reduz o custo de tokens por Heartbeat de ~100K para ~2-5K tokens.
• Por agente: defina agents.list[].heartbeat. Quando qualquer agente define heartbeat, somente esses agentes executam Heartbeat.
• Heartbeats executam turnos completos de agente — intervalos mais curtos consomem mais tokens.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
        notifyUser: true, // send a brief notice when compaction starts (default: 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 (resumo em partes para históricos longos). Consulte Compaction.
• provider: ID de um Plugin de provedor de Compaction registrado. Quando definido, summarize() do provedor é chamado em vez do resumo LLM interno. Em caso de falha, recorre ao interno. Definir um provedor força mode: "safeguard". Consulte Compaction.
• timeoutSeconds: máximo de segundos permitidos para uma única operação de Compaction antes que o OpenClaw a interrompa. Padrão: 900.
• identifierPolicy: strict (padrão), off ou custom. strict adiciona instruções internas de preservação de identificadores opacos durante o resumo de Compaction.
• 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 Compaction. O padrão é ["Session Startup", "Red Lines"]; defina [] para desativar a reinjeção. Quando não definido ou explicitamente definido para esse par padrão, cabeçalhos antigos Every Session/Safety também são aceitos como fallback legado.
• model: substituição opcional de provider/model-id apenas para resumo de Compaction. Use isso quando a sessão principal deve manter um modelo, mas os resumos de Compaction devem executar em outro; quando não definido, a Compaction usa o modelo principal da sessão.
• notifyUser: quando true, envia um breve aviso ao usuário quando a Compaction começa (por exemplo, “Compactando contexto…”). Desativado por padrão para manter a Compaction silenciosa.
• memoryFlush: turno agentic silencioso antes da auto-Compaction 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", // duration (ms/s/m/h), default unit: minutes
        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"] },
      },
    },
  },
}

​

Streaming em blocos

{
  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 conversas diretas/menções, message para conversas em 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 / inline contents also supported:
          // 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", // optional
          gatewayEndpoint: "https://lab.example", // optional
          policy: "strict", // optional OpenShell policy id
          providers: ["openai"], // optional
          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", // or { primary, fallbacks }
        thinkingDefault: "high", // per-agent thinking level override
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        embeddedHarness: { runtime: "auto", fallback: "pi" },
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        skills: ["docs-search"], // replaces agents.defaults.skills when set
        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 prevalece (aviso registrado). Se nenhum for definido, a primeira entrada da lista é o padrão.
• model: a forma string substitui apenas primary; a forma objeto { primary, fallbacks } substitui ambos ([] desativa fallbacks globais). Jobs Cron que substituem apenas primary ainda herdam os 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 isto para substituições específicas do agente, como cacheRetention, temperature ou maxTokens, sem duplicar todo o catálogo de modelos.
• skills: lista opcional de permissões de Skills por agente. Se omitida, o agente herda agents.defaults.skills quando definido; uma lista explícita substitui os padrões em vez de mesclar, e [] significa nenhuma Skills.
• thinkingDefault: nível thinking padrão opcional por agente (off | minimal | low | medium | high | xhigh | adaptive). Substitui agents.defaults.thinkingDefault para este agente quando nenhuma substituição por mensagem ou sessão estiver definida.
• reasoningDefault: visibilidade reasoning padrão opcional por agente (on | off | stream). Aplica-se quando nenhuma substituição de reasoning por mensagem ou sessão estiver definida.
• fastModeDefault: padrão opcional por agente para modo rápido (true | false). Aplica-se quando nenhuma substituição de modo rápido por mensagem ou sessão estiver definida.
• embeddedHarness: substituição opcional por agente para a política de harness de baixo nível. Use { runtime: "codex", fallback: "none" } para tornar um agente exclusivo do Codex enquanto outros agentes mantêm o fallback PI padrão.
• runtime: descritor opcional de runtime por agente. Use type: "acp" com padrões de runtime.acp (agent, backend, mode, cwd) quando o agente deve usar sessões de harness ACP por padrão.
• 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: lista de permissões de IDs de agentes para sessions_spawn (["*"] = qualquer; 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 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 assume route), acp para vínculos 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ífico do canal)
• acp (opcional; apenas para entradas 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: "*" (em 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, // skip parent-thread fork above this token count (0 disables)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}