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 },    },  },}

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,      // 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"],      },    },  },}

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

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).

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

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 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    ],  },}

Workshop (skills.workshop)

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

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

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 incluídasskills.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