Configurazione delle Skills

La maggior parte della configurazione delle Skills si trova sotto skills in ~/.openclaw/openclaw.json. La visibilità specifica dell’agente si trova sotto 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 },
    },
  },
}

Per la generazione di immagini integrata, usare agents.defaults.imageGenerationModel insieme allo strumento principale image_generate invece di skills.entries. Le voci delle Skills sono destinate esclusivamente a flussi di lavoro delle Skills personalizzati o di terze parti.

Caricamento (`skills.load`)

string[]

Directory aggiuntive delle Skills da analizzare, con la precedenza più bassa (sotto le Skills incluse e dei Plugin). I percorsi vengono espansi con il supporto di ~.

string[]

Directory di destinazione reali e attendibili nelle quali possono risolversi le cartelle delle Skills collegate simbolicamente, anche quando il collegamento simbolico si trova all’esterno della radice configurata. Usare questa opzione per layout intenzionali con repository adiacenti, come <workspace>/skills/manager -> ~/Projects/manager/skills. Mantenere questo elenco ristretto: non indicare radici ampie come ~ o ~/Projects.

boolean

predefinito:"true"

Monitora le cartelle delle Skills e aggiorna l’istantanea delle Skills quando cambiano i file SKILL.md. Include i file annidati nelle radici raggruppate delle Skills.

number

predefinito:"250"

Finestra di debounce in millisecondi per gli eventi del monitoraggio delle Skills.

Installazione (`skills.install`)

boolean

predefinito:"true"

Preferisce i programmi di installazione Homebrew quando brew è disponibile.

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

predefinito:"\"npm\""

Gestore di pacchetti Node preferito per le installazioni delle Skills. Questa impostazione interessa soltanto le installazioni delle Skills: la CLI di OpenClaw e il runtime del Gateway richiedono Node perché l’archivio di stato canonico usa node:sqlite. openclaw setup --node-manager e openclaw onboard --node-manager accettano npm, pnpm o bun; impostare "yarn" direttamente nella configurazione per le installazioni delle Skills basate su Yarn.

boolean

predefinito:"false"

Consente ai client Gateway operator.admin attendibili di installare archivi zip privati preparati tramite skills.upload.*. Le normali installazioni da ClawHub non richiedono questa impostazione.

Criteri di installazione dell’operatore (`security.installPolicy`)

Usare security.installPolicy quando gli operatori necessitano di un comando locale attendibile per approvare o bloccare le installazioni di Skills e Plugin in base a criteri specifici dell’host. I criteri vengono eseguiti dopo che OpenClaw ha preparato il materiale sorgente e prima che l’installazione o l’aggiornamento prosegua. Si applicano alle Skills di ClawHub, alle Skills caricate, alle Skills Git/locali, ai programmi di installazione delle dipendenze delle Skills e alle origini di installazione/aggiornamento dei Plugin.

{
  security: {
    installPolicy: {
      enabled: true,
      // Omettere targets per includere ogni destinazione supportata.
      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

predefinito:"false"

Abilita i criteri di installazione gestiti dall’operatore. Se abilitati senza un comando exec valido, le installazioni vengono bloccate per impostazione predefinita.

("skill" | "plugin")[]

Filtro facoltativo delle destinazioni. Se omesso, i criteri si applicano a ogni destinazione supportata, affinché le nuove installazioni non vengano inaspettatamente consentite.

string

Percorso assoluto dell’eseguibile attendibile dei criteri. OpenClaw lo esegue senza una shell e convalida il percorso prima dell’uso.

string[]

Argomenti statici passati dopo command.

number

predefinito:"10000"

Durata massima effettiva di una decisione dei criteri.

number

predefinito:"timeoutMs"

Tempo massimo senza output su stdout o stderr prima che i criteri blocchino per impostazione predefinita.

number

predefinito:"1048576"

Numero massimo complessivo di byte di stdout e stderr accettati dal processo dei criteri.

Record<string, string>

Variabili d’ambiente letterali fornite al processo dei criteri.

string[]

Nomi delle variabili d’ambiente copiati dal processo OpenClaw nel processo dei criteri. Vengono passate soltanto le variabili indicate.

string[]

Elenco facoltativo delle directory consentite che possono contenere l’eseguibile dei criteri.

boolean

predefinito:"false"

Ignora i controlli sulla proprietà e sui permessi del percorso del comando. Usare questa opzione soltanto quando il percorso è protetto da un altro meccanismo.

boolean

predefinito:"false"

Consente che il percorso configurato del comando sia un collegamento simbolico. La destinazione risolta deve comunque soddisfare gli altri controlli del percorso. Gli argomenti degli script dell’interprete devono essere file regolari diretti, non collegamenti simbolici.

I criteri ricevono su stdin un oggetto JSON contenente protocolVersion: 1, openclawVersion, targetType, targetName, sourcePath, sourcePathKind, il valore strutturato facoltativo source, il valore strutturato origin e request. Devono scrivere un oggetto JSON su stdout: { "protocolVersion": 1, "decision": "allow" } oppure { "protocolVersion": 1, "decision": "block", "reason": "..." }. Un codice di uscita diverso da zero, un timeout, JSON non valido, campi mancanti o versioni del protocollo non supportate comportano il blocco per impostazione predefinita. OpenClaw non esegue i criteri di installazione durante il normale avvio del Gateway. Le installazioni e gli aggiornamenti vengono bloccati per impostazione predefinita quando i criteri sono abilitati ma non disponibili. openclaw doctor esegue la convalida statica; openclaw doctor --deep esegue una verifica sintetica dell’installazione usando il comando configurato. Gli aggiornamenti in blocco applicano i criteri a ciascuna destinazione: un aggiornamento bloccato di una Skill o di un Plugin non riesce per tale destinazione senza disabilitare i criteri né ignorare le destinazioni successive del gruppo. Esempio di 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 minimo per i criteri:

#!/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: "i percorsi locali dei plugin non sono approvati su questo host",
      }),
    );
    return;
  }
  process.stdout.write(JSON.stringify({ protocolVersion: 1, decision: "allow" }));
});

Elenco consentito delle Skills incluse

string[]

Elenco facoltativo consentito esclusivamente per le Skills incluse. Se impostato, soltanto le Skills incluse presenti nell’elenco sono idonee. Le Skills gestite, a livello di agente e dello spazio di lavoro non sono interessate.

Voci per singola Skill (`skills.entries`)

Per impostazione predefinita, le chiavi sotto entries corrispondono a name della Skill. Se una Skill definisce metadata.openclaw.skillKey, usare invece tale chiave. Racchiudere tra virgolette i nomi con trattini (JSON5 consente chiavi tra virgolette).

boolean

false disabilita la Skill anche se è inclusa o installata. La Skill inclusa coding-agent richiede l’abilitazione esplicita: impostarla su true e assicurarsi che claude, codex, opencode o un’altra CLI supportata sia installata e autenticata.

string | { source, provider, id }

Campo pratico per le Skills che dichiarano metadata.openclaw.primaryEnv. Supporta una stringa di testo normale o un SecretRef: { source: "env", provider: "default", id: "VAR_NAME" }.

Record<string, string>

Variabili d’ambiente inserite durante l’esecuzione dell’agente. Vengono inserite soltanto quando la variabile non è già impostata nel processo.

object

Contenitore facoltativo per campi di configurazione personalizzati per singola Skill.

Elenchi consentiti degli agenti (`agents`)

Usare la configurazione dell’agente quando si desiderano le stesse radici delle Skills della macchina/dello spazio di lavoro, ma un insieme diverso di Skills visibili per ciascun agente.

{
  agents: {
    defaults: {
      skills: ["github", "weather"], // base condivisa
    },
    list: [
      { id: "writer" }, // eredita github, weather
      { id: "docs", skills: ["docs-search"] }, // sostituisce completamente i valori predefiniti
      { id: "locked-down", skills: [] }, // nessuna Skill
    ],
  },
}

string[]

Elenco consentito di base condiviso, ereditato dagli agenti che omettono agents.list[].skills. Ometterlo completamente per lasciare le Skills senza restrizioni per impostazione predefinita.

string[]

Insieme finale esplicito di Skills per tale agente. Gli elenchi espliciti sostituiscono i valori predefiniti ereditati, senza unirsi a essi. Impostare su [] per non esporre alcuna Skill a tale agente.

Gli elenchi consentiti delle Skills degli agenti sono un filtro di visibilità e caricamento per il rilevamento delle Skills di OpenClaw, i prompt, il rilevamento dei comandi slash, la sincronizzazione della sandbox e le istantanee delle Skills. Non costituiscono un limite di autorizzazione durante l’esecuzione della shell. Se un agente può eseguire exec sull’host, tale shell può comunque eseguire client esterni o leggere file dell’host visibili all’utente di esecuzione, inclusi i registri dei client MCP come ~/.openclaw/skills/config/mcporter.json. Per isolare MCP per agente, combinare gli elenchi consentiti delle Skills con l’isolamento tramite sandbox/utente del sistema operativo, negare l’esecuzione sull’host o limitarla rigorosamente tramite un elenco consentito e preferire credenziali per agente nel server MCP.

Workshop (`skills.workshop`)

boolean

predefinito:"false"

Quando true, OpenClaw può creare proposte in sospeso a partire da correzioni persistenti e può esaminare il lavoro completato con successo, sostanziale, dopo che il sistema diventa inattivo. Ciò può aggiungere un’esecuzione del modello in background dopo i turni idonei. La creazione di skill richiesta dall’utente e /learn continuano a funzionare quando l’impostazione è false.

Consultare Autoapprendimento per idoneità, privacy, costi, autorizzazioni limitate alle proposte e risoluzione dei problemi.

"pending" | "auto"

predefinito:"\"auto\""

auto consente l’applicazione, il rifiuto o la quarantena avviati dall’agente senza un’ulteriore richiesta di approvazione. pending richiede l’approvazione dell’operatore.

boolean

predefinito:"false"

Consente all’applicazione di Skill Workshop di scrivere attraverso i collegamenti simbolici delle skill dell’area di lavoro il cui percorso di destinazione reale è già considerato attendibile da skills.load.allowSymlinkTargets. Mantenere disabilitata questa opzione, a meno che l’applicazione delle proposte generate debba modificare la radice condivisa delle skill.

number

predefinito:"50"

Numero massimo di proposte in sospeso e in quarantena conservate per area di lavoro (intervallo consentito: 1-200).

number

predefinito:"40000"

Dimensione massima del corpo della proposta in byte (intervallo consentito: 1024-200000). Le descrizioni delle proposte hanno separatamente un limite rigido di 160 byte, perché compaiono nell’output di individuazione e di elenco.

Consultare Skill Workshop per il ciclo di vita delle proposte, i comandi CLI, i parametri degli strumenti dell’agente e i metodi del Gateway controllati da questa configurazione.

Radici delle skill con collegamenti simbolici

Per impostazione predefinita, le radici delle skill dell’area di lavoro, dell’agente di progetto, delle directory aggiuntive e di quelle incluse costituiscono limiti di contenimento. Una cartella di skill con collegamento simbolico sotto <workspace>/skills che viene risolta all’esterno della radice viene ignorata con un messaggio nel log. Per consentire una struttura intenzionale di collegamenti simbolici, dichiarare attendibile la destinazione:

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

Con questa configurazione, <workspace>/skills/manager -> ~/Projects/manager/skills viene accettato dopo la risoluzione del percorso reale. extraDirs analizza direttamente il repository adiacente; allowSymlinkTargets conserva il percorso con collegamento simbolico per le strutture esistenti. Per impostazione predefinita, l’applicazione di Skill Workshop non scrive attraverso questi collegamenti simbolici. Per consentire all’applicazione di Workshop di modificare le skill nelle destinazioni con collegamenti simbolici già considerate attendibili, abilitare separatamente questa opzione:

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

Le directory gestite ~/.openclaw/skills e personali ~/.agents/skills accettano già incondizionatamente i collegamenti simbolici alle directory delle skill (il contenimento SKILL.md per singola skill continua ad applicarsi) — allowSymlinkTargets è necessario solo per le radici dell’area di lavoro, delle directory aggiuntive e dell’agente di progetto (<workspace>/.agents/skills).

Skill in sandbox e variabili di ambiente

skills.entries.<skill>.env e apiKey si applicano solo alle esecuzioni sull’host. All’interno di una sandbox non hanno alcun effetto: una skill che dipende da GEMINI_API_KEY non riuscirà con apiKey not configured, a meno che la variabile non venga fornita separatamente alla sandbox.

Passare i segreti a una sandbox Docker con:

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

Gli utenti con accesso al daemon Docker possono esaminare i valori sandbox.docker.env tramite i metadati Docker. Quando tale esposizione non è accettabile, utilizzare un file di segreti montato, un’immagine personalizzata o un altro percorso di distribuzione.

Promemoria sull’ordine di caricamento

workspace/skills      (priorità massima)
workspace/.agents/skills
~/.agents/skills
~/.openclaw/skills
skill incluse
skills.load.extraDirs (priorità minima)

Le modifiche alle skill e alla configurazione hanno effetto nella successiva nuova sessione quando il monitoraggio è abilitato, oppure nel turno successivo dell’agente quando il monitoraggio rileva una modifica.

Contenuti correlati

Riferimento delle skill

Cosa sono le skill, ordine di caricamento, criteri di abilitazione e formato SKILL.md.

Creazione delle skill

Creazione di skill personalizzate per l’area di lavoro.

Skill Workshop

Coda di proposte per le skill redatte dall’agente.

Autoapprendimento

Proposte conservative e facoltative derivanti dal lavoro completato.

Comandi slash

Catalogo nativo dei comandi slash e direttive della chat.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Configurazione delle Skills

Caricamento (`skills.load`)

Installazione (`skills.install`)

Criteri di installazione dell’operatore (`security.installPolicy`)

Elenco consentito delle Skills incluse

Voci per singola Skill (`skills.entries`)

Elenchi consentiti degli agenti (`agents`)

Workshop (`skills.workshop`)

Radici delle skill con collegamenti simbolici

Skill in sandbox e variabili di ambiente

Promemoria sull’ordine di caricamento

Contenuti correlati

Riferimento delle skill

Creazione delle skill

Skill Workshop

Autoapprendimento

Comandi slash

​Caricamento (skills.load)

​Installazione (skills.install)

​Criteri di installazione dell’operatore (security.installPolicy)

​Elenco consentito delle Skills incluse

​Voci per singola Skill (skills.entries)

​Elenchi consentiti degli agenti (agents)

​Workshop (skills.workshop)

​Radici delle skill con collegamenti simbolici

​Skill in sandbox e variabili di ambiente

​Promemoria sull’ordine di caricamento

​Contenuti correlati

Riferimento delle skill

Creazione delle skill

Skill Workshop

Autoapprendimento

Comandi slash

Caricamento (`skills.load`)

Installazione (`skills.install`)

Criteri di installazione dell’operatore (`security.installPolicy`)

Elenco consentito delle Skills incluse

Voci per singola Skill (`skills.entries`)

Elenchi consentiti degli agenti (`agents`)

Workshop (`skills.workshop`)

Radici delle skill con collegamenti simbolici

Skill in sandbox e variabili di ambiente

Promemoria sull’ordine di caricamento

Contenuti correlati