Configuración de skills

Toda la configuración relacionada con skills se encuentra en skills dentro de ~/.openclaw/openclaw.json.

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun (el runtime del Gateway sigue siendo Node; bun no recomendado)
    },
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // o string en texto plano
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

Campos

• allowBundled: lista de permitidos opcional solo para skills incluidos de fábrica. Cuando se configura, solo los skills incluidos en la lista son elegibles (los skills gestionados/de workspace no se ven afectados).
• load.extraDirs: directorios adicionales de skills para escanear (prioridad más baja).
• load.watch: observa las carpetas de skills y refresca la instantánea de skills (por defecto: true).
• load.watchDebounceMs: debounce para eventos del watcher de skills en milisegundos (por defecto: 250).
• install.preferBrew: preferir instaladores brew cuando estén disponibles (por defecto: true).
• install.nodeManager: preferencia de instalador de node (npm | pnpm | yarn | bun, por defecto: npm). Esto solo afecta las instalaciones de skills; el runtime del Gateway debe seguir siendo Node (Bun no recomendado para WhatsApp/Telegram).
• entries.<skillKey>: sobreescrituras por skill.

Campos por skill:

• enabled: ponlo en false para desactivar un skill aunque esté incluido/instalado.
• env: variables de entorno inyectadas para la ejecución del agente (solo si no están ya configuradas).
• apiKey: conveniencia opcional para skills que declaran una variable de entorno primaria. Admite string en texto plano u objeto SecretRef ({ source, provider, id }).

Notas

• Las claves bajo entries corresponden al nombre del skill por defecto. Si un skill define metadata.openclaw.skillKey, usa esa clave en su lugar.
• Los cambios en skills se aplican en el siguiente turno del agente cuando el watcher está habilitado.

Skills en sandbox + variables de entorno

Cuando una sesión está en sandbox, los procesos de skills se ejecutan dentro de Docker. El sandbox no hereda el process.env del host.

Usa una de estas opciones:

• agents.defaults.sandbox.docker.env (o por agente agents.list[].sandbox.docker.env)
• incluir las variables de entorno en tu imagen de sandbox personalizada

Las variables env globales y skills.entries.<skill>.env/apiKey aplican solo a ejecuciones en el host.