Operações seguras com arquivos

OpenClaw usa @openclaw/fs-safe para operações locais de arquivos sensíveis à segurança: leituras/gravações limitadas à raiz, substituição atômica, extração de arquivos compactados, espaços de trabalho temporários, estado em JSON e tratamento de arquivos de segredos.

É uma proteção de biblioteca para código confiável do OpenClaw que recebe nomes de caminhos não confiáveis, não uma sandbox. As permissões do sistema de arquivos do host, os usuários do sistema operacional, os contêineres e a política do agente/das ferramentas ainda definem o verdadeiro raio de impacto.

Padrão: sem auxiliar Python

O OpenClaw define o auxiliar Python POSIX do fs-safe como desativado por padrão:

• o Gateway não deve iniciar um processo auxiliar persistente em Python, a menos que um operador opte por isso;
• a maioria das instalações não precisa da proteção adicional contra alterações em diretórios-pai;
• desativar o Python mantém o comportamento em tempo de execução previsível em ambientes desktop, Docker, CI e de aplicativos empacotados.

O OpenClaw altera apenas o padrão. Uma configuração explícita sempre prevalece:

# Comportamento padrão do OpenClaw: alternativas do fs-safe somente com Node.OPENCLAW_FS_SAFE_PYTHON_MODE=off # Ativa o auxiliar quando disponível, recorrendo à alternativa se estiver indisponível.OPENCLAW_FS_SAFE_PYTHON_MODE=auto # Falha de forma segura se o auxiliar não puder ser iniciado.OPENCLAW_FS_SAFE_PYTHON_MODE=require # Caminho explícito opcional para o interpretador.OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3

Os nomes genéricos de variáveis de ambiente do fs-safe também funcionam: FS_SAFE_PYTHON_MODE e FS_SAFE_PYTHON.

Use require (não auto) quando o auxiliar fizer parte da sua postura de segurança; auto recorre silenciosamente ao comportamento somente com Node se o auxiliar não puder ser iniciado.

O que permanece protegido sem Python

Com o auxiliar desativado, o OpenClaw ainda conta com as proteções do fs-safe somente com Node:

• rejeita escapes de caminhos relativos (..), caminhos absolutos e separadores de caminho onde apenas nomes simples são permitidos;
• resolve operações por meio de um identificador de raiz confiável, em vez de verificações improvisadas com path.resolve(...).startsWith(...);
• recusa padrões de links simbólicos e links físicos em APIs que exigem essa política;
• abre arquivos com verificações de identidade quando a API retorna ou consome o conteúdo deles;
• grava arquivos de estado/configuração usando um arquivo temporário irmão e renomeação atômica;
• impõe limites de bytes para leituras e extração de arquivos compactados;
• aplica modos de arquivo privados a segredos e arquivos de estado quando exigido pela API.

Isso abrange o modelo de ameaças normal do OpenClaw: código confiável do Gateway processando entradas de caminho não confiáveis provenientes de modelos/plugins/canais dentro dos limites de um único operador confiável.

O que o Python acrescenta

Em POSIX, o auxiliar opcional mantém um processo Python persistente e usa operações do sistema de arquivos relativas a descritores de arquivo para alterações em diretórios-pai: renomear, remover, criar diretório, consultar/listar e alguns caminhos de gravação.

Isso reduz as janelas de condição de corrida sob o mesmo UID em que outro processo troca um diretório-pai entre a validação e a alteração — uma defesa em profundidade em hosts nos quais processos locais não confiáveis podem modificar os mesmos diretórios em que o OpenClaw opera.

Se sua implantação apresentar esse risco e a existência do Python for garantida, defina:

OPENCLAW_FS_SAFE_PYTHON_MODE=require

Orientações para plugins e o núcleo

• O acesso a arquivos destinado a plugins deve passar pelos auxiliares de openclaw/plugin-sdk/*, e não pelo fs bruto, quando um caminho vier de uma mensagem, saída do modelo, configuração ou entrada de plugin.
• O código do núcleo deve usar os wrappers do fs-safe em src/infra/* para que a política de processo do OpenClaw seja aplicada de forma consistente.
• A extração de arquivos compactados deve usar os auxiliares de arquivos compactados do fs-safe com limites explícitos de tamanho, quantidade de entradas, links e destino.
• Segredos devem usar os auxiliares de segredos do OpenClaw ou os auxiliares de segredos/estado privado do fs-safe; não implemente manualmente verificações de modo em torno de fs.writeFile.
• Para isolamento contra usuários locais hostis, não dependa apenas do fs-safe. Execute Gateways separados sob usuários ou hosts distintos do sistema operacional, ou use sandboxing.

Relacionado: Segurança, Sandboxing, Aprovações de execução, Segredos.