CLI

Пакет CLI: clawhub, исполняемый файл: clawhub.

Установите его глобально с помощью npm или pnpm:

npm i -g clawhub# илиpnpm add -g clawhub

Затем проверьте установку:

clawhub --helpclawhub loginclawhub whoami

Глобальные флаги

• --workdir <dir>: рабочий каталог (по умолчанию: cwd; при наличии конфигурации используется рабочее пространство Clawdbot)
• --dir <dir>: каталог установки внутри рабочего каталога (по умолчанию: skills)
• --site <url>: базовый URL для входа через браузер (по умолчанию: https://clawhub.ai)
• --registry <url>: базовый URL API (по умолчанию: обнаруженный, иначе https://clawhub.ai)
• --no-input: отключить запросы подтверждения

Эквивалентные переменные среды:

• CLAWHUB_SITE (устаревшая: CLAWDHUB_SITE)
• CLAWHUB_REGISTRY (устаревшая: CLAWDHUB_REGISTRY)
• CLAWHUB_WORKDIR (устаревшая: CLAWDHUB_WORKDIR)

HTTP-прокси

В системах, находящихся за корпоративными прокси-серверами или в сетях с ограничениями, CLI учитывает стандартные переменные среды HTTP-прокси:

• HTTPS_PROXY / https_proxy
• HTTP_PROXY / http_proxy
• NO_PROXY / no_proxy

Если задана любая из этих переменных, CLI направляет исходящие запросы через указанный прокси-сервер. HTTPS_PROXY используется для HTTPS-запросов, HTTP_PROXY — для обычного HTTP. NO_PROXY / no_proxy учитывается для обхода прокси-сервера при обращении к указанным хостам или доменам.

Это необходимо в системах, где прямые исходящие подключения заблокированы (например, в контейнерах Docker, на VPS Hetzner с доступом в интернет только через прокси-сервер или за корпоративными межсетевыми экранами).

Пример:

export HTTPS_PROXY=http://proxy.example.com:3128export NO_PROXY=localhost,127.0.0.1clawhub search "my query"

Если переменные прокси-сервера не заданы, поведение не меняется (используются прямые подключения).

Файл конфигурации

Хранит токен API и кэшированный URL реестра.

• macOS: ~/Library/Application Support/clawhub/config.json
• Linux/XDG: $XDG_CONFIG_HOME/clawhub/config.json или ~/.config/clawhub/config.json
• Windows: %APPDATA%\\clawhub\\config.json
• Резервный устаревший путь: если clawhub/config.json ещё не существует, но существует clawdhub/config.json, CLI повторно использует устаревший путь
• переопределение: CLAWHUB_CONFIG_PATH (устаревшая: CLAWDHUB_CONFIG_PATH)

Команды

login / auth login

• По умолчанию: открывает в браузере <site>/cli/auth и завершает вход через обратный вызов на loopback-интерфейсе.
• Без графического интерфейса: clawhub login --token clh_...
• Интерактивный режим для удалённой системы или системы без графического интерфейса: clawhub login --device выводит код и ожидает, пока вы авторизуете его на <site>/cli/device.

whoami

• Проверяет сохранённый токен через /api/v1/whoami.

token

• Выводит сохранённый токен API в стандартный вывод.
• Полезно для передачи локального токена входа командам настройки секретов CI через конвейер.

star <skill> / unstar <skill>

• Добавляет навык в избранное или удаляет его оттуда.
• Вызывает POST /api/v1/stars/<slug> и DELETE /api/v1/stars/<slug>.
• --yes пропускает подтверждение.

search <query...>

• Вызывает /api/v1/search?q=....
• Вывод содержит идентификатор навыка, имя пользователя владельца, отображаемое имя и оценку релевантности.
• При поиске точные совпадения токенов идентификатора или имени имеют приоритет перед популярностью загрузок. Отдельный токен идентификатора, например map, соответствует personal-map точнее, чем подстроке внутри amap.
• Популярность оказывает небольшое предварительное влияние на ранжирование, но не гарантирует первое место.
• Если навык должен отображаться, но не отображается, войдите в систему и выполните clawhub inspect @owner/slug, чтобы проверить доступную владельцу диагностику модерации, прежде чем переименовывать метаданные.

explore

• Выводит список новейших навыков через /api/v1/skills?limit=...&sort=createdAt (сортировка по createdAt по убыванию).
• Флаги:
  • --limit <n> (1–200, по умолчанию: 25)
  • --sort newest|updated|rating|downloads|trending (по умолчанию: сначала новые). Устаревшие псевдонимы сортировки по установкам по-прежнему поддерживаются для совместимости.
  • --json (машиночитаемый вывод)
• Вывод: <slug> v<version> <age> <summary> (описание сокращается до 50 символов).

inspect @owner/slug

• Получает метаданные навыка и файлы версии без установки.
• --version <version>: проверить определённую версию (по умолчанию: последнюю).
• --tag <tag>: проверить версию с указанным тегом (например, latest).
• --versions: вывести историю версий (первую страницу).
• --limit <n>: максимальное количество версий в списке (1–200).
• --files: вывести список файлов выбранной версии.
• --file <path>: получить необработанное содержимое файла (только текстовые файлы; ограничение 200 КБ).
• --json: машиночитаемый вывод.

install @owner/slug

• Определяет последнюю версию для указанного владельца и навыка.
• Загружает ZIP-архив через /api/v1/download.
• Распаковывает в <workdir>/<dir>/<slug>.
• Отказывается перезаписывать закреплённые навыки; сначала выполните clawhub unpin <skill>.
• Записывает:
  • <workdir>/.clawhub/lock.json (устаревший: .clawdhub)
  • <skill>/.clawhub/origin.json (устаревший: .clawdhub)

uninstall <skill>

• Удаляет <workdir>/<dir>/<slug> и соответствующую запись из файла блокировки.
• Если выполнен вход, пытается отправить телеметрию, чтобы текущие счётчики установок можно было деактивировать.
• Интерактивный режим: запрашивает подтверждение.
• Неинтерактивный режим (--no-input): требует --yes.

list

• Читает <workdir>/.clawhub/lock.json (устаревший: .clawdhub).
• Показывает pinned рядом с навыками, замороженными с помощью clawhub pin, включая необязательную причину.

pin <skill>

• Помечает установленный навык как закреплённый в файле блокировки.
• --reason <text> сохраняет причину заморозки навыка.
• Закреплённые навыки пропускаются командой update --all, а прямой вызов update <skill> для них отклоняется.
• Закреплённые навыки также отклоняют install --force, чтобы локальное содержимое нельзя было случайно заменить.

unpin <skill>

• Удаляет закрепление установленного навыка из файла блокировки, чтобы последующие обновления могли его изменять.

update [@owner/slug] / update --all

• Вычисляет цифровой отпечаток локальных файлов.
• Если цифровой отпечаток совпадает с известной версией: запрос не выводится.
• Если цифровой отпечаток не совпадает:
  • по умолчанию операция отклоняется
  • перезаписывает с помощью --force (или выводит запрос в интерактивном режиме)
• Закреплённые навыки никогда не обновляются командой --force.
• update <skill> немедленно завершается с ошибкой для закреплённых навыков и предлагает сначала выполнить clawhub unpin <skill>.
• update --all пропускает закреплённые идентификаторы и выводит сводку о том, какие навыки остались замороженными.

skill publish <path>

• Сравнивает цифровой отпечаток локального пакета с ClawHub и успешно завершает работу, если содержимое уже опубликовано.
• Для новых навыков по умолчанию используется 1.0.0; для изменённых навыков — следующая исправляющая версия.
• --version <version> явно выбирает версию и выполняет публикацию, даже если содержимое совпадает с существующей версией.
• --dry-run определяет результат публикации без загрузки; --json выводит машиночитаемый результат.
• --owner <handle> публикует от имени организации или пользователя, если субъект имеет доступ издателя.
• --migrate-owner при публикации новой версии переносит существующий навык в --owner. Требуется доступ администратора или владельца у обоих издателей.
• Поведение владельцев и проверки описано в docs/publishing.md.
• Публикация навыка означает, что он выпускается на ClawHub под лицензией MIT-0.
• Опубликованные навыки можно бесплатно использовать, изменять и распространять без указания авторства.
• ClawHub не поддерживает платные навыки или индивидуальные цены для навыков.
• Устаревший псевдоним: publish <path>.

clawhub skill publish ./my-skill --dry-runclawhub skill publish ./my-skillclawhub skill publish ./my-skill --version 2.0.0

GitHub Actions

Многократно используемый рабочий процесс ClawHub skill-publish.yml вызывает skill publish для одного skill_path или для каждой непосредственной папки навыка внутри root (по умолчанию: skills). Он пропускает неизменённые навыки и использует такое же автоматическое поведение для исправляющей версии.

Задайте dry_run: true, чтобы выполнить предварительный просмотр без токена. Для реальной публикации требуется секрет clawhub_token.

sync

• Сканирует текущий рабочий каталог, настроенный каталог навыков и все папки --root <dir> в поисках локальных папок навыков, содержащих SKILL.md или skill.md.
• Сравнивает цифровой отпечаток каждого локального навыка с ClawHub и публикует только новые или изменённые навыки.
• Новые навыки публикуются как 1.0.0; для изменённых навыков по умолчанию публикуется следующая исправляющая версия. Используйте --bump minor|major для пакетов обновлений, которым требуется более крупное изменение версии по semver.
• --dry-run показывает план публикации без загрузки; --json выводит машиночитаемый план.
• --all публикует каждый новый или изменённый навык без запроса подтверждения. Без --all в интерактивных терминалах можно выбрать навыки для публикации.
• --owner <handle> публикует от имени организации или пользователя, если субъект имеет доступ издателя.
• sync выполняет только одностороннюю публикацию. Он не устанавливает, не обновляет, не загружает и не отправляет телеметрию установок или загрузок.

clawhub sync --all --dry-runclawhub sync --allclawhub sync --root ./skills --owner openclaw --bump minor

scan --slug <slug>

• Требует clawhub login.
• Запускает ClawScan от ClawHub через POST /api/v1/skills/-/scan, затем опрашивает состояние, пока сканирование не завершится.
• Сканирования выполняются асинхронно и могут занять некоторое время. Пока сканирование находится в очереди, индикатор выполнения в терминале показывает его текущую приоритетную позицию и количество сканирований перед ним.
• Для сканирования опубликованных версий требуется владение или доступ к управлению издателем. Модераторы и администраторы могут использовать тот же серверный механизм через clawhub-admin.
• --update допустим только вместе с --slug; он записывает результаты успешно завершённого сканирования опубликованной версии обратно в выбранную версию.
• --output <file.zip> загружает полный архив отчёта с manifest.json, clawscan.json, skillspector.json, static-analysis.json, virustotal.json и README.md.
• --json выводит полный ответ опроса для автоматизации.
• Сканирование локальных путей больше не поддерживается. Загрузите новую версию, затем используйте scan download, чтобы получить сохранённые результаты сканирования отправленной версии.

clawhub scan --slug gifgrepclawhub scan --slug gifgrep --version 1.2.3clawhub scan --slug gifgrep --update --output report.zip

scan download <name>

• Требуется clawhub login.
• Скачивает сохранённый ZIP-архив отчёта о сканировании для отправленной версии Skills или плагина, включая версии, которые были заблокированы или скрыты проверками безопасности ClawHub.
• Для скачивания Skills используется слаг Skills, а по умолчанию — --kind skill.
• Для скачивания плагинов используется имя пакета и требуется --kind plugin.
• --version обязателен, чтобы авторы проверяли именно ту отправленную версию, которую заблокировал ClawHub.
• --output <file.zip> задаёт путь назначения.

clawhub scan download gifgrep --version 1.2.3clawhub scan download @scope/demo --version 2.0.0 --kind plugin --output report.zip

GitHub Actions

ClawHub предоставляет официальный переиспользуемый рабочий процесс по адресу /.github/workflows/skill-publish.yml для репозиториев Skills и репозиториев каталогов.

Типичная настройка каталога:

name: Skill Publish on:  pull_request:  workflow_dispatch: jobs:  dry-run:    if: github.event_name == 'pull_request'    uses: openclaw/clawhub/.github/workflows/skill-publish.yml@v1    with:      owner: nvidia      dry_run: true   publish:    if: github.event_name == 'workflow_dispatch'    uses: openclaw/clawhub/.github/workflows/skill-publish.yml@v1    with:      owner: nvidia      dry_run: false    secrets:      clawhub_token: ${{ secrets.CLAWHUB_TOKEN }}

Примечания:

• Для репозиториев каталогов значение root по умолчанию равно skills.
• Передайте skill_path: skills/review-helper, чтобы обработать одну папку Skills.
• owner соответствует флагу CLI --owner; не указывайте его, чтобы опубликовать от имени аутентифицированного пользователя.
• Для публикации Skills V1 используется clawhub_token; доверенная публикация через GitHub OIDC пока доступна только для пакетов.

delete <skill>

• Без --version выполняет обратимое удаление Skills (доступно владельцу, модератору или администратору).
• Вызывает DELETE /api/v1/skills/{slug}.
• При обратимом удалении владельцем слаг резервируется на 30 дней; команда выводит время окончания резервирования.
• --version <version> безвозвратно удаляет одну принадлежащую владельцу версию, которая не является последней, через закрытый при сбое маршрут для конкретной версии. Удалённые версии нельзя восстановить или опубликовать повторно. Опубликуйте замену перед удалением текущей последней версии. Сотрудники платформы не могут обойти проверку владения в этом процессе, предназначенном только для отдельных версий.
• --reason <text> записывает примечание модератора для обратимого удаления всей Skills и в журнал аудита.
• --note <text> — псевдоним для --reason.
• --yes пропускает подтверждение.

undelete <skill>

• Восстанавливает скрытую Skills (доступно владельцу, модератору или администратору).
• Восстановление удалённой версии не предусмотрено; безвозвратно удалённые версии восстановить нельзя.
• Вызывает POST /api/v1/skills/{slug}/undelete.
• --reason <text> записывает примечание модератора для Skills и в журнал аудита.
• --note <text> — псевдоним для --reason.
• --yes пропускает подтверждение.

hide <skill>

• Скрывает Skills (доступно владельцу, модератору или администратору).
• Псевдоним для delete.

unhide <skill>

• Снимает скрытие со Skills (доступно владельцу, модератору или администратору).
• Псевдоним для undelete.

skill rename <skill> <new-name>

• Переименовывает принадлежащую владельцу Skills и сохраняет предыдущий слаг как псевдоним перенаправления.
• Вызывает POST /api/v1/skills/{slug}/rename.
• --yes пропускает подтверждение.

skill merge <source> <target>

• Объединяет одну принадлежащую владельцу Skills с другой принадлежащей ему Skills.
• Исходный слаг перестаёт отображаться в общедоступном списке и становится псевдонимом перенаправления на целевой слаг.
• Вызывает POST /api/v1/skills/{sourceSlug}/merge.
• --yes пропускает подтверждение.

transfer

• Рабочий процесс передачи владения.
• При передаче на дескрипторы пользователей создаётся ожидающий запрос, который должен принять получатель.
• Передача на дескрипторы организаций или издателей применяется немедленно, только если у инициатора есть административный доступ как к текущему владельцу, так и к целевому издателю.
• Подкоманды:
  • transfer request <skill> <handle> [--message "..."] [--yes]
  • transfer list [--outgoing]
  • transfer accept <skill> [--yes]
  • transfer reject <skill> [--yes]
  • transfer cancel <skill> [--yes]
• Конечные точки:
  • POST /api/v1/skills/{slug}/transfer
  • POST /api/v1/skills/{slug}/transfer/accept
  • POST /api/v1/skills/{slug}/transfer/reject
  • POST /api/v1/skills/{slug}/transfer/cancel
  • GET /api/v1/transfers/incoming
  • GET /api/v1/transfers/outgoing

package explore [query...]

• Просматривает единый каталог пакетов или выполняет поиск в нём через GET /api/v1/packages и GET /api/v1/packages/search.
• Используйте эту команду для плагинов и других записей семейств пакетов; верхнеуровневый search остаётся интерфейсом поиска Skills.
• Флаги:
  • --family skill|code-plugin|bundle-plugin
  • --official
  • --executes-code
  • --target <target>, --os <os>, --arch <arch>, --libc <libc>
  • --requires-browser, --requires-desktop, --requires-native-deps
  • --requires-external-service, --external-service <name>
  • --binary <name>, --os-permission <name>
  • --artifact-kind legacy-zip|npm-pack
  • --npm-mirror
  • --limit <n> (1-100, по умолчанию: 25)
  • --json

Примеры:

clawhub package explore --family code-pluginclawhub package explore --family code-plugin --os darwin --requires-desktopclawhub package explore --family code-plugin --artifact-kind npm-packclawhub package explore --npm-mirrorclawhub package explore episodic-claw --family code-plugin

package inspect <name>

• Получает метаданные пакета без установки.
• Используйте эту команду для проверки метаданных плагина, совместимости, верификации, исходного кода, а также версий и файлов.
• --version <version>: проверить определённую версию (по умолчанию: последняя).
• --tag <tag>: проверить версию с заданным тегом (например, latest).
• --versions: вывести историю версий (первую страницу).
• --limit <n>: максимальное количество выводимых версий (1-100).
• --files: вывести файлы выбранной версии.
• --file <path>: получить необработанное содержимое файла (только текстовые файлы; ограничение 200KB).
• --json: машиночитаемый вывод.

package download <name>

• Разрешает версию пакета через GET /api/v1/packages/{name}/versions/{version}/artifact.
• Скачивает артефакт из downloadUrl средства разрешения.
• Проверяет SHA-256 ClawHub для всех артефактов.
• Для артефактов ClawPack npm-pack также проверяет целостность npm sha512, контрольную сумму npm и имя/версию package.json в tar-архиве.
• Устаревшие ZIP-версии скачиваются через устаревший маршрут ZIP.
• Флаги:
  • --version <version>: скачать определённую версию.
  • --tag <tag>: скачать версию с заданным тегом (по умолчанию: latest).
  • -o, --output <path>: выходной файл или каталог.
  • --force: перезаписать существующий выходной файл.
  • --json: машиночитаемый вывод.

Примеры:

clawhub package download @openclaw/example-plugin --tag latestclawhub package download @openclaw/example-plugin --version 1.2.3 -o artifacts/

package verify <file>

• Вычисляет SHA-256 ClawHub, целостность npm sha512 и контрольную сумму npm для локального артефакта.
• При использовании --package получает ожидаемые метаданные из ClawHub и сравнивает локальный файл с метаданными опубликованного артефакта.
• При использовании прямых флагов дайджеста выполняет проверку без сетевого запроса.
• Флаги:
  • --package <name>: имя пакета для получения ожидаемых метаданных артефакта.
  • --version <version> или --tag <tag>: ожидаемая версия пакета.
  • --sha256 <hex>: ожидаемый SHA-256 ClawHub.
  • --npm-integrity <sri>: ожидаемое значение целостности npm.
  • --npm-shasum <sha1>: ожидаемая контрольная сумма npm.
  • --json: машиночитаемый вывод.

Примеры:

clawhub package verify ./example-plugin-1.2.3.tgz --package @openclaw/example-plugin --version 1.2.3clawhub package verify ./example-plugin-1.2.3.tgz --sha256 <hex>

package validate <source>

• Запускает встроенный в CLI ClawHub Plugin Inspector для локальной папки пакета плагина.
• По умолчанию выполняет автономную статическую проверку без поиска или импорта локальной рабочей копии OpenClaw.
• Критические ошибки совместимости приводят к завершению с ненулевым кодом. Результаты, содержащие только предупреждения, выводятся, но команда завершается с нулевым кодом.
• Флаги:
  • --out <dir>: записать отчёты Plugin Inspector в этот каталог.
  • --openclaw <path>: выполнить проверку относительно явно указанной локальной рабочей копии OpenClaw.
  • --runtime: включить сбор данных среды выполнения; импортирует код плагина.
  • --allow-execute: разрешить сбор данных среды выполнения в изолированном рабочем пространстве.
  • --no-mock-sdk: отключить имитацию SDK OpenClaw во время сбора данных среды выполнения.
  • --json: машиночитаемый вывод.

Пример:

clawhub package validate ./example-plugin

Если при проверке обнаружена проблема с пакетом, манифестом, импортом SDK или артефактом, см. Исправления ошибок проверки плагинов, затем повторно выполните команду.

package delete <name>

• Без --version выполняет обратимое удаление пакета и всех выпусков.
• --version <version> безвозвратно удаляет один принадлежащий владельцу выпуск, который не является последним, через закрытый при сбое маршрут для конкретной версии. Удалённые версии нельзя восстановить или опубликовать повторно. Опубликуйте замену перед удалением текущей последней версии. Этот процесс для отдельной версии требует прав владельца пакета или администратора издателя организации; сотрудники платформы не могут обойти проверку владения пакетом.
• Для обратимого удаления всего пакета требуются права владельца пакета, владельца или администратора издателя организации, модератора платформы либо администратора платформы.
• Флаги:
  • --version <version>: безвозвратно удалить одну версию, которая не является последней.
  • --yes: пропустить подтверждение.
  • --json: машиночитаемый вывод.

Пример:

clawhub package delete @openclaw/example-plugin --yesclawhub package delete @openclaw/example-plugin --version 1.2.3 --yes

package undelete <name>

• Восстанавливает обратимо удалённый пакет и выпуски.
• Восстановление удалённой версии не предусмотрено; безвозвратно удалённые версии восстановить нельзя.
• Требуются права владельца пакета, владельца или администратора издателя организации, модератора платформы либо администратора платформы.
• Вызывает POST /api/v1/packages/{name}/undelete.
• Флаги:
  • --yes: пропустить подтверждение.
  • --json: машиночитаемый вывод.

Пример:

clawhub package undelete @openclaw/example-plugin --yes

package transfer <name>

• Передаёт пакет другому издателю.
• Требует административного доступа как к текущему владельцу пакета, так и к целевому издателю, если операция не выполняется администратором платформы.
• Имена пакетов с областью видимости должны передаваться владельцу соответствующей области.
• Вызывает POST /api/v1/packages/{name}/transfer.
• Флаги:
  • --to <owner>: идентификатор целевого издателя.
  • --reason <text>: необязательная причина для аудита.
  • --json: машиночитаемый вывод.

Пример:

clawhub package transfer @openclaw/example-plugin --to openclaw

package report

• Команда с аутентификацией для отправки модераторам жалобы на пакет.
• Вызывает POST /api/v1/packages/{name}/report.
• Жалобы относятся ко всему пакету, могут быть связаны с определённой версией и становятся доступными модераторам для рассмотрения.
• Сами по себе жалобы не скрывают пакеты автоматически и не блокируют скачивания.
• Флаги:
  • --version <version>: необязательная версия пакета, к которой относится жалоба.
  • --reason <text>: обязательная причина жалобы.
  • --json: машиночитаемый вывод.

Пример:

clawhub package report @openclaw/example-plugin --version 1.2.3 --reason "suspicious native payload"

package moderation-status

• Команда для владельца, позволяющая проверить видимость пакета при модерации.
• Вызывает GET /api/v1/packages/{name}/moderation.
• Показывает текущее состояние сканирования пакета, количество открытых жалоб, состояние ручной модерации последнего выпуска, состояние блокировки скачивания и причины модерации.
• Флаги:
  • --json: машиночитаемый вывод.

Пример:

clawhub package moderation-status @openclaw/example-plugin

package readiness <name>

• Проверяет, готов ли пакет к будущему использованию в OpenClaw.
• Вызывает GET /api/v1/packages/{name}/readiness.
• Сообщает о препятствиях, связанных с официальным статусом, доступностью ClawPack, дайджестом артефакта, происхождением исходного кода, совместимостью с OpenClaw, целевыми хостами, метаданными окружения и состоянием сканирования.
• Флаги:
  • --json: машиночитаемый вывод.

Пример:

clawhub package readiness @openclaw/example-plugin

package migration-status <name>

• Показывает предназначенное для операторов состояние миграции пакета, который может заменить встроенный плагин OpenClaw.
• Вызывает ту же вычисляемую конечную точку проверки готовности, что и package readiness, но выводит ориентированные на миграцию состояние, последнюю версию, статус официального пакета, проверки и препятствия.
• Флаги:
  • --json: машиночитаемый вывод.

Пример:

clawhub package migration-status @openclaw/example-plugin

publisher create <handle>

• Создаёт издателя-организацию, принадлежащего аутентифицированному пользователю.
• Идентификатор преобразуется в нижний регистр и может передаваться с @ или без него.
• Новые издатели-организации по умолчанию не считаются доверенными или официальными.
• Завершается ошибкой, если идентификатор уже используется существующим издателем, пользователем или зарезервированным маршрутом.

clawhub publisher create opik --display-name "Opik"

package publish <source>

• Публикует плагин с кодом или пакетный плагин через POST /api/v1/packages.
• <source> принимает:
  • Путь к локальной папке: ./my-plugin
  • Локальный tar-архив ClawPack, созданный npm pack: ./my-plugin-1.2.3.tgz
  • Репозиторий GitHub: owner/repo или owner/repo@ref
  • URL GitHub: https://github.com/owner/repo
• Метаданные автоматически определяются по package.json, openclaw.plugin.json и фактическим маркерам пакета OpenClaw, таким как .codex-plugin/plugin.json, .claude-plugin/plugin.json и .cursor-plugin/plugin.json.
• Источники .tgz обрабатываются как ClawPack. CLI загружает точные байты npm-пакета, а извлечённое содержимое package/ использует только для проверки и предварительного заполнения метаданных.
• Перед загрузкой папки плагинов с кодом упаковываются в npm-архив ClawPack, чтобы установки OpenClaw могли проверить точный артефакт. Для папок пакетных плагинов по-прежнему используется публикация извлечённых файлов.
• Для источников GitHub сведения о происхождении автоматически заполняются на основе репозитория, разрешённого коммита, ссылки и подпути.
• Для локальных папок сведения о происхождении автоматически определяются из локального репозитория Git, если удалённый origin указывает на GitHub.
• Внешние плагины с кодом должны явно объявлять openclaw.compat.pluginApi и openclaw.build.openclawVersion. Верхнеуровневое поле package.json.version не используется как резервное значение при проверке публикации.
• --dry-run показывает предварительный просмотр сформированных данных публикации без загрузки.
• --json формирует машиночитаемый вывод для CI.
• --owner <handle> публикует от имени пользователя или издателя-организации, если субъект имеет доступ издателя.
• Имена пакетов с областью видимости должны соответствовать выбранному владельцу. См. docs/publishing.md.
• Существующие флаги (--family, --name, --version, --source-repo, --source-commit, --source-ref, --source-path) по-прежнему работают как переопределения.
• Для приватных репозиториев GitHub требуется GITHUB_TOKEN.

clawhub package publish ./plugin.tgz --owner openclaw

Рекомендуемый локальный процесс

Сначала используйте --dry-run, чтобы проверить сформированные метаданные пакета и сведения о происхождении перед созданием реального выпуска:

npm packclawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin --dry-runclawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin

Процесс для локальной папки

При публикации плагинов с кодом из папки создаётся и загружается артефакт ClawPack из папки пакета:

clawhub package publish ./my-plugin --family code-plugin --dry-runclawhub package publish ./my-plugin --family code-plugin

Минимальный package.json для --family code-plugin

Внешним плагинам с кодом требуется небольшой объём метаданных OpenClaw в package.json. Этого минимального манифеста достаточно для успешной публикации:

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "compat": {      "pluginApi": ">=2026.3.24-beta.2"    },    "build": {      "openclawVersion": "2026.3.24-beta.2"    }  }}

Обязательные поля:

• openclaw.compat.pluginApi
• openclaw.build.openclawVersion

Примечания:

• package.json.version — это версия выпуска вашего пакета, но она не используется как резервное значение при проверке совместимости и сборки OpenClaw.
• openclaw.hostTargets и openclaw.environment — необязательные метаданные. ClawHub может отображать их при наличии, но для публикации они не требуются.
• openclaw.compat.minGatewayVersion и openclaw.build.pluginSdkVersion — необязательные дополнительные поля для публикации более подробных метаданных совместимости.
• Если вы используете старую версию CLI clawhub, обновите её перед публикацией, чтобы локальные предварительные проверки выполнялись до загрузки.
• Если проверка сообщает код исправления, см. Исправления ошибок проверки плагинов.

GitHub Actions

ClawHub также предоставляет официальный повторно используемый рабочий процесс /.github/workflows/package-publish.yml для репозиториев плагинов.

Типичная конфигурация вызывающего рабочего процесса:

name: Package Publish on:  pull_request:  workflow_dispatch:  push:    tags:      - "v*" jobs:  dry-run:    if: github.event_name == 'pull_request'    uses: openclaw/clawhub/.github/workflows/package-publish.yml@v0.12.0    with:      dry_run: true   publish:    if: github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/')    permissions:      contents: read      id-token: write    uses: openclaw/clawhub/.github/workflows/package-publish.yml@v0.12.0    with:      dry_run: false    secrets:      clawhub_token: ${{ secrets.CLAWHUB_TOKEN }}

Примечания:

• В повторно используемом рабочем процессе значение source по умолчанию соответствует вызывающему репозиторию.
• Для монорепозиториев передайте source_path, чтобы рабочий процесс публиковал папку пакета плагина, например source_path: extensions/codex.
• Закрепляйте повторно используемый рабочий процесс на стабильном теге или полном SHA коммита. Не запускайте публикацию выпуска из @main.
• pull_request должен использовать dry_run: true, чтобы CI не создавал лишних изменений.
• Фактические публикации должны быть ограничены доверенными событиями, такими как workflow_dispatch, или отправкой тегов.
• Доверенная публикация без секрета работает только в workflow_dispatch; для отправки тегов по-прежнему требуется clawhub_token.
• Сохраняйте доступность clawhub_token для первой публикации, недоверенных пакетов или аварийных публикаций.
• Рабочий процесс загружает результат JSON как артефакт и предоставляет его через выходные данные рабочего процесса.

package trusted-publisher get <name>

• Показывает конфигурацию доверенного издателя GitHub Actions для пакета.
• Используйте эту команду после настройки конфигурации, чтобы подтвердить репозиторий, имя файла рабочего процесса и необязательную привязку к окружению.
• Флаги:
  • --json: машиночитаемый вывод.

Пример:

clawhub package trusted-publisher get @openclaw/example-plugin

package trusted-publisher set <name>

• Добавляет или заменяет конфигурацию доверенного издателя GitHub Actions для существующего пакета.
• Сначала пакет необходимо создать посредством обычной ручной или аутентифицированной токеном команды clawhub package publish.
• После настройки конфигурации последующие поддерживаемые публикации через GitHub Actions могут использовать OIDC и доверенную публикацию без долгосрочного токена ClawHub.
• --repository <repo> должен быть owner/repo.
• --workflow-filename <file> должен совпадать с именем файла рабочего процесса в .github/workflows/.
• --environment <name> является необязательным. Если он настроен, окружение GitHub Actions в утверждении OIDC должно в точности совпадать.
• При выполнении этой команды ClawHub проверяет настроенный репозиторий GitHub. Публичные репозитории можно проверить по публичным метаданным GitHub. Для приватных репозиториев ClawHub должен иметь доступ GitHub к этому репозиторию, например через будущую установку приложения ClawHub GitHub App или другую авторизованную интеграцию GitHub.
• Флаги:
  • --repository <repo>: репозиторий GitHub, например openclaw/example-plugin.
  • --workflow-filename <file>: имя файла рабочего процесса, например package-publish.yml.
  • --environment <name>: необязательное окружение GitHub Actions с точным совпадением.
  • --json: машиночитаемый вывод.

Пример:

clawhub package trusted-publisher set @openclaw/example-plugin \  --repository openclaw/example-plugin \  --workflow-filename package-publish.yml \  --environment release

package trusted-publisher delete <name>

• Удаляет конфигурацию доверенного издателя из пакета.
• Используйте это для отката, если привязку рабочего процесса, репозитория или окружения необходимо отключить или создать заново.
• Последующие фактические публикации должны использовать обычную публикацию с аутентификацией, пока конфигурация не будет настроена снова.
• Флаги:
  • --json: машиночитаемый вывод.

Пример:

clawhub package trusted-publisher delete @openclaw/example-plugin

Телеметрия установки

• Отправляется после clawhub install <slug>, если выполнен вход, кроме случаев, когда задано CLAWHUB_DISABLE_TELEMETRY=1.
• Отправка данных выполняется по мере возможности. Команды установки не завершаются ошибкой, если телеметрия недоступна.
• Подробности: docs/telemetry.md.