From b90f3e1de3a85a73390d7f274e659e9aabadc61f Mon Sep 17 00:00:00 2001 From: nicshik Date: Thu, 16 Jul 2026 08:55:25 +0300 Subject: [PATCH] docs: add Hermes (non-OpenClaw) deployment guide Add docs/hermes-deployment.md: deploying agy + the antigravity_ask / antigravity_image agent skills on the Hermes host (Python Telegram agent running codex exec, no OpenClaw). Based on an analysis of the live Hermes host and the hermes repo: hardened systemd unit (ReadWritePaths drop-in for ~/.gemini), deploy --delete on workspace/bin (wrappers go to /usr/local/bin), per-task artifact delivery (SKILL.md addendum), optional SKILL_CATALOG registration. login.sh is reused as-is via OPENCLAW_USER=hermes; the /antigravity panel plugin does not port. Link the guide from both READMEs and their Files sections. --- README.md | 8 +- README.ru.md | 7 +- docs/hermes-deployment.md | 263 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 276 insertions(+), 2 deletions(-) create mode 100644 docs/hermes-deployment.md diff --git a/README.md b/README.md index 9bbec71..a95fef4 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,12 @@ pretending to be the old `gemini` CLI. Works on any **OpenClaw host** running the gateway as a dedicated service user. It is OpenClaw-specific glue — it installs into the OpenClaw gateway via `openclaw -plugins install`, so it does not apply to non-OpenClaw agent stacks. +plugins install`, so it does not apply to non-OpenClaw agent stacks. The one +supported exception is Nick's **Hermes** host (a Python Telegram agent running +`codex exec`, no OpenClaw): the agy install, the OAuth login, and the two agent +skills port over — see [`docs/hermes-deployment.md`](docs/hermes-deployment.md) +(in Russian, matching the Hermes docs). The `/antigravity` panel plugin itself +does not port. ## Why a plugin (not a skill) @@ -364,6 +369,7 @@ scripts/healthcheck.sh end-to-end verification, non-zero exit on failure scripts/uninstall.sh remove plugin + symlink + helper (--purge also removes agy) scripts/secret-scan.sh fail if any tracked file looks like a credential docs/plugin-internals.md maintainer design notes: command/rendering model + onboarding internals +docs/hermes-deployment.md deploying agy + the agent skills on the Hermes host (no OpenClaw; RU) docs/onboarding-improvement-plan.md design notes for the onboarding flow .github/workflows/preflight.yml CI gate: shell/plugin syntax, JSON, secret-scan, no *bak* ``` diff --git a/README.ru.md b/README.ru.md index a2813ac..b73ddcf 100644 --- a/README.ru.md +++ b/README.ru.md @@ -23,7 +23,11 @@ Google снял отдельный CLI `gemini` для индивидуальн Работает на любом **хосте OpenClaw**, где гейтвей запущен под выделенным сервисным пользователем. Это связка именно для OpenClaw — плагин ставится через -`openclaw plugins install`, к другим агентским стекам не применим. +`openclaw plugins install`, к другим агентским стекам не применим. Единственное +поддерживаемое исключение — хост **Hermes** (Python-агент для Telegram поверх +`codex exec`, без OpenClaw): туда переносятся установка agy, OAuth-логин и оба +агентских скилла — см. [`docs/hermes-deployment.md`](docs/hermes-deployment.md). +Сам плагин-пульт `/antigravity` не переносится. ## Почему плагин (а не скилл) @@ -369,6 +373,7 @@ scripts/healthcheck.sh сквозная проверка, ненулевой scripts/uninstall.sh удалить плагин + симлинк + хелпер (--purge удаляет и agy) scripts/secret-scan.sh падает, если какой-то отслеживаемый файл похож на креденшал docs/plugin-internals.md заметки для мейнтейнеров: модель команд/рендеринга + внутренности онбординга +docs/hermes-deployment.md разворачивание agy + агентских скиллов на хосте Hermes (без OpenClaw) docs/onboarding-improvement-plan.md заметки по дизайну онбординга .github/workflows/preflight.yml CI-гейт: синтаксис шелла/плагина, JSON, secret-scan, запрет *bak* ``` diff --git a/docs/hermes-deployment.md b/docs/hermes-deployment.md new file mode 100644 index 0000000..7ba9908 --- /dev/null +++ b/docs/hermes-deployment.md @@ -0,0 +1,263 @@ +# Разворачивание на Hermes (без OpenClaw) + +Как поставить Antigravity CLI (`agy`) и скиллы `antigravity_ask` / +`antigravity_image` на сервер **Hermes** — Telegram-агент Ника на Python +(`hermes-agent`), который запускает `codex exec` и не имеет никакого OpenClaw. + +Гайд написан по результатам анализа боевого хоста Hermes (89.22.232.11, +Ubuntu 24.04) и репозитория `hermes` от 2026-07-16. Все пути и ограничения ниже — +проверенные факты, не предположения. + +## Что переносится, а что нет + +| Часть gemini-claw | На Hermes | +|---|---| +| Установка `agy` под сервисным пользователем + симлинк в PATH | Переносится (шаги 2–3) | +| `scripts/login.sh` (OAuth Google AI Pro через tmux) | Работает как есть с `OPENCLAW_USER=hermes` | +| Скиллы `skills/antigravity_ask`, `skills/antigravity_image` (`runtimes: codex`) | Переносятся с двумя правками: обёртки и доставка файлов (шаги 5–6) | +| Плагин-пульт `plugin/index.js` (`/antigravity` меню, кнопки) | **Не переносится** — это OpenClaw plugin SDK; аналог пришлось бы писать на Python внутри `hermes_agent` | +| `scripts/setup.sh`, `install.sh`, `preflight.sh`, `healthcheck.sh` | **Не подходят** — падают без CLI `openclaw` (проверка `OPENCLAW_BIN`) | +| Хелпер `bin/agy-models` + таймер | Не нужен (он обслуживает меню пульта); ставить не обязательно | + +## Чем Hermes отличается от хоста OpenClaw + +Факты, вокруг которых построены шаги: + +- Бот — systemd-юнит `hermes-agent`: `User=hermes` (home `/home/hermes`), + код в `/opt/hermes-agent`, `WorkingDirectory=/srv/hermes-agent/workspace`. +- Юнит **жёстко захардён**: `ProtectSystem=strict`, `ProtectHome=read-only`, + запись разрешена только в `ReadWritePaths=/srv/hermes-agent /var/lib/hermes-agent + /home/hermes/.codex`. `agy` пишет OAuth-токен и артефакты в `~/.gemini` — + без drop-in с `ReadWritePaths=/home/hermes/.gemini` генерация из бота упадёт + на записи (шаг 4). Снаружи юнита (root/ssh) ограничения не действуют, + поэтому установка и логин работают до drop-in. +- `PATH` юнита включает `/usr/local/bin` — симлинк `/usr/local/bin/agy` виден + боту (там же уже живёт `codex`). +- `codex exec` запускается с `--sandbox danger-full-access` (переменная + `CODEX_SANDBOX` в `/etc/hermes-agent/telegram.env`) — процессы codex + ограничивает только systemd-hardening, отдельной песочницы нет. +- Деплой Hermes (`scripts/deploy_hermes.py`) льёт `workspace/bin/` по rsync + **с `--delete`** — всё, что положить туда мимо репозитория `hermes`, сотрётся + при следующем деплое. Каталоги `workspace/skills/<имя>/` синкаются + поимённо (antic, image_gen, …), поэтому новые каталоги скиллов деплой не + трогает. Отсюда правило: **скиллы — в `workspace/skills/`, обёртки — в + `/usr/local/bin/`** (обе локации переживают деплой Hermes). +- Картинки в Telegram Hermes доставляет **только из каталога задачи** + (Hermes передаёт его в промпте строкой «Каталог для файлов этой задачи: + <путь>» и после задачи сканирует его). `gen.py` пишет в + `$OPENCLAW_WORKSPACE_DIR/outputs/antigravity-skill-images/` и печатает + `IMAGE: <путь>` — codex должен скопировать эти файлы в каталог задачи + (шаг 6), иначе картинка сгенерируется, но в чат не уедет. +- Команда `/skill <имя>` в Hermes принимает только имена из реестра + `SKILL_CATALOG` в `hermes_agent/config.py` (репозиторий `hermes`). Без + регистрации скиллы всё равно работают: правило в `workspace/AGENTS.md` + велит codex читать `skills/<имя>/SKILL.md`, если задача явно упоминает скилл + («сделай через antigravity_image …»). Регистрация — необязательный шаг 7. +- На хосте уже есть `tmux`, `curl`, `git`; свободного диска ~4 ГБ — на `agy` + хватает. + +У Hermes уже есть скилл `image_gen` (Gemini API по ключу `GEMINI_API_KEY`, с +пометражным биллингом). `antigravity_image` закрывает ту же потребность через +подписку Google AI Pro по OAuth — без API-ключа и биллинга. + +## Шаг 0. Предпосылки + +- root-доступ по SSH на хост Hermes. +- Аккаунт **Google AI Pro** для OAuth (лучше выделенный, не основной — см. + раздел Security в README). +- Развёрнутый стек Hermes (юнит `hermes-agent` активен). + +## Шаг 1. Клонировать репозиторий на хост + +```bash +git clone https://github.com/nicshik/gemini-claw /root/gemini-claw +cd /root/gemini-claw +``` + +Обновления потом — `git pull`, как и для OpenClaw-хостов. + +## Шаг 2. Установить agy под пользователем hermes + +Официальный установщик, от имени `hermes` (не root): + +```bash +sudo -u hermes env HOME=/home/hermes PATH=/usr/local/bin:/usr/bin:/bin \ + bash -c 'curl -fsSL https://antigravity.google/cli/install.sh | bash' +ln -sfn /home/hermes/.local/bin/agy /usr/local/bin/agy +sudo -u hermes env HOME=/home/hermes agy --version +``` + +Важно: команды под `hermes` запускать через `sudo -u hermes env HOME=/home/hermes …` +(или `runuser -u hermes -- env HOME=/home/hermes …`), но **не** `sudo -E` — +`sudo -E` протаскивает root-овый `$HOME`, и agy/codex пишут состояние не туда. + +## Шаг 3. OAuth Google AI Pro + +`scripts/login.sh` не зависит от OpenClaw (переменная называется +`OPENCLAW_USER` по историческим причинам — это просто сервисный пользователь): + +```bash +sudo OPENCLAW_USER=hermes scripts/login.sh +``` + +Скрипт печатает URL — открой его в локальном браузере, войди в аккаунт AI Pro, +вставь код обратно. Это единственный ручной шаг; токен ляжет в +`/home/hermes/.gemini` и никуда не копируется. + +Проверка: + +```bash +sudo -u hermes env HOME=/home/hermes bash -c \ + 'timeout 90 /usr/local/bin/agy -p "Reply with exactly: OK" /etc/systemd/system/hermes-agent.service.d/antigravity.conf <<'EOF' +[Service] +# agy (Antigravity CLI) держит OAuth-токен и артефакты в ~/.gemini +ReadWritePaths=/home/hermes/.gemini +EOF +systemctl daemon-reload +systemctl restart hermes-agent +systemctl is-active hermes-agent +``` + +## Шаг 5. Установить скиллы и обёртки + +Каталоги скиллов — в workspace (переживают деплой Hermes, см. выше): + +```bash +cp -r /root/gemini-claw/skills/antigravity_ask /root/gemini-claw/skills/antigravity_image \ + /srv/hermes-agent/workspace/skills/ +chown -R hermes:hermes /srv/hermes-agent/workspace/skills/antigravity_ask \ + /srv/hermes-agent/workspace/skills/antigravity_image +``` + +Обёртки — в `/usr/local/bin` (в `workspace/bin` нельзя: деплой Hermes льёт его +с `--delete`). Родные обёртки из `skills/bin/` ищут скрипт относительно себя, +поэтому для Hermes пишем свои, с зашитым workspace: + +```bash +cat > /usr/local/bin/antigravity-image <<'EOF' +#!/usr/bin/env bash +set -euo pipefail +export OPENCLAW_WORKSPACE_DIR="${OPENCLAW_WORKSPACE_DIR:-/srv/hermes-agent/workspace}" +exec python3 /srv/hermes-agent/workspace/skills/antigravity_image/scripts/gen.py "$@" +EOF +cat > /usr/local/bin/antigravity-ask <<'EOF' +#!/usr/bin/env bash +set -euo pipefail +exec python3 /srv/hermes-agent/workspace/skills/antigravity_ask/scripts/ask.py "$@" +EOF +chmod 0755 /usr/local/bin/antigravity-image /usr/local/bin/antigravity-ask +``` + +`OPENCLAW_WORKSPACE_DIR` направляет вывод `gen.py` в +`/srv/hermes-agent/workspace/outputs/antigravity-skill-images/` (юниту туда +можно писать; каталог самоочищается до 20 последних файлов). + +## Шаг 6. Дописать в SKILL.md правила для Hermes + +Установленные SKILL.md написаны под OpenClaw-пути и не знают про доставку +через каталог задачи. Дописываем (в **установленные** копии; исходники в +`/root/gemini-claw` не трогаем): + +```bash +cat >> /srv/hermes-agent/workspace/skills/antigravity_image/SKILL.md <<'EOF' + +## Hermes + +- Запускай обёртку по абсолютному пути: `/usr/local/bin/antigravity-image …` + (путь `~/.openclaw/workspace/bin/...` выше — для OpenClaw, здесь его нет). +- Hermes доставляет в Telegram только файлы из каталога задачи (он передан в + промпте строкой «Каталог для файлов этой задачи: <путь>»). После генерации + скопируй каждый файл из строк `IMAGE: <путь>` в этот каталог: + `cp "<путь из IMAGE:>" "<каталог задачи>/"`. +- Не утверждай, что картинка готова и отправлена, пока файл не лежит в + каталоге задачи. +EOF + +cat >> /srv/hermes-agent/workspace/skills/antigravity_ask/SKILL.md <<'EOF' + +## Hermes + +- Запускай обёртку по абсолютному пути: `/usr/local/bin/antigravity-ask …` + (путь `~/.openclaw/workspace/bin/...` выше — для OpenClaw, здесь его нет). +EOF +``` + +## Шаг 7 (необязательно). Регистрация в реестре скиллов Hermes + +Без этого шага скиллы уже работают через явное упоминание в тексте задачи +(«сделай через antigravity_image …») — правило из `workspace/AGENTS.md`. +Чтобы работали `/skill antigravity_image <задача>` и кнопки меню `/skills`, +в репозитории `hermes` в `hermes_agent/config.py` нужно добавить: + +- в `SKILL_CATALOG`: + `"antigravity_image": "картинки через Antigravity (agy, Nano Banana 2) по подписке Google AI Pro"`, + `"antigravity_ask": "вопрос модели через Antigravity CLI (agy)"`; +- при желании — алиасы в `SKILL_ALIASES` (`"agy"`, `"antigravity"`, `"nano-banana"`) + и пункт в `SKILL_MENU_ITEMS`; + +и задеплоить Hermes штатным `scripts/deploy-hermes.sh`. Это правка чужого +репозитория, поэтому в gemini-claw она не автоматизирована. + +## Шаг 8. Проверка + +```bash +# 1) agy отвечает под hermes (текст, без трат картиночной квоты) +sudo -u hermes env HOME=/home/hermes bash -c \ + 'timeout 90 /usr/local/bin/agy -p "Reply with exactly: OK" /dev/null || true +systemctl daemon-reload +# токен и сам agy (по желанию): +rm -rf /home/hermes/.gemini /home/hermes/.local/bin/agy +systemctl start hermes-agent +``` + +После удаления не забудь отозвать доступ приложения в аккаунте Google, если +токеном больше не пользуешься.