Gemini CLI – исчерпывающее руководство

Запрос: "Зайди на 1.3 и перечисли все Docker-контейнеры, которые потребляют больше 200Мб памяти."

Лог действий агента:

`run_command("ssh 1.3 'docker stats –no-stream –format \"{{.Name}}\t{{.MemUsage}}\"'")`

Анализ вывода (например, `gitlab-ee 2.4GB`, `nginx 15MB`).

Ответ: "На узле 1.3 только контейнер `gitlab-ee` превышает лимит…"

4.3. Задача №2: Поиск "иголки в стоге сена"

Попробуем найти ошибку в логах Nginx, которая случилась 10 минут назад.

Запрос: "Найди в логах /var/log/nginx/error.log все упоминания 'upstream timed out' за последние 15 минут и скажи, какой IP был источником."

Инструменты, которые использует агент:

`run_command("date -d '15 minutes ago' +'%Y/%m/%d %H:%M:%S'")`

`grep_search` или `awk` для фильтрации лога по времени.

Извлечение IP из строки лога.

4.4. Интерактивный режим vs One-off команды

Gemini CLI поддерживает два режима:

1. CLI Mode (`gemini "task"`): Запустил, получил результат, вышел. Идеально для скриптов Bash.

2. REPL Mode (`gemini`): Живой диалог. Контекст сохраняется между командами. Вы можете сказать "А теперь перезапусти этот сервис", и агент поймет, о каком сервисе шла речь ранее.

4.5. Золотое правило первой сессии

Никогда не доверяйте агенту на 100% в первый день. Используйте флаг `–dry-run` или просто внимательно читайте "Thought" блок. Если агент хочет выполнить `rm -rf`, а вы просили "почистить логи", остановите его.

> [!TIP]

> Начните с команд "Read-only". Попросите агента объяснить структуру вашего проекта или проанализировать `docker-compose.yml`.

––

Ключевые мысли главы:

Агентский Hello World – это **действие**, а не текст.

**SSH + Docker + Grep*– святая троица первого запуска.

Используйте **REPL*для сложных многошаговых задач.

Секция 5.1: SSH-туннели как артерии агента: Магия невидимых связей

Для агента Gemini CLI протокол SSH – это не просто способ зайти на сервер. Это фундамент его "сенсорной системы", позволяющий ему дотягиваться до самых удаленных узлов вашей сети. В этой секции мы разберем, как сделать SSH-туннели максимально надежными и прозрачными для ИИ.

5.1.1. SSH как RPC для Агентов

В классическом администрировании SSH используется интерактивно. Для агента SSH – это механизм удаленного вызова процедур (Remote Procedure Call).

Типичный сценарий:

Вы просите агента: "Проверь статус БД на сервере 1.3".

Агент не просто заходит туда. Он выполняет цепочку:

`Local -> Jump Host (1.1) -> Target (1.3)`.

5.1.2. Проксирование и Jump Hosts (ProxyJump)

Когда ваша сеть сегментирована, агент должен знать, как проходить через "шлюзы".

Использование директивы `ProxyJump` в `~/.ssh/config` – лучший способ сделать это для агента.

Пример конфигурации для ИИ-агента:

Host backend-node

HostName 10.252.1.3

ProxyJump gateway-node

User noc

IdentityFile ~/.ssh/id_ed25519_agent

Благодаря этой записи, агент в промпте может просто написать: `ssh backend-node "uptime"`. Ему не нужно знать всю топологию сети, SSH-клиент сделает это за него. Это экономит контекстное окно модели!

5.1.3. SSH-туннелирование (Port Forwarding)

Иногда агенту нужно получить доступ к сервису, который доступен только локально на удаленном узле (например, административный порт Redis).

**Local Forwarding:*`ssh -L 6379:localhost:6379 backend-node`. Агент "прокидывает" порт себе и может работать с Redis так, будто он запущен локально.

**Использование агентом:*Агент сам понимает, когда нужно поднять туннель: "Сервис доступен только на 127.0.0.1 удаленного узла. Я создам временный SSH-туннель для анализа".

5.1.4. Key-based Auth и SSH Agent

Автономному агенту нельзя вводить пароли. Использование SSH-ключей (ED25519) – единственный путь.

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

5.1.5. Решение проблемы "Зависших соединений"

SSH-сессии могут "подвисать". Агент может ждать вывода вечно.

Настройки для надежности:

ServerAliveInterval 60

ServerAliveCountMax 3

Эти опции заставляют SSH-клиент завершаться, если сервер перестал отвечать, что позволяет агенту получить ошибку и перепланировать свои действия (например, попробовать другой маршрут).

5.1.6. SCP и SFTP: Руки Агента для файлов

Передаче файлов между узлами агент отдает приоритет `scp` или `rsync`. Для него это атомарная операция.

> "Я вижу, что патч готов на Gateway. Я перенесу его на Backend через scp и применю там".

––

Резюме раздела:

SSH для Gemini CLI – это не просто протокол, это его "нервная система". Чем чище и прозрачнее настроен ваш SSH-конфиг, тем быстрее и эффективнее агент будет перемещаться по вашей инфраструктуре. В следующей секции мы перейдем к созданию еще более глубокой и безопасной связи – меш-сети WireGuard.

Секция 5.2: WireGuard для агентов: Создание безопасной сети

В то время как SSH идеален для точечных "уколов", для полноценной жизни агенту нужна целостная сетевая среда. WireGuard – это современный протокол VPN, который работает быстрее всех конкурентов и имеет минимальную поверхность атаки. В этой секции мы научим агента Gemini CLI управлять меш-сетью.

5.2.1. Почему WireGuard – это "VPN для роботов"?

В отличие от OpenVPN c его сложным процессом рукопожатия и медленным переключением, WireGuard работает по принципу Peer-to-Peer. Он не держит постоянного соединения, когда нет трафика.

**Для агента это означает:*Минимальные задержки (Latency). Агент получает ответ от удаленного узла так же быстро, как от соседа по стойке.

**Безопасность:*Если агент видит, что VPN-интерфейс `wg0` упал, он блокирует все свои сетевые попытки до восстановления связи.

5.2.2. Архитектура "Плоской Сети" (Flat Mesh Network)

Главная проблема администрирования – сложная адресация. Агенту сложно помнить, что сервер `A` доступен через `10.0.1.5`, а сервер `B` через `192.168.50.22`.

Решение через WireGuard: Все узлы объединяются в одну подсеть (например, `10.8.0.0/24`).

Агент теперь может обращаться к узлам по простым IP: `10.8.0.1`, `10.8.0.3` и т.д. Это упрощает его логику планирования почти в 10 раз.

5.2.3. Генерация конфигурации агентом

Агент может сам управлять расширением вашей сети.

> "Я вижу новый узел 1.5. Я сгенерирую для него пару ключей WireGuard, добавлю его публичный ключ в конфиг шлюза и пришлю вам команду для настройки узла".

Код, который может сгенерировать агент:

wg genkey | tee privatekey | wg pubkey > publickey

Агент понимает структуру `wg0.conf` и может безошибочно вносить в него изменения с помощью `sed` или `awk`.

5.2.4. Роутинг и IP-форвардинг

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

**Задача агента:*"Настрой `wg0` так, чтобы весь трафик на `8.8.8.8` шел через туннель".

**Действие агента:*Проверка `/proc/sys/net/ipv4/ip_forward` и настройка таблиц роутинга.

5.2.5. Проблема "Roaming" (Бродячие агенты)

WireGuard позволяет агенту менять свои IP-адреса на лету (например, если вы переносите Gateway с одного провайдера на другой). Трафик не рвется. Агент просто продолжает выполнять свою задачу в фоне, даже если его внешний IP изменился 10 раз за сессию.

5.2.6. Мониторинг здоровья сети

Агент в фоне может периодически выполнять `wg show` и анализировать время синхронизации (Latest Handshake). Если он видит, что узел молчит более 3 минут, он может инициировать процедуру рестарта VPN или поднять тревогу.

––

Резюме раздела:

WireGuard превращает разрозненные серверы в единый, защищенный "цифровой организм". Для Gemini CLI это означает упрощение навигации и гарантированную безопасность коммуникаций. В следующей секции мы разберем, как защитить этот организм от внешнего мира с помощью мощных фаерволов IPTables и NFTables.

Секция 5.3: Управление фаерволами (IPTables, NFTables): Огненный щит Агента

Безопасность сетевой ткани (которую мы построили в прошлых секциях) бесполезна, если её периметр не защищен фаерволом. В этой секции мы научим агента Gemini CLI работать с "низкоуровневой гвардией" ядра Linux – IPTables и современным NFTables.

5.3.1. Фаервол как Декларативная Политика

Для обычного человека правила фаервола – это запутанные цепочки команд. Для агента это набор логических условий.

Агент воспринимает задачу так: "Запрети всё по умолчанию (DROP), кроме порта 22 для моего IP и порта 51820 для WireGuard".

5.3.2. IPTables: Старая школа фильтрации

Несмотря на возраст, IPTables остается самым распространенным инструментом. Агент использует его для быстрых манипуляций.

Сценарий блокировки атаки:

Если агент видит в логах Nginx атаку типа "грубая сила" (Brute-force), он может мгновенно выполнить:

iptables -A INPUT -s [ATTACKER_IP] -j DROP

Это происходит на порядок быстрее, чем если бы это делал человек. Агент "чувствует" атаку через логи и реагирует на уровне ядра.

5.3.3. NFTables: Будущее сетевого управления

NFTables – это замена IPTables с более чистым синтаксисом и высокой производительностью.

Агент отдает предпочтение NFTables, если он доступен в системе, так как его конфиги более структурированы и легче поддаются автоматическому анализу.

Агент может "прочитать" текущее состояние сети одним взглядом:

`nft list ruleset` для агента – это JSON-подобная структура знаний, по которой он понимает, какие "дыры" открыты в вашей системе.

5.3.4. State Management (Conntrack)

Агент учитывает состояние соединений (Stateful Inspection). Он знает, что если он инициировал исходящий запрос к API Gemini, то ответ должен быть пропущен фаерволом автоматически.

**Правило агента:*"Разреши входящий трафик для уже установленных соединений (RELATED, ESTABLISHED)".

5.3.5. Опасности автоматического управления фаерволом

Главный риск – агент может заблокировать сам себя (и вас).

> "Я закрою порт 22, чтобы никто не ломался. Ой, я сам теперь не могу зайти по SSH".

Механизм защиты в Gemini CLI:

Перед применением правил фаервола агент обязан добавить правило "Безопасного окна" или использовать временное применение скрипта (например, через `cron`), который откатит правила назад через 60 секунд, если агент не подтвердит свою связность.

5.3.6. NAT и Проброс Портов

Агент может выступать в роли сетевого инженера, настраивая доступ к внутренним сервисам извне:

> "Я настрою DNAT на шлюзе 1.1, чтобы трафик на порт 8080 перенаправлялся напрямую на Backend 1.3".

5.3.7. Логирование и алертинг фаервола

Агент может настроить фаервол так, чтобы подозрительные пакеты писались в `dmesg`, а сам агент следил за этим выводом. Это создает замкнутую систему: Обнаружение -> Блокировка -> Логирование -> Анализ.

––

Резюме раздела:

Управление фаерволом через Gemini CLI превращает пассивную защиту в активную иммунную систему. Агент не просто "ставит правила", он динамически адаптирует их под текущую обстановку.

Этим разделом мы завершаем Модуль 5. В следующем модуле мы перейдем к управлению Вычислительными Мощностями – Docker, Kubernetes и процессорам.

Глава 5: Философия минималистичного промптинга: Как говорить, чтобы вас понимали

В мире агентских CLI промпт – это не просто вопрос, это техническое задание. Но есть ловушка: многие пользователи пишут либо слишком мало ("Почини"), либо слишком много ("Я хочу, чтобы ты пошел на сервер, проверил диск, если он полный, удали логи, но только те, что старые…"). В этой главе мы разберем искусство "золотой середины".

5.1. Принцип "Намерение вместо Инструкций"

Главная ошибка – пытаться микро-менеджить агента. Помните, у него есть паттерн ReAct. Если вы скажете ему "как" делать, вы лишите его возможности найти более оптимальный путь.

**Плохо:*"Запусти `df -h`, найди `/var/log` и удали файлы `.log`."

**Хорошо:*"Освободи 5ГБ места в разделе `/var`, удалив только старые архивы логов. Не трогай активные файлы."

Во втором случае агент сам решит, использовать `find`, `du` или `rm`, и проверит дескрипторы открытых файлов.

5.2. Контекстная плотность (Contextual Density)

Агент видит систему, но он не знает ваших бизнес-процессов. Добавляйте только тот контекст, который он не может получить из командной строки.

Пример эффективного промпта:

> "Мы переходим на схему 1.3 для GitLab. Проверь, готов ли текущий конфиг Caddy к приему трафика на порту 8080."

Здесь "схема 1.3" – это контекст, который агент сопоставит с вашим README или Knowledge Items, а всё остальное он проверит сам.

5.3. Структура идеального запроса

Используйте формулу [Цель] + [Ограничения] + [Ожидаемый результат]:

1. Цель: "Обнови Docker-образ фронтенда."

2. Ограничения: "Используй тег `latest`, не перезапускай контейнер в рабочее время (сейчас 14:00)."

3. Результат: "После сборки пришли мне хеш нового образа."

5.4. Магия "Уточняющих вопросов"

Хороший агент – это тот, кто спрашивает, если не уверен. Если ваш промпт двусмысленен, агент может остановиться.

*Совет:Если вы хотите, чтобы агент был более смелым, добавьте "Accepting risks: low". Если вы в критической среде – "High-stakes mode".

5.5. Как избегать "галлюцинаций в командах"

Иногда ИИ придумывает флаги команд, которых не существует (например, `ls –sort-by-magic`).

Метод защиты: Просите агента сначала вызвать `–help` для незнакомого инструмента.

> "Прежде чем настраивать WireGuard, проверь версию `wg` и доступные параметры."

––

Ключевые мысли главы:

Описывайте **желаемое состояние**, а не список команд.

**Меньше слов – больше смысла.*Избегайте вежливости ("Пожалуйста, если тебе не трудно…"), это мусорные токены.

Давайте четкие **границы допустимого**.

> [!TIP]

> Промпт в терминале – это код. Пишите его так, как если бы вы писали чистую функцию: понятное имя (команда), четкие аргументы (контекст).

В следующей главе мы перейдем к Инструментарию: глубокому разбору того, как агент "щупает" вашу систему через SSH, Grep и Docker.

Секция 6.1: Docker для агентов: Создание неизменяемых сущностей

Контейнеризация – это то, что превращает хаотичные серверы в предсказуемые блоки конструктора. Для Gemini CLI Docker является не просто инструментом, а фундаментом стабильности. В этой секции мы разберем, как агент использует Docker для создания "неизменяемой инфраструктуры" (Immutable Infrastructure).

6.1.1. Философия "Контейнер как Атомарная Мысль"

Когда вы просите агента развернуть приложение, он не устанавливает зависимости в систему. Он упаковывает их в `Dockerfile`.

**Для агента это означает:*Гарантия результата. Если образ собрался на Gateway, он будет работать и на Backend.

**Изоляция зависимостей:*Агент может запускать Python 2.7 и Python 3.12 на одной машине одновременно, не вызывая конфликтов в `pip`.

6.1.2. Промпт-инжиниринг Docker-образов

Агент Gemini CLI – виртуоз в написании `Dockerfile`. Он знает лучшие практики (Multi-stage builds, минимизация слоев, использование Alpine/Distroless).

Пример диалога с агентом:

> "Напиши Dockerfile для Go-приложения, максимально безопасный и легкий".

> *Действие агента:* Создание файла с использованием `builder` стейджа и копированием бинарника в `scratch` или `alpine`.

6.1.3. Управление жизненным циклом (Docker Compose)

Для сложных систем агент использует Docker Compose. Он видит в этом YAML-файле описание целой экосистемы (БД + API + Frontend).

Агентский инсайт:

Агент может анализировать `docker-compose.yml` и находить ошибки в сетях (например, забытый `links` или неправильное имя сервиса), которые человек может пропустить.

6.1.4. Отладка внутри контейнера (Docker Exec)

Если сервис внутри контейнера не работает, агент не гадает. Он "входит" внутрь через `run_command(cmd="docker exec -it … bash")`.

Это дает ему доступ к "микромиру" приложения. Он может проверить внутренние логи, доступность портов и переменные окружения именно так, как их видит само приложение.

6.1.5. Реестры образов и Безопасность

Агент понимает важность приватных реестров (Private Registry).

> "Я соберу образ локально, повешу на него тег вашей компании и пушну в GitLab Registry, чтобы другие узлы могли его скачать".

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

Агент может интегрировать инструменты типа `trivy` или `snyk` в свой цикл сборки.

**Thought:*"Перед публикацией образа я должен убедиться, что в нем нет критических уязвимостей (CVE)".

**Observation:*"Найдено 3 ошибки High. Я заменю базовый образ на более свежий".

6.1.6. Оптимизация ресурсов: Docker Prune

Автономные агенты могут генерировать много мусора (неиспользуемые слои, остановленные контейнеры).

Гигиена агента: Хорошо обученный агент Gemini CLI всегда завершает сессию очисткой: `docker system prune -f`, чтобы не забивать диск инфраструктуры.

––

Резюме раздела:

Docker дает агенту "суперсилу" воспроизводимости. Используя контейнеры, Gemini CLI перестает быть просто помощником и становится настоящим архитектором, создающим надежные и масштабируемые системы. В следующей секции мы пойдем еще дальше и разберем, как агент управляет целыми кластерами серверов через Kubernetes.

Секция 6.2: Kubernetes: Управление кластерным разумом

Если Docker – это книга, то Kubernetes – это огромная библиотека с миллионами томов, где всё движется и переставляется само собой. Для ИИ-агента Kubernetes является "естественной средой обитания", так как оба они основаны на декларативном описании желаемого состояния. В этой секции мы научим Gemini CLI управлять кластером как единым мозгом.

6.2.1. Агент против Кубернетеса: Кто кем управляет?

Kubernetes сам по себе является "агентом" (Core Controllers). Он следит за тем, чтобы количество подов совпадало с описанием.

Gemini CLI добавляет когнитивный слой над этим. Он не просто "перезапускает под", он анализирует: "Почему под падает? Связано ли это с недостатком памяти на узле 1.2 или с ошибкой в новом конфиге?".

6.2.2. Навигация в Океане Манифестов (YAML Engineering)

Одна из главных задач агента – написание и коррекция YAML-манифестов.

**Deployment:*Агент описывает, как обновлять приложение (RollingUpdate).

**Service & Ingress:*Агент настраивает внешние пути доступа.

**ConfigMaps & Secrets:*Агент управляет динамическими настройками.

Преимущество ИИ: Агент может быстро найти ошибку в `indentation` (отступах) или неправильное использование `Selectors`, на что человек может потратить 20 минут дебага.

6.2.3. Оперативное управление через `kubectl`

Агент использует `kubectl` как свои глаза.

> "Проанализируй события (events) в неймспейсе 'production'. Найди все поды со статусом ImagePullBackOff".

Агент мгновенно парсит вывод `kubectl get events -o json` и сопоставляет ошибки с конкретными действиями (например, опечатка в имени образа в Docker Registry).

6.2.4. Регрессионное тестирование в Кластере

Агент может выполнять "Канареечные релизы" (Canary Releases) в автоматическом режиме:

1. Агент разворачивает новую версию (V2) рядом с V1.

2. Направляет 5% трафика на V2.

3. Следит за метриками ошибок.

4. Если всё хорошо – делает Full Rollout. Если нет – делает моментальный Rollback.

6.2.5. Управление ресурсами: ЦПУ и Память

Агент играет роль "экономки" кластера. Он анализирует `ResourceQuotas` и `Limits`.

**Действие:*"Я вижу, что под `legal-bot` потребляет 90% лимита памяти. Я увеличу лимиты в манифесте и применю изменения".

**Размышление:*"Достаточно ли места на физических узлах для этого расширения?".

6.2.6. Кастомные ресурсы (CRDs) и Операторы

Продвинутый агент может писать собственные Kubernetes Operators на Python или Go. Это позволяет создавать абсолютно автономную инфраструктуру, которая не только чинит себя, но и эволюционирует на основе данных о нагрузке.

––

Резюме раздела:

Kubernetes для Gemini CLI – это не инструмент, это манифест его воли. Используя мощь оркестрации, агент превращает разрозненные серверы в гибкую и неубиваемую систему. В следующей секции мы разберем, как не допустить "выгорания" этой системы через глубокий мониторинг ресурсов.

Секция 6.3: Мониторинг ресурсов и борьба с "утечками памяти" ИИ

Автономный агент – это "жадное" существо. Он потребляет ЦПУ для выполнения команд, память для хранения контекста и пропускную способность сети для доступа к API. Если не следить за его "аппетитом", он может привести к отказу всей системы. В этой финальной секции Модуля 6 мы научимся мониторить "метаболизм" агента и предотвращать ресурсные катастрофы.

6.3.1. Глаза Агента: `top`, `htop`, `vmstat`

Агент использует классические утилиты Linux не только для того, чтобы показать их вам, но и чтобы понять собственное состояние.

Интеллектуальный анализ нагрузки:

Вместо того чтобы просто смотреть на 100% Load Average, агент анализирует:

**CPU Wait:*"Может ли быть проблема в медленном диске (I/O)?"

**Steal Time:*"Не забирает ли ресурсы хост-гипервизор у нашей VM?"

**Memory Swapping:*"Пора ли убить какой-то процесс, чтобы система не 'задохнулась'?"

6.3.2. Проблема "Утечки Памяти" сессии (Context Overload)

У ИИ-агентов есть специфический вид "утечки памяти" – переполнение контекстного окна. В длинных сессиях агент накапливает столько данных, что начинает "тормозить", отвечать медленнее и совершать логические ошибки.

Стратегия очистки:

Агент периодически выполняет "Сброс контекста" (Context Truncation). Он суммирует важные выводы (дистилляция) и удаляет сырые логи прошлых шагов. Это аналогично очистке кэша в обычном приложении.

6.3.3. Мониторинг Интенсивности API (Token Burn Rate)

Работа агента стоит денег (токены). Без контроля агент может потратить месячный бюджет за 10 минут, если попадет в бесконечный цикл.

Защитные механизмы:

1. Quota Watcher: Агент мониторит остаток на балансе API (если есть такой инструмент в MCP).

2. Step-by-Step Cost Analysis: Перед каждым шагом агент оценивает: "Стоит ли это действие потраченных ресурсов?".

6.3.4. Ограничение влияния через Cgroups

На системном уровне мы рекомендуем ограничивать группу процессов, в которой живет агент, через Cgroups.

`cpu.max`: Ограничить использование до 1 ядра.

`memory.max`: Ограничить до 2 ГБ.

Если агент выйдет за эти рамки, ядро Linux (OOM Killer) убьёт процесс агента, сохранив работоспособность критических систем (БД, веб-сервер).

6.3.5. Визуализация метрик через Prometheus и Grafana