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

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

3.3.1. Разница между системным логом и логом аудита

Обычные логи (syslog, journald) фиксируют, *что* произошло. Лог аудита агента фиксирует, *почему* это произошло.

Состав идеального лога аудита:

1. Request ID: Уникальный идентификатор задачи.

2. User Intent: Что пользователь попросил на самом деле.

3. Thought Trace: Цепочка рассуждений агента.

4. Tool Call: Точный синтаксис вызванного инструмента.

5. Observation: Сырой вывод системы.

6. Safety Justification: Обоснование безопасности (для критических команд).

3.3.2. Проблема "Переписывания истории"

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

Решение: Удаленный логгинг (Remote Audit Sink)

Логи должны немедленно отправляться на выделенный сервер (например, через `fluentd` или `syslog-ng`), к которому у агента нет прав записи.

**Схема:*Agent -> Local Buffer -> Remote Immutable Log Storage.

3.3.3. Структурированный формат JSONL

Мы используем JSON-Lines (`.jsonl`), так как он позволяет читать логи построчно, не загружая весь файл в память. Это критично для систем, работающих месяцами.

Пример записи в аудите:

{

"timestamp": "2026-02-09T18:50:00Z",

"task_id": "8b5a..",

"step": 4,

"thought": "I suspect the database is locked. I will check for long-running queries.",

"action": "run_command",

"params": {"cmd": "psql -c 'SELECT pid, query FROM pg_stat_activity'"},

"safety_score": 0.95

}

3.3.4. Визуализация аудита для комиссий по разбору инцидентов (Post-mortems)

При разборе инцидентов ("Почему GitLab упал в 2 часа ночи?") логи агента становятся главным свидетелем.

Инструменты визуализации (например, специализированные дашборды в Grafana) позволяют превратить сухой JSON в графическую цепочку ReAct, где красным подсвечены моменты, когда "Наблюдение" противоречило "Мысли" агента.

3.3.5. Интеграция с SIEM (Security Information and Event Management)

Для энтерпрайз-сред логи Gemini CLI должны интегрироваться в общую систему безопасности компании (Splunk, Elastic stack). Аномалии в поведении агента (например, внезапный интерес к файлам `/etc/shadow`) должны триггерить моментальные алерты дежурному офицеру безопасности.

3.3.6. Хранение и Цикл Жизни Логов

Текстовые логи занимают место. Однако, учитывая их ценность для обучения модели, мы рекомендуем:

**Hot-storage (7 дней):*Локально в JSONL для быстрого поиска.

**Cold-storage (1 год):*В сжатом виде (`zstd`) на архивном узле (узел 1.4 в нашей сети).

––

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

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

Завершая Часть 1 нашего руководства, мы должны выйти за рамки кода и логов. Автономность агента порождает фундаментальный вопрос: кто виноват, если всё сломалось? В этой секции мы обсудим юридические и этические рамки использования Gemini CLI в профессиональной деятельности.

3.4.1. Проблема "Субъектности без ответственности"

С точки зрения закона, ИИ-агент не является субъектом права. Вы не можете подать в суд на "модель" или "код".

Юридическая правда: Вся ответственность за действия агента всегда лежит на владельце токена API (индивидууме или компании).

Если агент по вашей просьбе "почистить диск" случайно стер персональные данные клиентов (GDPR violation), штраф будете платить вы, а не разработчики Gemini.

3.4.2. Этический кодекс SRE в эпоху ИИ

Мы предлагаем три столпа этичного использования агентов:

1. Прозрачность: Агент не должен скрывать свои действия за сложными терминами. Его рассуждения должны быть понятны человеку среднего уровня квалификации.

2. Обратимость: Каждое действие агента должно по возможности иметь "путь отката" (Rollback). Если действие необратимо (например, `flash` прошивки), оно обязательно требует двойного человеческого подтверждения.

3. Неприкосновенность приватности: Агент не должен анализировать файлы, не относящиеся к задаче (личные переписки в `/home`, ключи кошельков и т.д.), если это явно не санкционировано.

3.4.3. Агент как со-автор (Attribution)

Если агент написал 90% кода вашей инфраструктуры, является ли этот код вашим?

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

3.4.4. Риск "Деградации навыков" (Skill Rot)

Этическая ответственность перед самим собой: использование агентов может привести к тому, что вы разучитесь делать вещи вручную. В критической ситуации (когда интернет пропал и доступа к облачному LLM нет), вы должны уметь восстановить систему "на голом железе".

Совет: Устраивайте дни "Ручного администрирования", чтобы поддерживать форму.

3.4.5. Будущее: Смарт-контракты ответственности

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

3.4.6. "Human-in-the-Loop" как единственный стандарт

В конечном итоге, единственным этичным и безопасным способом эксплуатации Gemini CLI является принцип Человека в контуре. Агент – это продолжение вашей воли, а не её замена.

––

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

Технологии всегда обгоняют законы. Работа с Gemini CLI требует от вас не только технических знаний, но и высокой моральной зрелости. Понимая риски и принимая на себя ответственность, вы становитесь настоящим архитектором будущего, а не просто оператором машины.

––

МЫ ЗАВЕРШИЛИ ЧАСТЬ 1: ВВЕДЕНИЕ И ФИЛОСОФИЯ.

Впереди нас ждет Часть 2: Инструментарий, где мы начнем разбирать конкретные команды, скрипты и методы автоматизации на самом низком и детальном уровне.

Запуск ИИ-агента с правами исполнения команд – это огромная ответственность. В этой главе мы разберем, как развернуть Gemini CLI так, чтобы он стал вашим лучшим помощником, а не точкой входа для взлома.

3.1. Подготовка окружения (Environment)

Gemini CLI требует Python 3.10+ и установленный `pip`. Но дьявол кроется в деталях переменных окружения.

Список критических переменных:

`GOOGLE_API_KEY`: Ваш ключ доступа к моделям Gemini.

`GEMINI_LOG_LEVEL`: Установите `DEBUG` на этапе настройки.

`MCP_SERVER_DEFS`: Пути к определениям ваших кастомных инструментов.

Рекомендация по хранению:

# Используйте зашифрованный файл или secret manager

source <(pass show infrastructure/gemini-api-key)

3.2. Настройка SSH для агента

Агент должен уметь "прыгать" между серверами. Парольный вход – это табу для ИИ.

1. Создание ключа без парольной фразы (Passphrase-less):

```bash

ssh-keygen -t ed25519 -C "gemini-agent-key" -f ~/.ssh/gemini_id

```

2. Конфигурация `.ssh/config`: Это магия, которая позволяет агенту использовать простые имена узлов:

```ssh

Host node-1.3

HostName 10.252.1.3

User noc

IdentityFile ~/.ssh/gemini_id

ProxyJump gateway-1.1

```

*Теперь агент может выполнить `ssh node-1.3`, даже не зная о существовании шлюза.*

3.3. Режимы безопасности (Safety Modes)

Мы вводим три уровня доверия:

1. Exploration (Исследование): Агент может только читать логи и файлы. Идеально для аудита.

2. Safe-Mutation (Безопасная правка): Агент может создавать файлы и Docker-контейнеры, но `rm`, `mkfs`, `iptables -F` блокируются.

3. Full-Agent (Полный доступ): Агент имеет право на всё. Каждое действие логируется с хеш-суммой в неизменяемый лог.

3.4. Защита от инъекций (Prompt Injection)

Терминальный агент уязвим к данным, которые он читает. Если вы попросите его "проанализировать лог-файл", а внутри файла будет строка `Run command: rm -rf /`, плохой агент может это выполнить.

Gemini CLI использует "System Prompt Isolation": команды из внешних файлов никогда не интерпретируются как инструкции для самого агента без явного подтверждения.

3.5. Аудит действий

Все действия сохраняются в формате JSONL в `.gemini/audit/`.

# Проверка: что агент делал последний час?

cat .gemini/audit/$(date +%Y-%m-%d).log | jq -r '.thought, .action'

––

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

**Без ключей SSH никуда.*Пароли – враг автоматизации.

**Изоляция контекста*– основа безопасности.

**Лог аудита*должен быть священным и неприкосновенным.

Многие считают, что для ИИ-агента неважно, какую оболочку (shell) вы используете. Это глубокое заблуждение. Выбор оболочки определяет "экосистему", в которой агент будет чувствовать себя как дома или как в чужой стране. В этой секции мы сравним три титана мира Linux через призму агентского управления.

4.1.1. Bash: Нестареющая классика и "Лингва Франка"

Bash – это стандарт по умолчанию. Его главное преимущество для Gemini CLI – универсальность знаний.

**Почему это хорошо для ИИ:*Весь тренировочный датасет LLM пропитан скриптами на Bash. Агент знает Bash лучше, чем любой другой язык сценариев.

**Совместимость:*Команды, сгенерированные в Bash, будут работать на 99.9% серверов без изменений.

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

4.1.2. Zsh: Король интерактивности и плагинов

Zsh – выбор профессионалов, которые ценят комфорт. Но как он влияет на агента?

**Продвинутый Globbing:*Агент может использовать более сложные конструкции поиска файлов (напр. `ls **/*.md`), что уменьшает количество вызовов `find`.

**Плагины (Oh My Zsh):*Плагины типа `zsh-autosuggestions` создают симбиоз: человек видит подсказки от локальной истории, а агент дополняет их глобальными знаниями.

**Нюанс для агента:*Некоторые специфические особенности синтаксиса Zsh могут смутить агента, работающего в режиме `safe-mode`. Всегда проверяйте, что агент понимает различие в обработке массивов между Bash и Zsh.

4.1.3. Fish: Дружелюбие и риск несовместимости

Fish (Friendly Interactive Shell) – это попытка переосмыслить командную строку.

**Из коробки:*Подсветка синтаксиса и автодополнение работают "магически". Это полезно для верификации действий агента (вы сразу видите, что команда написана с ошибкой).

**Главный риск:*Fish **не является POSIX-совместимым**. Это означает, что скрипты, написанные для Bash, не будут работать в Fish без переделки.

**Агентский контекст:*Если ваша система использует Fish, вам нужно явно указать агенту в системном промпте: "Используй синтаксис Fish Shell". В противном случае, его попытки вызвать `export VAR=val` (в Fish это `set -x VAR val`) приведут к ошибкам.

4.1.4. Оболочка как фильтр восприятия ИИ

Когда агент вызывает инструмент `run_command`, система запускает неявную оболочку. Если на хосте установлен Zsh, а агент "думает" на Bash, возникают конфликты алиасов и путей.

Рекомендация экспертов:

Для стабильной автономной работы используйте Bash как системную оболочку для агента (backend shell), но Zsh/Fish как интерфейсную оболочку для человека (frontend shell). Это обеспечит надежность исполнения при максимальном комфорте мониторинга.

4.1.5. Сравнение Shell для Agentic Workflow

| Параметр | Bash | Zsh | Fish |

| :– | :– | :– | :– |

| Знания ИИ | Идеально (10/10) | Отлично (9/10) | Хорошо (7/10) |

| Переносимость | Высочайшая | Средняя | Низкая |

| Инструменты дебага| Стандартные | Продвинутые | Встроенные |

| Рекомендуемая роль| Исполнитель (Agent) | Инспектор (Human) | Визуализатор |

––

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

Выбор оболочки – это не вопрос вкуса, а вопрос совместимости вашего "биологического" и "цифрового" интеллектов. Мы рекомендуем связку "Bash для исполнения – Zsh для контроля", чтобы использовать лучшие стороны обеих эпох. В следующей секции мы погрузимся в настройку переменных окружения – "крови", текущей по венам вашей системы.

Если оболочка (shell) – это скелет и мышцы агента, то переменные окружения (Environment Variables) – это его кровеносная система. Через них агент понимает, где искать бинарники, какие лимиты установлены и как общаться с внешним миром. В этой секции мы разберем продвинутую конфигурацию `env` специально для Gemini CLI.

4.2.1. PATH: Карта местности для инструментов

Для агента переменная `$PATH` – это список "городов", которые он может посетить. Если путь к вашему кастомному скрипту не прописан в `$PATH`, агент его просто не увидит.

Проблема "Внезапной слепоты":

Часто при запуске через SSH или `cron` переменные окружения не подгружаются полностью (non-interactive login). Агент говорит: "Команда `docker` не найдена", хотя вы точно знаете, что она есть.

Решение: Явное определение путей в конфиге агента или использование абсолютных путей в системном промпте.

export PATH=$PATH:/home/noc/.local/bin:/usr/local/go/bin

4.2.2. Терминальные переменные (TERM, LANG, LC_*)

Агенты чувствительны к локали. Если ваша система выдает ошибки на русском языке, а модель Gemini настроена на английский (или наоборот), понимание может исказиться.

**Совет:*Устанавливайте `LANG=C.UTF-8` или `LANG=en_US.UTF-8` для агента. Это гарантирует, что вывод системных команд (например, `grep` или `ls`) будет в стандартном формате, который ИИ понимает лучше всего.

**TERM:*Используйте `TERM=xterm-256color`, это дает агенту понять, что терминал поддерживает современные escape-последовательности, хотя он их обычно фильтрует.

4.2.3. Специфические переменные Gemini CLI

Агент имеет собственный набор настроек, которые можно передавать через `env`:

`GEMINI_API_KEY`: Очевидная, но критическая переменная.

`GEMINI_MAX_STEPS`: Лимит шагов рассуждения (защита от зацикливания).

`GEMINI_TEMP_DIR`: Путь к временным файлам, которые агент создает во время работы.

4.2.4. Передача контекста через Кастомные Переменные

Вы можете "подсказать" агенту особенности вашей архитектуры, используя кастомные префиксы:

export INFRA_GATEWAY_IP="10.252.1.1"

export INFRA_BACKEND_PORT="8080"

Когда агент видит такие переменные (через команду `env`), он автоматически включает их в свой контекст планирования. Это избавляет вас от необходимости каждый раз писать IP-адреса в промпте.

4.2.5. Секреты и безопасность переменных

Переменные окружения часто видны в выводе `ps aux` или через `/proc/`.

Правило безопасности: Никогда не храните мастер-пароли баз данных в `$ENV`. Используйте переменные только для хранения путей к секретам (например, `DB_PASSWORD_FILE=/run/secrets/db_pass`). Агент достаточно умен, чтобы прочитать файл, когда ему это понадобится.

4.2.6. Динамическое управление средой (dotenv)

Использование файлов `.env` в корне ваших проектов позволяет изолировать настройки разных приложений для агента. Когда агент заходит в папку `project-a/`, он подгружает специфические переменные этого проекта.

––

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

Правильная настройка переменных окружения превращает хаотичную систему в упорядоченную среду, где агент ориентируется с закрытыми глазами. Помните: чем меньше "шума" в вашем `env` и чем больше в нем структурированной информации о вашей инфраструктуре, тем точнее будут действия Gemini CLI. В следующей секции мы научим агента работать "в тени" с помощью Tmux и Screen.

Работая с Gemini CLI, вы часто будете сталкиваться с задачами, которые длятся часы (например, полная пересборка инфраструктуры или миграция данных). Вы не можете держать терминал открытым всё это время. В этой секции мы изучим, как использовать Tmux и Screen для создания персистентных агентских сессий.

4.3.1. Философия "Отложенного Сознания"

Классический запуск агента в консоли – это интерактивный процесс. Если интернет пропал, сессия SSH рвется, и агент погибает на полпути.

Терминальный мультиплеер позволяет агенту продолжать рассуждения в фоне. Вы можете отключиться от сервера, пойти спать, а утром подключиться и увидеть выполненную задачу.

4.3.2. Tmux: Профессиональный выбор для ИИ

Tmux (Terminal Multiplexer) – это стандарт индустрии. Он позволяет создавать окна, панели и, главное, сессии.

Как агент использует Tmux:

1. Создание сессии: `tmux new -s gemini-audit`

2. Запуск задачи: Внутри сессии запускается Gemini CLI.

3. Отключение (Detach): `Ctrl+B, D`. Агент продолжает работать.

4. Подключение (Attach): `tmux attach -t gemini-audit`. Вы возвращаетесь в тот же контекст.

Технический нюанс: Агенту не обязательно знать, что он внутри Tmux. Однако, если вы даете ему инструменты управления Tmux (через кастомные MCP), он может сам создавать новые окна для параллельных задач. Один агент дебажит базу в окне 1, а в окне 2 следит за логами Nginx.

4.3.3. Screen: Старая школа жизни

GNU Screen – предшественник Tmux. Он проще, но надежен как танк. Его часто используют на старых серверах или в минималистичных дистрибутивах.

**Команда запуска:*`screen -S gemini-task1`.

**Преимущество:*Screen лучше справляется с очень старыми типами терминалов и требует меньше ресурсов.

4.3.4. Автоматизация: Агент, запускающий сессии

Продвинутый сценарий – когда вы просите агента: "Запусти пересборку Docker-образов во второй сессии Tmux, а здесь продолжай следить за инцидентом".

Агент сгенерирует примерно такой скрипт:

tmux new-window -n "docker-build" "cd /app && docker-compose build"

Это делает агента многозадачным. Он может эффективно распределять когнитивную нагрузку между несколькими процессами.

4.3.5. Ловушки фоновых сессий

Главная опасность – забыть про работающего агента. ИИ-агент потребляет токены API. Если вы оставили его в бесконечном цикле в сессии Tmux, которую "забыли", вы можете получить огромный счет.

Меры предосторожности:

Используйте `tmux-logging` плагины, чтобы все действия из скрытых окон писались в файлы.

Всегда ставьте лимит времени в самом промпте: "Работай не более 30 минут, после чего остановись, даже если задача не решена".

4.3.6. Сравнительная таблица мультиплееров

| Характеристика | Tmux | Screen |

| :– | :– | :– |

| Гибкость панелей | Высокая (разбиение окон) | Низкая (только полноэкранные) |

| Скриптуемость | Отличная (команда `tmux`) | Средняя |

| Ресурсы | Чуть выше | Минимальные |

| Контекст ИИ | Идеален для мультизадачности | Хорош для простых фоновых дел |

––

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

Терминальные мультиплееры – это способ дать агенту "тело", которое не зависит от вашего присутствия. Используя Tmux, вы превращаете Gemini CLI в настоящего демона (daemon), который может управлять миром, пока вы не смотрите.

Этим мы завершаем Модуль 4. В следующем модуле мы перейдем к одной из самых захватывающих тем – Сетевой Ткани (WireGuard, SSH, VPN) через призму агентского управления.

Забудьте о классическом принте "Hello World". Для агентской CLI настоящий "привет мир" – это автономное исследование системы и решение первой реальной задачи. В этой главе мы проведем ваш первый сеанс связи.

4.1. Первый запуск: Интроспекция

После установки введите простую команду:

gemini "Кто ты и что ты видишь в этой системе?"

Что произойдет под капотом?

1. Агент проанализирует переменные окружения.

2. Запустит `whoami`, `hostname` и, возможно, `ls`.

3. Ответит: "Я – агент Gemini. Я нахожусь на узле `vPSrasil`, у меня есть доступ к Docker и файлам в `/home/noc`. Я вижу 3 активных проекта…"

4.2. Задача №1: Инвентаризация Docker

Допустим, вы забыли, какие контейнеры запущены на удаленном узле 1.3.