Configuração de Skills

A maior parte da configuração de skills fica em skills no ~/.openclaw/openclaw.json. A visibilidade específica de cada agente fica em agents.defaults.skills e agents.list[].skills.

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm",
      allowUploadedArchives: false,
    },
    workshop: {
      autonomous: { enabled: false },
      allowSymlinkTargetWrites: false,
      approvalPolicy: "auto",
      maxPending: 50,
      maxSkillBytes: 40000,
    },
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

Para geração de imagens integrada, use agents.defaults.imageGenerationModel junto com a ferramenta principal image_generate, em vez de skills.entries. As entradas de skills destinam-se apenas a fluxos de trabalho de skills personalizados ou de terceiros.

Carregamento (`skills.load`)

string[]

Diretórios adicionais de skills a serem verificados, com a menor precedência (abaixo das skills integradas e de plugins). Os caminhos são expandidos com suporte a ~.

string[]

Diretórios de destino reais e confiáveis para os quais pastas de skills com links simbólicos podem apontar, mesmo quando o link simbólico está fora da raiz configurada. Use isso para layouts intencionais de repositórios irmãos, como <workspace>/skills/manager -> ~/Projects/manager/skills. Mantenha esta lista restrita — não aponte para raízes amplas como ~ ou ~/Projects.

boolean

padrão:"true"

Monitora as pastas de skills e atualiza o snapshot de skills quando os arquivos SKILL.md são alterados. Abrange arquivos aninhados em raízes de skills agrupadas.

number

padrão:"250"

Janela de debounce, em milissegundos, para eventos do monitor de skills.

Instalação (`skills.install`)

boolean

padrão:"true"

Prefere instaladores do Homebrew quando brew está disponível.

"npm" | "pnpm" | "yarn" | "bun"

padrão:"\"npm\""

Preferência de gerenciador de pacotes Node para instalações de skills. Isso afeta apenas as instalações de skills — a CLI do OpenClaw e o runtime do Gateway exigem Node porque o armazenamento de estado canônico usa node:sqlite. openclaw setup --node-manager e openclaw onboard --node-manager aceitam npm, pnpm ou bun; defina "yarn" diretamente na configuração para instalações de skills que usam Yarn.

boolean

padrão:"false"

Permite que clientes confiáveis do Gateway operator.admin instalem arquivos zip privados preparados por meio de skills.upload.*. Instalações normais do ClawHub não precisam dessa configuração.

Política de instalação do operador (`security.installPolicy`)

Use security.installPolicy quando os operadores precisarem de um comando local confiável para aprovar ou bloquear instalações de skills e plugins com uma política específica do host. A política é executada depois que o OpenClaw prepara o material de origem e antes que a instalação ou atualização prossiga. Ela se aplica a skills do ClawHub, skills enviadas, skills do Git/locais, instaladores de dependências de skills e origens de instalação/atualização de plugins.

{
  security: {
    installPolicy: {
      enabled: true,
      // Omita targets para abranger todos os destinos compatíveis.
      targets: ["skill", "plugin"],
      exec: {
        source: "exec",
        command: "/usr/local/bin/openclaw-install-policy",
        args: ["--json"],
        timeoutMs: 10000,
        noOutputTimeoutMs: 10000,
        maxOutputBytes: 1048576,
        passEnv: ["OPENCLAW_STATE_DIR", "PATH"],
        env: { POLICY_MODE: "strict" },
        trustedDirs: ["/usr/local/bin"],
      },
    },
  },
}

boolean

padrão:"false"

Habilita a política de instalação controlada pelo operador. Quando habilitada sem um comando exec válido, as instalações falham de forma fechada.

("skill" | "plugin")[]

Filtro de destino opcional. Quando omitido, a política se aplica a todos os destinos compatíveis, para que novas instalações não falhem de forma aberta inesperadamente.

string

Caminho absoluto para o executável confiável da política. O OpenClaw o executa sem um shell e valida o caminho antes do uso.

string[]

Argumentos estáticos passados depois de command.

number

padrão:"10000"

Tempo máximo total de execução para uma decisão de política.

number

padrão:"timeoutMs"

Tempo máximo sem saída em stdout ou stderr antes que a política falhe de forma fechada.

number

padrão:"1048576"

Máximo de bytes combinados de stdout e stderr aceitos do processo da política.

Record<string, string>

Variáveis de ambiente literais fornecidas ao processo da política.

string[]

Nomes de variáveis de ambiente copiados do processo do OpenClaw para o processo da política. Somente as variáveis nomeadas são repassadas.

string[]

Lista de permissões opcional de diretórios que podem conter o executável da política.

boolean

padrão:"false"

Ignora as verificações de propriedade e permissão do caminho do comando. Use somente quando o caminho estiver protegido por outro mecanismo.

boolean

padrão:"false"

Permite que o caminho do comando configurado seja um link simbólico. O destino resolvido ainda deve atender às demais verificações de caminho. Os argumentos de scripts do interpretador devem ser arquivos regulares diretos, não links simbólicos.

A política recebe um objeto JSON em stdin com protocolVersion: 1, openclawVersion, targetType, targetName, sourcePath, sourcePathKind, source estruturado opcional, origin estruturado e request. Ela deve gravar um objeto JSON em stdout: { "protocolVersion": 1, "decision": "allow" } ou { "protocolVersion": 1, "decision": "block", "reason": "..." }. Código de saída diferente de zero, tempo limite excedido, JSON malformado, campos ausentes ou versões de protocolo não compatíveis resultam em falha fechada. O OpenClaw não executa a política de instalação durante a inicialização normal do Gateway. As instalações e atualizações falham de forma fechada quando a política está habilitada, mas indisponível. openclaw doctor realiza validação estática; openclaw doctor --deep executa uma sondagem de instalação sintética no comando configurado. Atualizações em massa aplicam a política por destino: uma atualização de skill ou plugin bloqueada faz esse destino falhar sem desabilitar a política nem ignorar destinos posteriores no lote. Exemplo de stdin:

{
  "protocolVersion": 1,
  "openclawVersion": "2026.6.1",
  "targetType": "skill",
  "targetName": "weather",
  "sourcePath": "/var/folders/.../openclaw-skill-clawhub/root",
  "sourcePathKind": "directory",
  "source": {
    "kind": "clawhub",
    "authority": "openclaw",
    "mutable": false,
    "network": true
  },
  "origin": {
    "type": "clawhub",
    "registry": "https://clawhub.openclaw.ai",
    "slug": "weather",
    "version": "1.0.0"
  },
  "request": {
    "kind": "skill-install",
    "mode": "install",
    "requestedSpecifier": "clawhub:weather@1.0.0"
  },
  "skill": {
    "installId": "clawhub"
  }
}

Comando mínimo de política:

#!/usr/bin/env node

let input = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => {
  input += chunk;
});
process.stdin.on("end", () => {
  const request = JSON.parse(input);
  if (request.targetType === "plugin" && request.source?.kind === "local-path") {
    process.stdout.write(
      JSON.stringify({
        protocolVersion: 1,
        decision: "block",
        reason: "caminhos locais de plugins não são aprovados neste host",
      }),
    );
    return;
  }
  process.stdout.write(JSON.stringify({ protocolVersion: 1, decision: "allow" }));
});

Lista de permissões de skills integradas

string[]

Lista de permissões opcional somente para skills integradas. Quando definida, apenas as skills integradas presentes na lista são elegíveis. Skills gerenciadas, no nível do agente e do espaço de trabalho não são afetadas.

Entradas por skill (`skills.entries`)

As chaves em entries correspondem ao name da skill por padrão. Se uma skill definir metadata.openclaw.skillKey, use essa chave em vez disso. Coloque nomes com hífen entre aspas (JSON5 permite chaves entre aspas).

boolean

false desabilita a skill mesmo quando ela é integrada ou está instalada. A skill integrada coding-agent é opcional — defina-a como true e certifique-se de que uma das opções claude, codex, opencode ou outra CLI compatível esteja instalada e autenticada.

string | { source, provider, id }

Campo de conveniência para skills que declaram metadata.openclaw.primaryEnv. Aceita uma string de texto simples ou uma SecretRef: { source: "env", provider: "default", id: "VAR_NAME" }.

Record<string, string>

Variáveis de ambiente injetadas durante a execução do agente. São injetadas somente quando a variável ainda não está definida no processo.

object

Objeto opcional para campos personalizados de configuração por skill.

Listas de permissões de agentes (`agents`)

Use a configuração do agente quando quiser as mesmas raízes de skills da máquina/do espaço de trabalho, mas um conjunto diferente de skills visíveis por agente.

{
  agents: {
    defaults: {
      skills: ["github", "weather"], // linha de base compartilhada
    },
    list: [
      { id: "writer" }, // herda github, weather
      { id: "docs", skills: ["docs-search"] }, // substitui completamente os padrões
      { id: "locked-down", skills: [] }, // nenhuma skill
    ],
  },
}

string[]

Lista de permissões de referência compartilhada, herdada por agentes que omitem agents.list[].skills. Omita-a completamente para deixar as skills irrestritas por padrão.

string[]

Conjunto final explícito de skills para esse agente. Listas explícitas substituem os padrões herdados — elas não são mescladas. Defina como [] para não expor nenhuma skill a esse agente.

As listas de permissões de skills do agente são um filtro de visibilidade e carregamento para a descoberta de skills do OpenClaw, prompts, descoberta de comandos com barra, sincronização do sandbox e snapshots de skills. Elas não constituem um limite de autorização durante a execução do shell. Se um agente puder executar exec no host, esse shell ainda poderá executar clientes externos ou ler arquivos do host visíveis ao usuário de execução, incluindo registros de clientes MCP, como ~/.openclaw/skills/config/mcporter.json. Para isolamento de MCP por agente, combine listas de permissões de skills com isolamento por sandbox/usuário do SO, negue a execução no host ou restrinja-a rigorosamente por uma lista de permissões e prefira credenciais por agente no servidor MCP.

Workshop (`skills.workshop`)

boolean

padrão:"false"

Quando true, o OpenClaw pode criar propostas pendentes a partir de correções duráveis e pode revisar trabalhos concluídos substanciais e bem-sucedidos depois que o sistema ficar ocioso. Isso pode adicionar uma execução de modelo em segundo plano após turnos elegíveis. A criação de skills solicitada pelo usuário e /learn continuam funcionando quando a configuração está false.

Consulte Autoaprendizado para ver elegibilidade, privacidade, custo, permissões somente para propostas e solução de problemas.

"pending" | "auto"

padrão:"\"auto\""

auto permite que o agente aplique, rejeite ou coloque em quarentena por iniciativa própria, sem uma solicitação adicional de aprovação. pending exige aprovação do operador.

boolean

padrão:"false"

Permite que a aplicação do Skill Workshop grave por meio de links simbólicos de skills do workspace cujo destino real já seja confiável segundo skills.load.allowSymlinkTargets. Mantenha isso desabilitado, a menos que a aplicação de propostas geradas deva modificar essa raiz compartilhada de skills.

number

padrão:"50"

Número máximo de propostas pendentes e em quarentena mantidas por workspace (intervalo permitido: 1-200).

number

padrão:"40000"

Tamanho máximo do corpo da proposta em bytes (intervalo permitido: 1024-200000). As descrições das propostas têm um limite rígido separado de 160 bytes, pois aparecem na saída de descoberta e listagem.

Consulte Skill Workshop para ver o ciclo de vida das propostas, os comandos da CLI, os parâmetros de ferramentas do agente e os métodos do Gateway controlados por esta configuração.

Raízes de skills com links simbólicos

Por padrão, as raízes de skills do workspace, do agente do projeto, de diretórios extras e de skills incluídas são limites de contenção. Uma pasta de skill com link simbólico em <workspace>/skills que seja resolvida fora da raiz é ignorada com uma mensagem de log. Para permitir intencionalmente um layout com links simbólicos, declare o destino confiável:

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

Com esta configuração, <workspace>/skills/manager -> ~/Projects/manager/skills é aceito após a resolução do caminho real. extraDirs verifica diretamente o repositório irmão; allowSymlinkTargets preserva o caminho com link simbólico para layouts existentes. Por padrão, a aplicação do Skill Workshop não grava por meio desses links simbólicos. Para permitir que a aplicação do Workshop modifique skills em destinos de links simbólicos já confiáveis, habilite essa opção separadamente:

{
  skills: {
    load: {
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
    workshop: {
      allowSymlinkTargetWrites: true,
    },
  },
}

Os diretórios gerenciados ~/.openclaw/skills e pessoais ~/.agents/skills já aceitam incondicionalmente links simbólicos para diretórios de skills (a contenção de SKILL.md por skill ainda se aplica) — allowSymlinkTargets só é necessário para raízes do workspace, de diretórios extras e do agente do projeto (<workspace>/.agents/skills).

Skills em sandbox e variáveis de ambiente

skills.entries.<skill>.env e apiKey se aplicam somente a execuções no host. Dentro de uma sandbox, eles não têm efeito — uma skill que dependa de GEMINI_API_KEY falhará com apiKey not configured, a menos que a variável seja fornecida separadamente à sandbox.

Passe segredos para uma sandbox do Docker com:

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          env: { GEMINI_API_KEY: "your-key-here" },
        },
      },
    },
  },
}

Usuários com acesso ao daemon do Docker podem inspecionar os valores de sandbox.docker.env por meio dos metadados do Docker. Use um arquivo de segredo montado, uma imagem personalizada ou outro meio de fornecimento quando essa exposição não for aceitável.

Lembrete da ordem de carregamento

workspace/skills      (mais alta)
workspace/.agents/skills
~/.agents/skills
~/.openclaw/skills
skills incluídas
skills.load.extraDirs (mais baixa)

As alterações em skills e na configuração entram em vigor na próxima sessão nova quando o observador está habilitado, ou no próximo turno do agente quando o observador detecta uma alteração.

Relacionados

Referência de skills

O que são skills, ordem de carregamento, restrições e formato de SKILL.md.

Criação de skills

Criação de skills personalizadas para o workspace.

Skill Workshop

Fila de propostas para skills elaboradas pelo agente.

Autoaprendizado

Propostas conservadoras e opcionais provenientes de trabalhos concluídos.

Comandos de barra

Catálogo nativo de comandos de barra e diretivas de chat.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Configuração de Skills

Carregamento (`skills.load`)

Instalação (`skills.install`)

Política de instalação do operador (`security.installPolicy`)

Lista de permissões de skills integradas

Entradas por skill (`skills.entries`)

Listas de permissões de agentes (`agents`)

Workshop (`skills.workshop`)

Raízes de skills com links simbólicos

Skills em sandbox e variáveis de ambiente

Lembrete da ordem de carregamento

Relacionados

Referência de skills

Criação de skills

Skill Workshop

Autoaprendizado

Comandos de barra

​Carregamento (skills.load)

​Instalação (skills.install)

​Política de instalação do operador (security.installPolicy)

​Lista de permissões de skills integradas

​Entradas por skill (skills.entries)

​Listas de permissões de agentes (agents)

​Workshop (skills.workshop)

​Raízes de skills com links simbólicos

​Skills em sandbox e variáveis de ambiente

​Lembrete da ordem de carregamento

​Relacionados

Referência de skills

Criação de skills

Skill Workshop

Autoaprendizado

Comandos de barra

Carregamento (`skills.load`)

Instalação (`skills.install`)

Política de instalação do operador (`security.installPolicy`)

Lista de permissões de skills integradas

Entradas por skill (`skills.entries`)

Listas de permissões de agentes (`agents`)

Workshop (`skills.workshop`)

Raízes de skills com links simbólicos

Skills em sandbox e variáveis de ambiente

Lembrete da ordem de carregamento

Relacionados