Pular para o conteúdo principal

Documentation Index

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

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

OpenClaw usa @openclaw/fs-safe para operações locais de arquivo sensíveis à segurança: leituras/gravações limitadas à raiz, substituição atômica, extração de arquivos compactados, workspaces temporários, estado JSON e tratamento de arquivos de segredo. O objetivo é uma barreira de proteção de biblioteca consistente para código OpenClaw confiável que recebe nomes de caminho não confiáveis. Ela não é uma sandbox. Permissões do sistema de arquivos do host, usuários do sistema operacional, contêineres e a política de agente/ferramenta ainda definem o raio de impacto real.

​
Padrão: sem auxiliar Python

OpenClaw deixa o auxiliar POSIX Python do fs-safe desativado por padrão. Por quê:
  • o Gateway não deve iniciar um sidecar Python persistente, a menos que um operador tenha optado por isso;
  • muitas instalações não precisam do reforço adicional contra mutação de diretório pai;
  • desabilitar Python mantém o comportamento de pacote/runtime mais previsível em ambientes de desktop, Docker, CI e aplicativo empacotado.
OpenClaw altera apenas o padrão. Se você definir explicitamente um modo, o fs-safe o respeita: 
# Default OpenClaw behavior: Node-only fs-safe fallbacks.
OPENCLAW_FS_SAFE_PYTHON_MODE=off

# Opt into the helper when available, falling back if unavailable.
OPENCLAW_FS_SAFE_PYTHON_MODE=auto

# Fail closed if the helper cannot start.
OPENCLAW_FS_SAFE_PYTHON_MODE=require

# Optional explicit interpreter.
OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3
Os nomes genéricos do fs-safe também funcionam: FS_SAFE_PYTHON_MODE e FS_SAFE_PYTHON.

​
O que continua protegido sem Python

Com o auxiliar desativado, OpenClaw ainda usa os caminhos Node do fs-safe para:
  • rejeitar escapes de caminho relativo como .., caminhos absolutos e separadores de caminho onde apenas nomes são permitidos;
  • resolver operações por meio de um identificador de raiz confiável em vez de verificações ad hoc path.resolve(...).startsWith(...);
  • recusar padrões de symlink e hardlink em APIs que exigem essa política;
  • abrir arquivos com verificações de identidade quando a API retorna ou consome conteúdo de arquivo;
  • gravações atômicas em temporário irmão para arquivos de estado/configuração;
  • limites de bytes para leituras e extração de arquivos compactados;
  • modos privados para segredos e arquivos de estado quando a API os exige.
Essas proteções cobrem o modelo de ameaça normal do OpenClaw: código confiável do Gateway tratando entrada de caminho não confiável de modelo/plugin/canal dentro de um único limite de operador confiável.

​
O que Python adiciona

No POSIX, o auxiliar opcional do fs-safe mantém um processo Python persistente e usa operações de sistema de arquivos relativas a fd para mutações de diretório pai, como renomear, remover, criar diretório, stat/list e alguns caminhos de gravação. Isso reduz janelas de corrida de mesmo UID em que outro processo pode trocar um diretório pai entre a validação e a mutação. É defesa em profundidade para hosts onde processos locais não confiáveis podem modificar os mesmos diretórios em que o OpenClaw está operando. Se sua implantação tem esse risco e há garantia de que Python existe, use: 
OPENCLAW_FS_SAFE_PYTHON_MODE=require
Use require em vez de auto quando o auxiliar fizer parte da sua postura de segurança; auto intencionalmente recorre ao comportamento apenas Node se o auxiliar estiver indisponível.

​
Orientação para Plugin e core

  • O acesso a arquivos voltado a plugins deve passar por auxiliares openclaw/plugin-sdk/*, não por fs bruto, quando um caminho vem de uma mensagem, saída de modelo, configuração ou entrada de plugin.
  • Código core deve usar os wrappers locais 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 arquivo compactado do fs-safe com limites explícitos de tamanho, contagem de entradas, links e destino.
  • Segredos devem usar auxiliares de segredo do OpenClaw ou auxiliares de segredo/estado privado do fs-safe; não implemente manualmente verificações de modo em torno de fs.writeFile.
  • Se você precisa de isolamento contra usuários locais hostis, não dependa apenas do fs-safe. Execute Gateways separados sob usuários/hosts separados do sistema operacional ou use sandboxing.
Relacionado: Segurança, Sandboxing, Aprovações de execução, Segredos.