Vai al contenuto principale
La maggior parte della configurazione delle skill 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: "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 },
    },
  },
}
Per la generazione immagini integrata, usa agents.defaults.imageGenerationModel più lo strumento core image_generate invece di skills.entries. Le voci delle skill sono solo per flussi di lavoro di skill personalizzate o di terze parti.

​
Caricamento (skills.load)

​
skills.load.extraDirs
string[]
Directory di skill aggiuntive da analizzare, con la precedenza più bassa (dopo le skill in bundle e dei Plugin). I percorsi vengono espansi con supporto per ~.
​
skills.load.allowSymlinkTargets
string[]
Directory di destinazione reali attendibili in cui possono risolversi le cartelle di skill con symlink, anche quando il symlink si trova fuori dalla radice configurata. Usalo per layout intenzionali di repository affiancati, come <workspace>/skills/manager -> ~/Projects/manager/skills. Mantieni questo elenco ristretto: non puntare a radici ampie come ~ o ~/Projects.
​
skills.load.watch
boolean
predefinito:"true"
Monitora le cartelle di skill e aggiorna lo snapshot delle skill quando i file SKILL.md cambiano. Copre i file annidati sotto le radici di skill raggruppate.
​
skills.load.watchDebounceMs
number
predefinito:"250"
Finestra di debounce per gli eventi del watcher delle skill in millisecondi.

​
Installazione (skills.install)

​
skills.install.preferBrew
boolean
predefinito:"true"
Preferisce gli installer Homebrew quando brew è disponibile.
​
skills.install.nodeManager
"npm" | "pnpm" | "yarn" | "bun"
predefinito:"\"npm\""
Preferenza del gestore pacchetti Node per le installazioni di skill. Questo influisce solo sulle installazioni di skill: il runtime Gateway deve comunque usare Node (Bun non è consigliato per WhatsApp/Telegram). Usa openclaw setup --node-manager per npm, pnpm o bun; imposta "yarn" manualmente per installazioni di skill basate su Yarn.
​
skills.install.allowUploadedArchives
boolean
predefinito:"false"
Consente ai client Gateway operator.admin attendibili di installare archivi zip privati predisposti tramite skills.upload.*. Le normali installazioni ClawHub non richiedono questa impostazione.

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

Usa security.installPolicy quando gli operatori hanno bisogno di un comando locale attendibile per approvare o bloccare installazioni di skill e Plugin con criteri specifici dell’host. Il criterio viene eseguito dopo che OpenClaw ha predisposto il materiale sorgente e prima che l’installazione o l’aggiornamento continui. Si applica alle skill ClawHub, alle skill caricate, alle skill Git/locali, agli installer delle dipendenze delle skill e alle sorgenti di installazione/aggiornamento dei Plugin. 
{
  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.enabled
boolean
predefinito:"false"
Abilita il criterio di installazione di proprietà dell’operatore. Quando è abilitato senza un comando exec valido, le installazioni falliscono in modo chiuso.
​
security.installPolicy.targets
("skill" | "plugin")[]
Filtro di destinazione facoltativo. Quando viene omesso, il criterio si applica a ogni destinazione supportata in modo che le nuove installazioni non falliscano inaspettatamente in modo aperto.
​
security.installPolicy.exec.command
string
Percorso assoluto dell’eseguibile del criterio attendibile. OpenClaw lo esegue senza una shell e convalida il percorso prima dell’uso.
​
security.installPolicy.exec.args
string[]
Argomenti statici passati dopo command.
​
security.installPolicy.exec.timeoutMs
number
predefinito:"10000"
Tempo massimo di esecuzione effettivo per una decisione del criterio.
​
security.installPolicy.exec.noOutputTimeoutMs
number
predefinito:"timeoutMs"
Tempo massimo senza output su stdout o stderr prima che il criterio fallisca in modo chiuso.
​
security.installPolicy.exec.maxOutputBytes
number
predefinito:"1048576"
Numero massimo di byte combinati di stdout e stderr accettati dal processo del criterio.
​
security.installPolicy.exec.env
Record<string, string>
Variabili d’ambiente letterali fornite al processo del criterio.
​
security.installPolicy.exec.passEnv
string[]
Nomi di variabili d’ambiente copiati dal processo OpenClaw nel processo del criterio. Vengono passate solo le variabili nominate.
​
security.installPolicy.exec.trustedDirs
string[]
Allowlist facoltativa di directory che possono contenere l’eseguibile del criterio.
​
security.installPolicy.exec.allowInsecurePath
boolean
predefinito:"false"
Aggira i controlli di proprietà e permessi del percorso del comando. Usalo solo quando il percorso è protetto da un altro meccanismo.
​
security.installPolicy.exec.allowSymlinkCommand
boolean
predefinito:"false"
Consente al percorso del comando configurato di essere un symlink. La destinazione risolta deve comunque soddisfare gli altri controlli del percorso. Gli argomenti degli script interprete devono essere file regolari diretti, non symlink.
Il criterio riceve un oggetto JSON su stdin con protocolVersion: 1, openclawVersion, targetType, targetName, sourcePath, sourcePathKind, source strutturato facoltativo, origin strutturato e request. Deve scrivere un oggetto JSON su stdout: { "protocolVersion": 1, "decision": "allow" } oppure { "protocolVersion": 1, "decision": "block", "reason": "..." }. Uscita diversa da zero, timeout, JSON malformato, campi mancanti o versioni di protocollo non supportate falliscono in modo chiuso. OpenClaw non esegue il criterio di installazione durante il normale avvio del Gateway. Installazioni e aggiornamenti falliscono in modo chiuso quando il criterio è abilitato ma non disponibile. openclaw doctor esegue la convalida statica, e openclaw doctor --deep esegue una prova sintetica di installazione contro il comando configurato. Gli aggiornamenti in blocco applicano il criterio per destinazione: un aggiornamento bloccato di skill o Plugin fallisce per quella destinazione senza disabilitare il criterio o saltare le destinazioni successive nel batch. 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 di criterio minimo: 
#!/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" }));
});

​
Allowlist delle skill in bundle

​
skills.allowBundled
string[]
Allowlist facoltativa solo per le skill in bundle. Quando è impostata, sono idonee solo le skill in bundle nell’elenco. Le skill gestite, a livello di agente e del workspace non sono interessate.

​
Voci per skill (skills.entries)

Le chiavi sotto entries corrispondono per impostazione predefinita al name della skill. Se una skill definisce metadata.openclaw.skillKey, usa invece quella chiave. Metti tra virgolette i nomi con trattino (JSON5 consente chiavi tra virgolette).
​
skills.entries.<key>.enabled
boolean
false disabilita la skill anche quando è in bundle o installata. La skill in bundle coding-agent è opt-in: impostala su true e assicurati che uno tra claude, codex, opencode o un’altra CLI supportata sia installato e autenticato.
​
skills.entries.<key>.apiKey
string | { source, provider, id }
Campo di comodità per le skill che dichiarano metadata.openclaw.primaryEnv. Supporta una stringa in testo normale o una SecretRef: { source: "env", provider: "default", id: "VAR_NAME" }.
​
skills.entries.<key>.env
Record<string, string>
Variabili d’ambiente iniettate per l’esecuzione dell’agente. Vengono iniettate solo quando la variabile non è già impostata nel processo.
​
skills.entries.<key>.config
object
Contenitore facoltativo per campi di configurazione personalizzati per skill.

​
Allowlist degli agenti (agents)

Usa la configurazione dell’agente quando vuoi le stesse radici di skill di macchina/workspace ma un insieme di skill visibili diverso per 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
    ],
  },
}
​
agents.defaults.skills
string[]
Allowlist di base condivisa ereditata dagli agenti che omettono agents.list[].skills. Omettila del tutto per lasciare le skill senza restrizioni per impostazione predefinita.
​
agents.list[].skills
string[]
Insieme finale esplicito di skill per quell’agente. Gli elenchi espliciti sostituiscono i default ereditati: non vengono uniti. Imposta su [] per non esporre alcuna skill a quell’agente.
Le allowlist delle skill degli agenti sono un filtro di visibilità e caricamento per la discovery delle skill di OpenClaw, i prompt, la discovery dei comandi slash, la sincronizzazione sandbox e gli snapshot delle skill. Non sono un confine di autorizzazione al momento della shell. Se un agente può eseguire exec sull’host, quella shell può comunque eseguire client esterni o leggere file dell’host visibili all’utente di esecuzione, inclusi registri di client MCP come ~/.openclaw/skills/config/mcporter.json. Per l’isolamento MCP per agente, combina le allowlist delle skill con l’isolamento sandbox/utente OS, nega o consenti in modo strettamente limitato exec sull’host e preferisci credenziali per agente sul server MCP.

​
Workshop (skills.workshop)

​
skills.workshop.autonomous.enabled
boolean
predefinito:"false"
Quando è true, gli agenti possono creare proposte in sospeso da segnali durevoli della conversazione dopo turni riusciti. La creazione di skill richiesta dall’utente passa sempre tramite Skill Workshop indipendentemente da questa impostazione.
​
skills.workshop.approvalPolicy
"pending" | "auto"
predefinito:"\"pending\""
pending richiede l’approvazione dell’operatore prima di applicare, rifiutare o mettere in quarantena su iniziativa dell’agente. auto consente queste azioni senza approvazione.
​
skills.workshop.allowSymlinkTargetWrites
boolean
predefinito:"false"
Consenti a Skill Workshop di applicare scritture tramite symlink Skills dell’area di lavoro il cui target reale è già attendibile per skills.load.allowSymlinkTargets. Mantieni questa opzione disabilitata a meno che l’applicazione delle proposte generate debba modificare quella radice Skills condivisa.
​
skills.workshop.maxPending
number
predefinito:"50"
Numero massimo di proposte in sospeso e in quarantena conservate per area di lavoro.
​
skills.workshop.maxSkillBytes
number
predefinito:"40000"
Dimensione massima del corpo della proposta in byte. Le descrizioni delle proposte hanno un limite rigido di 160 byte perché compaiono nell’output di individuazione ed elenco.
Per impostazione predefinita, le radici Skills di area di lavoro, agente di progetto, directory extra e incluse sono confini di contenimento. Una cartella Skills con symlink sotto <workspace>/skills che si risolve fuori dalla radice viene ignorata con un messaggio di log. Per consentire un layout con symlink intenzionale, dichiara il target attendibile: 
{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}
Con questa configurazione, <workspace>/skills/manager -> ~/Projects/manager/skills viene accettato dopo la risoluzione realpath. extraDirs scansiona direttamente il repository adiacente; allowSymlinkTargets conserva il percorso con symlink per i layout esistenti. Per impostazione predefinita, l’applicazione di Skill Workshop non scrive attraverso quei symlink. Per consentire a Workshop di modificare Skills sotto target symlink già attendibili, abilitalo separatamente: 
{
  skills: {
    load: {
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
    workshop: {
      allowSymlinkTargetWrites: true,
    },
  },
}
Le directory gestite ~/.openclaw/skills e personali ~/.agents/skills accettano già symlink a directory Skills (il contenimento SKILL.md per singola Skill continua ad applicarsi).

​
Skills in sandbox e variabili env

skills.entries.<skill>.env e apiKey si applicano solo alle esecuzioni host. All’interno di una sandbox non hanno effetto: una Skill che dipende da GEMINI_API_KEY non riuscirà con apiKey not configured a meno che alla sandbox non venga fornita separatamente la variabile.
Passa i segreti in una sandbox Docker con: 
{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          env: { GEMINI_API_KEY: "your-key-here" },
        },
      },
    },
  },
}
Gli utenti con accesso al daemon Docker possono ispezionare i valori di sandbox.docker.env tramite i metadati Docker. Usa un file segreto montato, un’immagine personalizzata o un altro percorso di consegna quando questa esposizione non è accettabile.

​
Promemoria sull’ordine di caricamento

workspace/skills      (più alto)
workspace/.agents/skills
~/.agents/skills
~/.openclaw/skills
Skills incluse
skills.load.extraDirs (più basso)
Le modifiche a Skills e configurazione hanno effetto nella nuova sessione successiva quando il watcher è abilitato, oppure nel turno agente successivo quando il watcher rileva una modifica.

​
Correlati

Riferimento Skills

Cosa sono le Skills, ordine di caricamento, gating e formato SKILL.md.

Creare Skills

Creazione di Skills personalizzate per l’area di lavoro.

Skill Workshop

Coda di proposte per Skills redatte dall’agente.

Comandi slash

Catalogo nativo dei comandi slash e direttive chat.