Навыки (OpenClaw)

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

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

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

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

Если имя навыка конфликтует, приоритет:

<workspace>/skills (высший) → ~/.openclaw/skills → встроенные навыки (низший)

Кроме того, вы можете настроить дополнительные папки навыков (самый низкий приоритет) через skills.load.extraDirs в ~/.openclaw/openclaw.json.

Навыки на агента против общих навыков

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

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

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

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

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

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

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

Общие потоки:

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

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

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

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

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

SKILL.md должен включать как минимум:

---
name: nano-banana-pro
description: Генерировать или редактировать изображения через Gemini 3 Pro Image
---

Примечания:

  • Мы следуем спецификации AgentSkills для макета/намерения.
  • Парсер, используемый встроенным агентом, поддерживает только однострочные ключи frontmatter.
  • metadata должна быть однострочным JSON-объектом.
  • Используйте {baseDir} в инструкциях для ссылки на путь к папке навыка.
  • Опциональные ключи frontmatter:

    • homepage — URL, отображаемый как "Website" в UI навыков macOS (также поддерживается через metadata.openclaw.homepage).

    • user-invocable — true|false (по умолчанию: true). Когда true, навык доступен как пользовательская команда slash.

    • disable-model-invocation — true|false (по умолчанию: false). Когда true, навык исключается из запроса модели (по-прежнему доступен через вызов пользователем).

    • command-dispatch — tool (опционально). Когда установлено в tool, команда slash обходит модель и отправляется напрямую в инструмент.

    • 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: Генерировать или редактировать изображения через 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, отображаемый как "Website" в 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: Использовать Gemini CLI для помощи в кодировании и поиска Google.
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: "GEMINI_KEY_HERE",
        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.
  • 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 не установлена в deny), OpenClaw может рассматривать навыки только для macOS как подходящие, когда требуемые двоичные файлы присутствуют на этом узле. Агент должен выполнять эти навыки через инструмент nodes (обычно nodes.run).

Это полагается на узел, сообщающий о своей поддержке команд и на проверку bin через 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;, &lt; и т.д.), увеличивая длину.
  • Количество токенов варьируется в зависимости от токенизатора модели. Приблизительная оценка в стиле OpenAI — ~4 символа/токен, поэтому 97 символов ≈ 24 токена на навык плюс длины ваших фактических полей.

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

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

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

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

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

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

← Назад к документации