Навыки

Навыки

OpenClaw использует папки навыков, совместимые с AgentSkills, чтобы научить агента пользоваться инструментами. Каждый навык — это директория, содержащая файл SKILL.md с YAML-фронтметтером и инструкциями. OpenClaw загружает встроенные навыки плюс опциональные локальные переопределения и фильтрует их во время загрузки на основе окружения, конфигурации и наличия бинарных файлов.

Расположение и приоритет

Навыки загружаются из трёх мест:

  1. Встроенные навыки: поставляются с установкой (npm-пакет или OpenClaw.app)
  2. Управляемые/локальные навыки: ~/.openclaw/skills
  3. Рабочие навыки: <workspace>/skills

Если имена навыков конфликтуют, приоритет следующий: <workspace>/skills (наивысший) → ~/.openclaw/skills → встроенные навыки (наименьший) Дополнительно вы можете настроить дополнительные папки с навыками (наименьший приоритет) через skills.load.extraDirs в ~/.openclaw/openclaw.json.

Навыки на агента vs общие навыки

В настройках с несколькими агентами у каждого агента есть своё рабочее пространство. Это означает:

  • Навыки на агента находятся в <workspace>/skills только для этого агента.
  • Общие навыки находятся в ~/.openclaw/skills (управляемые/локальные) и видны всем агентам на одной машине.
  • Общие папки также можно добавить через skills.load.extraDirs (наименьший приоритет), если вы хотите использовать общий пакет навыков для нескольких агентов.

Если одно и то же имя навыка существует в нескольких местах, применяется обычный приоритет: рабочее пространство побеждает, затем управляемые/локальные, затем встроенные.

Плагины + навыки

Плагины могут поставлять собственные навыки, перечисляя директории skills в openclaw.plugin.json (пути относительно корня плагина). Навыки плагина загружаются, когда плагин включён, и участвуют в обычных правилах приоритета навыков. Вы можете ограничить их доступность через metadata.openclaw.requires.config в конфигурационной записи плагина. См. Плагины для обнаружения/настройки и Инструменты для инструментов, которым эти навыки обучают.

ClawHub (установка + синхронизация)

ClawHub — это публичный реестр навыков для OpenClaw. Просматривайте по адресу https://clawhub.com. Используйте его для обнаружения, установки, обновления и резервного копирования навыков. Полное руководство: ClawHub. Типичные сценарии:

  • Установить навык в ваше рабочее пространство:
    • clawhub install <skill-slug>
  • Обновить все установленные навыки:
    • clawhub update --all
  • Синхронизировать (сканировать + публиковать обновления):
    • clawhub sync --all

По умолчанию clawhub устанавливает в ./skills под вашей текущей рабочей директорией (или возвращается к настроенному рабочему пространству OpenClaw). OpenClaw подхватывает это как <workspace>/skills в следующей сессии.

Примечания по безопасности

  • Относитесь к сторонним навыкам как к ненадёжному коду. Читайте их перед включением.
  • Предпочитайте запуск в песочнице для ненадёжных входных данных и рискованных инструментов. См. Песочница.
  • Обнаружение навыков в рабочем пространстве и дополнительных директориях принимает только корни навыков и файлы SKILL.md, чей разрешённый реальный путь остаётся внутри настроенного корня.
  • skills.entries.*.env и skills.entries.*.apiKey внедряют секреты в хост-процесс для хода этого агента (не в песочницу). Держите секреты подальше от промптов и логов.
  • Для более широкой модели угроз и чек-листов см. Безопасность.

Формат (AgentSkills + Pi-совместимый)

SKILL.md должен содержать как минимум:

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
---

Примечания:

  • Мы следуем спецификации AgentSkills для структуры/назначения.
  • Парсер, используемый встроенным агентом, поддерживает только однострочные ключи фронтметтера.
  • metadata должен быть однострочным JSON-объектом.
  • Используйте {baseDir} в инструкциях для ссылки на путь к папке навыка.
  • Опциональные ключи фронтметтера:
    • homepage — URL, отображаемый как «Веб-сайт» в UI навыков macOS (также поддерживается через metadata.openclaw.homepage).
    • user-invocable — true|false (по умолчанию: true). Если true, навык доступен как пользовательская слеш-команда.
    • disable-model-invocation — true|false (по умолчанию: false). Если true, навык исключается из промпта модели (остаётся доступным через вызов пользователем).
    • command-dispatch — tool (опционально). Если установлено tool, слеш-команда обходит модель и отправляется напрямую инструменту.
    • command-tool — имя инструмента для вызова, когда установлено command-dispatch: tool.
    • command-arg-mode — raw (по умолчанию). Для отправки инструменту передаёт сырую строку аргументов (без разбора ядром). Инструмент вызывается с параметрами: { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }.

Ограничение (фильтры во время загрузки)

OpenClaw фильтрует навыки во время загрузки, используя metadata (однострочный JSON):

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

Поля под metadata.openclaw:

  • always: true — всегда включать навык (пропустить другие ограничения).
  • emoji — опциональный эмодзи, используемый UI навыков macOS.
  • homepage — опциональный URL, отображаемый как «Веб-сайт» в UI навыков macOS.
  • os — опциональный список платформ (darwin, linux, win32). Если задан, навык доступен только на этих ОС.
  • requires.bins — список; каждый должен существовать в PATH.
  • requires.anyBins — список; хотя бы один должен существовать в PATH.
  • requires.env — список; переменная окружения должна существовать или быть предоставлена в конфигурации.
  • requires.config — список путей в openclaw.json, которые должны быть истинными.
  • primaryEnv — имя переменной окружения, связанной с skills.entries.<name>.apiKey.
  • install — опциональный массив спецификаций установщика, используемых UI навыков macOS (brew/node/go/uv/download).

Примечание о песочнице:

  • requires.bins проверяется на хосте во время загрузки навыка.
  • Если агент запущен в песочнице, бинарный файл также должен существовать внутри контейнера. Установите его через agents.defaults.sandbox.docker.setupCommand (или пользовательский образ). setupCommand выполняется один раз после создания контейнера. Установка пакетов также требует исходящего сетевого доступа, доступной для записи корневой ФС и пользователя root в песочнице. Пример: навык summarize (skills/summarize/SKILL.md) нуждается в CLI summarize в контейнере песочницы для запуска там.

Пример установщика:

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "Install Gemini CLI (brew)",
            },
          ],
      },
  }
---

Примечания:

  • Если перечислено несколько установщиков, шлюз выбирает один предпочтительный вариант (brew, если доступен, иначе node).
  • Если все установщики — download, OpenClaw перечисляет каждую запись, чтобы вы могли видеть доступные артефакты.
  • Спецификации установщика могут включать os: ["darwin"|"linux"|"win32"] для фильтрации вариантов по платформе.
  • Установки Node учитывают skills.install.nodeManager в openclaw.json (по умолчанию: npm; варианты: npm/pnpm/yarn/bun). Это влияет только на установку навыков; среда выполнения Шлюза всё равно должна быть Node (Bun не рекомендуется для WhatsApp/Telegram).
  • Установки Go: если go отсутствует и brew доступен, шлюз сначала устанавливает Go через Homebrew и устанавливает GOBIN в bin Homebrew, когда это возможно.
  • Установки Download: url (обязательно), archive (tar.gz | tar.bz2 | zip), extract (по умолчанию: автоматически при обнаружении архива), stripComponents, targetDir (по умолчанию: ~/.openclaw/tools/<skillKey>).

Если metadata.openclaw отсутствует, навык всегда доступен (если не отключён в конфигурации или не заблокирован skills.allowBundled для встроенных навыков).

Переопределения конфигурации (~/.openclaw/openclaw.json)

Встроенные/управляемые навыки можно включать/выключать и снабжать значениями окружения:

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

Примечание: если имя навыка содержит дефисы, заключайте ключ в кавычки (JSON5 позволяет ключи в кавычках). Ключи конфигурации по умолчанию соответствуют имени навыка. Если навык определяет metadata.openclaw.skillKey, используйте этот ключ под skills.entries. Правила:

  • enabled: false отключает навык, даже если он встроен/установлен.
  • env: внедряется только если переменная ещё не установлена в процессе.
  • apiKey: удобство для навыков, которые объявляют metadata.openclaw.primaryEnv. Поддерживает обычную строку или объект SecretRef ({ source, provider, id }).
  • config: опциональный набор для пользовательских полей на навык; пользовательские ключи должны находиться здесь.
  • allowBundled: опциональный белый список только для встроенных навыков. Если задан, доступны только встроенные навыки из списка (на управляемые/рабочие навыки не влияет).

Внедрение окружения (за запуск агента)

Когда запускается ход агента, OpenClaw:

  1. Читает метаданные навыков.
  2. Применяет любые skills.entries.<key>.env или skills.entries.<key>.apiKey к process.env.
  3. Строит системный промпт с доступными навыками.
  4. Восстанавливает исходное окружение после завершения хода.

Это ограничено ходом агента, а не глобальной средой оболочки.

Снимок сессии (производительность)

OpenClaw делает снимок доступных навыков при запуске сессии и повторно использует этот список для последующих ходов в той же сессии. Изменения в навыках или конфигурации вступают в силу при следующей новой сессии. Навыки также могут обновляться в середине сессии, когда включён наблюдатель за навыками или когда появляется новый доступный удалённый узел (см. ниже). Думайте об этом как о горячей перезагрузке: обновлённый список подхватывается на следующем ходе агента.

Удалённые узлы macOS (Linux-шлюз)

Если Шлюз работает на Linux, но узел macOS подключён с разрешённым system.run (безопасность Exec approvals не установлена в deny), OpenClaw может считать навыки, доступные только для macOS, доступными, когда требуемые бинарные файлы присутствуют на этом узле. Агент должен выполнять эти навыки через инструмент nodes (обычно nodes.run). Это зависит от того, что узел сообщает о поддержке команд, и от проверки бинарного файла через system.run. Если узел macOS позже отключается, навыки остаются видимыми; вызовы могут завершаться неудачей, пока узел не переподключится.

Наблюдатель за навыками (автообновление)

По умолчанию OpenClaw наблюдает за папками навыков и обновляет снимок навыков при изменении файлов SKILL.md. Настройте это в skills.load:

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

Влияние на токены (список навыков)

Когда навыки доступны, OpenClaw внедряет компактный XML-список доступных навыков в системный промпт (через formatSkillsForPrompt в pi-coding-agent). Стоимость детерминирована:

  • Базовые накладные расходы (только когда ≥1 навык): 195 символов.
  • На навык: 97 символов + длина экранированных XML значений <name>, <description> и <location>.

Формула (символы):

total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))

Примечания:

  • Экранирование XML преобразует & < > " ' в сущности (&amp;, < и т.д.), увеличивая длину.
  • Количество токенов зависит от токенизатора модели. Грубая оценка в стиле OpenAI — ~4 символа/токен, поэтому 97 символов ≈ 24 токена на навык плюс ваши фактические длины полей.

Жизненный цикл управляемых навыков

OpenClaw поставляет базовый набор навыков как встроенные навыки в составе установки (npm-пакет или OpenClaw.app). ~/.openclaw/skills существует для локальных переопределений (например, закрепления/исправления навыка без изменения встроенной копии). Рабочие навыки принадлежат пользователю и переопределяют оба при конфликте имён.

Справочник по конфигурации

См. Конфигурация навыков для полной схемы конфигурации.

Ищете больше навыков?

Просмотрите https://clawhub.com.

Слеш-командыКонфигурация навыков