Runbook de exposição do Gateway

​

Escolha o padrão de exposição

​

Inventário preliminar

• Host do Gateway, usuário do sistema operacional e diretório de estado (padrão: ~/.openclaw).
• URL e modo de vinculação do Gateway (gateway.bind; porta padrão: 18789).
• Modo de autenticação, origem do token/senha ou origem da identidade do proxy confiável.
• Todos os canais habilitados e se aceitam mensagens diretas, grupos ou webhooks.
• Agentes acessíveis por remetentes não locais.
• Perfil de ferramentas, modo de sandbox e política de ferramentas elevadas para cada agente acessível.
• Credenciais externas disponíveis para esses agentes.
• Local do backup de ~/.openclaw/openclaw.json e das credenciais.

​

Verificações básicas

openclaw doctor
openclaw security audit
openclaw security audit --deep
openclaw health

openclaw gateway probe --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

​

Configuração mínima segura

{
  gateway: {
    bind: "loopback",
    auth: {
      mode: "token",
      token: "replace-with-a-long-random-token",
    },
  },
  session: {
    dmScope: "per-channel-peer",
  },
  agents: {
    defaults: {
      sandbox: { mode: "non-main" },
    },
  },
  tools: {
    profile: "messaging",
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false },
  },
}

​

Exposição de mensagens diretas e grupos

• Prefira dmPolicy: "pairing" ou uma lista allowFrom estrita em vez de dmPolicy: "open".
• Não combine listas de permissões com "*" e acesso amplo a ferramentas.
• Exija menções em grupos, a menos que a sala seja rigorosamente controlada.
• Defina session.dmScope: "per-channel-peer" (ou "per-account-channel-peer" para canais com várias contas) quando várias pessoas puderem enviar mensagens diretas ao bot, para que as sessões de mensagens diretas não compartilhem contexto.
• Encaminhe canais compartilhados para agentes com o mínimo de ferramentas e sem credenciais pessoais.

​

Verificações do proxy reverso

• O proxy deve autenticar os usuários antes de encaminhar as solicitações ao Gateway.
• O firewall ou a política de rede deve bloquear o acesso direto à porta do Gateway.
• gateway.trustedProxies deve listar somente os IPs de origem do proxy.
• O proxy deve remover ou sobrescrever cabeçalhos de identidade e encaminhamento fornecidos pelo cliente.
• Defina gateway.auth.trustedProxy.allowUsers quando o proxy atender a mais de um público.
• Use gateway.auth.trustedProxy.allowLoopback somente para um proxy no mesmo host em que os processos locais sejam confiáveis e o proxy seja responsável pelos cabeçalhos de identidade.

​

Análise de ferramentas e sandbox

• Confirme quais sessões são executadas no host e quais são executadas na sandbox.
• Negue ou exija aprovação para execução no host.
• Mantenha as ferramentas elevadas desabilitadas, a menos que um remetente específico e confiável precise delas.
• Evite ferramentas de navegador, canvas, Node, Cron, Gateway e criação de sessões em superfícies de mensagens abertas ou semiabertas.
• Mantenha as montagens vinculadas restritas; evite caminhos de credenciais, diretório pessoal, soquete do Docker e sistema.
• Use Gateways, usuários do sistema operacional ou hosts separados para limites de confiança substancialmente diferentes.

​

Validação após as alterações

1. Execute novamente openclaw security audit --deep.
2. Confirme que uma conexão autorizada é estabelecida com sucesso.
3. Confirme que um remetente ou uma sessão de navegador não autorizada tem o acesso negado.
4. Confirme que os segredos são ocultados nos logs.
5. Confirme que o roteamento de mensagens diretas/grupos alcança somente o agente pretendido.
6. Confirme que ferramentas de alto impacto solicitam aprovação ou têm o acesso negado.
7. Documente os avisos residuais aceitos.

​

Plano de reversão

{
  gateway: {
    bind: "loopback",
  },
  channels: {
    whatsapp: { dmPolicy: "disabled" },
    telegram: { dmPolicy: "disabled" },
    discord: { dmPolicy: "disabled" },
    slack: { dmPolicy: "disabled" },
  },
  tools: {
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false },
  },
}

1. Interrompa o encaminhamento público, o Tailscale Funnel ou as rotas do proxy reverso.
2. Troque os tokens/senhas do Gateway e as credenciais das integrações afetadas.
3. Remova "*" e remetentes inesperados das listas de permissões.
4. Analise os logs de auditoria recentes, o histórico de execuções, as chamadas de ferramentas e as alterações de configuração.
5. Execute novamente openclaw security audit --deep.
6. Reative o acesso usando o padrão mais restrito que atenda ao fluxo de trabalho.

​

Lista de verificação para análise

• O Gateway permanece restrito ao local loopback, a menos que haja um motivo documentado.
• O acesso fora do local loopback tem autenticação, proteção por firewall e nenhuma rota pública direta.
• Implantações com proxy confiável têm IPs de proxy estritos e controles de cabeçalhos.
• As mensagens diretas usam pareamento ou listas de permissões, e não acesso aberto por padrão.
• Os grupos exigem menções ou listas de permissões explícitas.
• Os canais compartilhados não têm acesso a credenciais pessoais.
• As sessões não principais são executadas no modo sandbox.
• A execução no host e as ferramentas elevadas são negadas ou condicionadas à aprovação.
• Os logs ocultam segredos.
• As constatações críticas da auditoria foram resolvidas.
• As etapas de reversão foram testadas e documentadas.