English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Skills

Configuração de Skills

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

json5
{  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)

skills.load.extraDirsstring[]

Diretórios adicionais de skills a verificar, com a menor precedência (depois de skills empacotadas e de Plugin). Os caminhos são expandidos com suporte a ~.

skills.load.allowSymlinkTargetsstring[]

Diretórios de destino reais confiáveis para os quais pastas de skills com symlink podem resolver, mesmo quando o symlink fica fora da raiz configurada. Use isto 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.

skills.load.watchbooleandefault: true

Observa pastas de skills e atualiza o snapshot de skills quando arquivos SKILL.md mudam. Abrange arquivos aninhados em raízes de skills agrupadas.

skills.load.watchDebounceMsnumberdefault: 250

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

Instalação (skills.install)

skills.install.preferBrewbooleandefault: true

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

skills.install.nodeManager"npm" | "pnpm" | "yarn" | "bun"default: "npm"

Preferência de gerenciador de pacotes Node para instalações de skills. Isto afeta apenas instalações de skills — o runtime do Gateway ainda deve usar Node (Bun não é recomendado para WhatsApp/Telegram). Use openclaw setup --node-manager para npm, pnpm ou bun; defina "yarn" manualmente para instalações de skills baseadas em Yarn.

skills.install.allowUploadedArchivesbooleandefault: false

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

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

Use security.installPolicy quando 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 preparou o material de origem e antes que a instalação ou atualização continue. Ela se aplica a skills do ClawHub, skills enviadas, skills Git/locais, instaladores de dependências de skills e origens de instalação/atualização de plugins.

json5
{  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"],      },    },  },}
security.installPolicy.enabledbooleandefault: 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.

security.installPolicy.targets("skill" | "plugin")[]

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

security.installPolicy.exec.commandstring

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

security.installPolicy.exec.argsstring[]

Argumentos estáticos passados depois de command.

security.installPolicy.exec.timeoutMsnumberdefault: 10000

Tempo máximo de execução em relógio de parede para uma decisão de política.

security.installPolicy.exec.noOutputTimeoutMsnumberdefault: timeoutMs

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

security.installPolicy.exec.maxOutputBytesnumberdefault: 1048576

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

security.installPolicy.exec.env"Record<string,
security.installPolicy.exec.passEnvstring[]

Nomes de variáveis de ambiente copiados do processo do OpenClaw para o processo de política. Apenas variáveis nomeadas são passadas.

security.installPolicy.exec.trustedDirsstring[]

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

security.installPolicy.exec.allowInsecurePathbooleandefault: false

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

security.installPolicy.exec.allowSymlinkCommandbooleandefault: false

Permite que o caminho de comando configurado seja um symlink. O destino resolvido ainda deve satisfazer as outras verificações de caminho. Argumentos de scripts interpretadores devem ser arquivos regulares diretos, não symlinks.

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": "..." }. Saída diferente de zero, timeout, JSON malformado, campos ausentes ou versões de protocolo sem suporte falham de forma fechada.

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 fechada quando a política está habilitada, mas indisponível. openclaw doctor realiza validação estática, e openclaw doctor --deep executa uma sondagem sintética de instalação contra o comando configurado.

Atualizações em massa aplicam a política por alvo: uma atualização de skill ou plugin bloqueada falha nesse alvo sem desabilitar a política nem pular alvos posteriores no lote.

Exemplo de stdin:

json
{  "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 de política mínimo:

js
#!/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 empacotadas

skills.allowBundledstring[]

Lista de permissões opcional apenas para skills empacotadas. Quando definida, apenas skills empacotadas na lista ficam elegíveis. Skills gerenciadas, no nível do agente e do workspace não são afetadas.

Entradas por skill (skills.entries)

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 está empacotada ou instalada. A skill empacotada coding-agent é opt-in — defina-a como true e garanta 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 em texto simples ou um SecretRef: { source: "env", provider: "default", id: "VAR_NAME" }.

"skills.entries.<key�����r�
"skills.entries.<key�w₫��ܩ

Listas de permissões de agentes (agents)

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

json5
{  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    ],  },}
agents.defaults.skillsstring[]

Lista de permissões de linha de base compartilhada herdada por agentes que omitem agents.list[].skills. Omita por completo para deixar skills irrestritas por padrão.

agents.list[].skillsstring[]

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

Workshop (skills.workshop)

skills.workshop.autonomous.enabledbooleandefault: false

Quando true, agentes podem criar propostas pendentes a partir de sinais duráveis de conversa após turnos bem-sucedidos. A criação de skills solicitada pelo usuário sempre passa pelo Skill Workshop, independentemente desta configuração.

skills.workshop.approvalPolicy"pending" | "auto"default: "pending"

pending exige aprovação do operador antes de aplicar, rejeitar ou colocar em quarentena por iniciativa do agente. auto permite essas ações sem aprovação.

skills.workshop.allowSymlinkTargetWritesbooleandefault: false

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

skills.workshop.maxPendingnumberdefault: 50

Máximo de propostas pendentes e em quarentena retidas por workspace.

skills.workshop.maxSkillBytesnumberdefault: 40000

Tamanho máximo do corpo da proposta em bytes. As descrições de propostas têm limite rígido de 160 bytes porque aparecem na saída de descoberta e listagem.

Por padrão, raízes de skills de workspace, agente de projeto, diretório extra e incluídas são limites de contenção. Uma pasta de skill com link simbólico em <workspace>/skills que resolve para fora da raiz é ignorada com uma mensagem de log.

Para permitir um layout intencional com link simbólico, declare o destino confiável:

json5
{  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 de realpath. 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 separadamente:

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

Diretórios gerenciados ~/.openclaw/skills e diretórios pessoais ~/.agents/skills já aceitam links simbólicos para diretórios de skills (a contenção por skill de SKILL.md ainda se aplica).

Skills em sandbox e variáveis de ambiente

Passe segredos para um sandbox Docker com:

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

Lembrete da ordem de carregamento

text
workspace/skills      (highest)workspace/.agents/skills~/.agents/skills~/.openclaw/skillsbundled skillsskills.load.extraDirs (lowest)

Alterações em skills e na configuração entram em vigor na próxima nova sessão 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, controles de acesso e formato de SKILL.md.
Criando skills

Autoria de skills personalizadas de workspace.
Skill Workshop

Fila de propostas para skills rascunhadas por agentes.
Comandos de barra

Catálogo nativo de comandos de barra e diretivas de chat.
Was this useful?
On this page

On this page