Configuración de habilidades

La mayor parte de la configuración de habilidades reside en skills en ~/.openclaw/openclaw.json. La visibilidad específica del agente reside en agents.defaults.skills y 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 },
      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 },
    },
  },
}

Cargando (`skills.load`)

Directorios de habilidades adicionales para escanear, con la menor prioridad (después de las habilidades agrupadas y de los complementos). Las rutas se expanden con compatibilidad con `~`. Directorios de destino reales de confianza a los que las carpetas de habilidades con enlaces simbólicos pueden resolver, incluso cuando el enlace simbólico reside fuera de la raíz configurada. Use esto para diseños intencionales de repositorios hermanos como `/skills/manager -> ~/Projects/manager/skills`. Mantenga esta lista reducida — no apunte a raíces amplias como `~` o `~/Projects`. Vigila las carpetas de habilidades y actualiza la instantánea de habilidades cuando los archivos `SKILL.md` cambian. Cubre archivos anidados bajo raíces de habilidades agrupadas. Ventana de rebote para los eventos del observador de habilidades en milisegundos.

Instalación (`skills.install`)

Prefiere los instaladores de Homebrew cuando `brew` esté disponible. Preferencia del administrador de paquetes de Node para la instalación de habilidades. Esto solo afecta las instalaciones de habilidades — el tiempo de ejecución de Gateway aún debería usar Node (no se recomienda Bun para WhatsApp/Telegram). Use `openclaw setup --node-manager` para npm, pnpm o bun; configure `"yarn"` manualmente para instalaciones de habilidades respaldadas por Yarn. Permitir que los clientes de Gateway `operator.admin` de confianza instalen archivos zip privados preparados a través de `skills.upload.*`. Las instalaciones normales de ClawHub no necesitan esta configuración.

Lista de permitidos de habilidades agrupadas

Lista de permitidos opcional solo para habilidades **agrupadas**. Cuando se establece, solo las habilidades agrupadas de la lista son elegibles. Las habilidades gestionadas, de nivel de agente y del espacio de trabajo no se ven afectadas.

Entradas por habilidad (`skills.entries`)

Las claves bajo entries coinciden con el name de la habilidad de manera predeterminada. Si una habilidad define metadata.openclaw.skillKey, use esa clave en su lugar. Ponga entre comillas los nombres con guiones (JSON5 permite claves entre comillas).

`false` deshabilita la habilidad incluso cuando está agrupada o instalada. La habilidad agrupada `coding-agent` es opcional — configúrela en `true` y asegúrese de que uno de `claude`, `codex`, `opencode` u otra CLI compatible esté instalada y autenticada. Campo de conveniencia para habilidades que declaran `metadata.openclaw.primaryEnv`. Soporta una cadena de texto sin formato o una SecretRef: `{ source: "env", provider: "default", id: "VAR_NAME" }`. Variables de entorno inyectadas para la ejecución del agente. Solo se inyectan cuando la variable aún no está establecida en el proceso. Bolsa opcional para campos de configuración personalizados por habilidad.

Listas de permitidos de agentes (`agents`)

Use la configuración del agente cuando desee las mismas raíces de habilidad de máquina/espacio de trabajo pero un conjunto de habilidades visible diferente para cada 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
    ],
  },
}

Lista de permitidos base compartida heredada por los agentes que omiten `agents.list[].skills`. Omita por completo para dejar las habilidades sin restricciones de forma predeterminada. Conjunto final de habilidades explícito para ese agente. Las listas explícitas **reemplazan** los valores predeterminados heredados; no se fusionan. Establézcalo en `[]` para no exponer habilidades para ese agente.

Taller (`skills.workshop`)

Cuando es `true`, los agentes pueden crear propuestas pendientes a partir de señales de conversación duraderas después de turnos exitosos. La creación de habilidades solicitada por el usuario siempre pasa por el Taller de habilidades independientemente de esta configuración. `pending` requiere la aprobación del operador antes de aplicar, rechazar o poner en cuarentena iniciado por el agente. `auto` permite esas acciones sin aprobación. Máximo de propuestas pendientes y en cuarentena retenidas por espacio de trabajo. Tamaño máximo del cuerpo de la propuesta en bytes. Las descripciones de las propuestas tienen un límite estricto de 160 bytes porque aparecen en los resultados de descubrimiento y listado.

Raíces de habilidades con enlaces simbólicos

De forma predeterminada, las raíces de habilidades del espacio de trabajo, agente de proyecto, directorio adicional y agrupadas son límites de contención. Se omite una carpeta de habilidad con enlaces simbólicos bajo <workspace>/skills que se resuelve fuera de la raíz con un mensaje de registro.

Para permitir un diseño intencional de enlaces simbólicos, declare el objetivo de confianza:

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

Con esta configuración, <workspace>/skills/manager -> ~/Projects/manager/skills se acepta después de la resolución de realpath. extraDirs escanea directamente el repositorio hermano; allowSymlinkTargets conserva la ruta del enlace simbólico para diseños existentes.

Los directorios gestionados ~/.openclaw/skills y personales ~/.agents/skills ya aceptan enlaces simbólicos a directorios de habilidades (el confinamiento SKILL.md por habilidad todavía se aplica).

Habilidades en sandbox y variables de entorno

Pase secretos a un sandbox de Docker con:

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

Recordatorio del orden de carga

workspace/skills      (highest)
workspace/.agents/skills
~/.agents/skills
~/.openclaw/skills
bundled skills
skills.load.extraDirs (lowest)

Los cambios en las habilidades y la configuración entran en vigor en la próxima nueva sesión cuando el observador está habilitado, o en el próximo turno del agente cuando el observador detecta un cambio.

Relacionado

Referencia de habilidades

Qué son las habilidades, el orden de carga, la regulación y el formato SKILL.md.

Creación de habilidades

Creación de habilidades personalizadas para el espacio de trabajo.

Taller de habilidades

Cola de propuestas para habilidades redactadas por el agente.

Comandos de barra

Catálogo nativo de comandos de barra y directivas de chat.