Configuração de Skills

A maior parte da configuração de Skills fica em skills no arquivo ~/.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: "pending",      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 },    },  },}

Carregamento (skills.load)

Instalação (skills.install)

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,      // Omit targets to cover every supported target.      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"],      },    },  },}

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 escrever 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, JSON malformado, campos ausentes ou versões de protocolo não compatíveis causam falha segura.

O OpenClaw não executa a política de instalação durante a inicialização normal do Gateway. Instalações e atualizações falham de forma segura quando a política está ativada, mas indisponível. openclaw doctor executa uma validação estática; openclaw doctor --deep executa uma sondagem sintética de instalação usando o comando configurado.

Atualizações em massa aplicam a política a cada destino: uma atualização de Skill ou Plugin bloqueada causa falha nesse destino sem desativar a política nem ignorar os destinos posteriores do 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: "local plugin paths are not approved on this host",      }),    );    return;  }  process.stdout.write(JSON.stringify({ protocolVersion: 1, decision: "allow" }));});

Lista de permissões de Skills integradas

Entradas por Skill (skills.entries)

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

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNraWxscy5lbnRyaWVzLjxrZXk .enabled" type="boolean"> false desativa a Skill mesmo quando ela está integrada ou instalada. A Skill integrada coding-agent exige ativação explícita — defina-a como true e certifique-se de que claude, codex, opencode ou outra CLI compatível esteja instalada e autenticada.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNraWxscy5lbnRyaWVzLjxrZXk .apiKey" type='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" }.

Listas de permissões de agentes (agents)

Use a configuração do agente quando quiser manter as mesmas raízes de Skills da máquina/workspace, mas usar um conjunto diferente de Skills visíveis para cada agente.

{  agents: {    defaults: {      skills: ["github", "weather"], // shared baseline    },    list: [      { id: "writer" }, // inherits github, weather      { id: "docs", skills: ["docs-search"] }, // replaces defaults entirely      { id: "locked-down", skills: [] }, // no skills    ],  },}

Workshop (skills.workshop)

Consulte Skill Workshop para conhecer o ciclo de vida das propostas, os comandos da CLI, os parâmetros das 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 espaço de trabalho, do agente do projeto, de diretórios extras e das Skills integradas são limites de contenção. Uma pasta de Skill com link simbólico em <workspace>/skills que seja resolvida para fora da raiz é ignorada e uma mensagem é registrada no log.

Para permitir intencionalmente uma estrutura 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 adjacente; allowSymlinkTargets preserva o caminho com link simbólico para estruturas existentes.

Por padrão, a aplicação pelo Skill Workshop não grava por meio desses links simbólicos. Para permitir que a aplicação pelo 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 as raízes do espaço de trabalho, de diretórios extras e do agente do projeto (<workspace>/.agents/skills).

Skills em sandbox e variáveis de ambiente

Passe segredos para uma sandbox do Docker com:

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

Lembrete da ordem de carregamento

workspace/skills      (mais alta)workspace/.agents/skills~/.agents/skills~/.openclaw/skillsSkills integradasskills.load.extraDirs (mais baixa)

As alterações nas Skills e na configuração entram em vigor na próxima nova sessão quando o monitor estiver habilitado, ou no próximo turno do agente quando o monitor detectar uma alteração.

Relacionados