От чата к агенту: как настроить OpenCode в Selectel для автономной работы с кодом

# От чата c LLM к полноценному AI-агенту: пошаговая настройка OpenCode

Когда использование искусственного интеллекта в работе ограничивается открытием чата и формированием текстового запроса, потенциал модели быстро достигается пределом. Языковая модель не обладает знанием внутренней документации, не видит контекста проекта и каждый раз требует повторного объяснения правил команды. Следующим логичным шагом становится создание рабочей среды, в которой агент получает доступ к файлам, инструкциям и локальным инструментам. В данной статье рассматривается настройка OpenCode — оболочки, позволяющей LLM интегрировать свои возможности в реальные рабочие процессы.

Приветствую. Я Арина, аналитик в Selectel. Цель этого материала — не просто показать установку программного обеспечения, а продемонстрировать архитектуру рабочего пространства, обеспечивающего стабильность результатов и безопасность операций.

Архитектура конфигурации: глобальное и локальное

Первым этапом является подключение «мозгов» — выбора провайдера языковой модели. Для личных проектов доступны внешние API с простыми настройками через ключи. Однако для корпоративных проектов приоритетом становится соблюдение внутренней политики безопасности: какие модели разрешены, можно ли передавать код внешним сервисам и как защитить конфиденциальные данные. Если компания использует развернутую локальную LLM, она может быть подключена к OpenCode без риска утечки информации.

Ключевым принципом настройки является разделение конфигурации на два уровня:

1. Global config (Глобальная конфигурация): Хранится в ~/.config/opencode/. Сюда выносятся общие настройки провайдеров, модели, универсальные инструкции и навыки (skills), используемые во всех проектах. Например, файл opencode.json определяет лимиты контекста для различных моделей (glm-5.3, kimi-k2.6) и базовые разрешения. 2. Project config (Конфигурация проекта): Находится в репозитории или workspace конкретного проекта. Здесь прописываются архитектурные ограничения, команды сборки, документация и специфичные навыки. Это предотвращает дублирование правил и позволяет каждому проекту иметь свои уникальные инструкции.

Роль файла AGENTS.md

Файл AGENTS.md служит для хранения правил, которые должны применяться практически всегда. В него включают требования не выдумывать факты, изучать связанную реализацию перед изменением кода и не выполнять действия деплоя (commit, push, merge) без явного разрешения. Важно сохранять этот файл лаконичным, так как перегруженные инструкции усложняют поддержку. Вместо дублирования правил в каждый проект, глобальная конфигурация обеспечивает базовый вектор поведения, а проектные файлы уточняют детали.

Навыки и команды (Skills и Commands)

Чтобы избежать повторного объяснения одних и тех же алгоритмов, их выносят в специальные блоки.

* Skills: Файлы типа SKILL.md в директории .opencode/skills описывают последовательность действий для специфических задач. Например, навык code-review может включать шаги: изучение измененных файлов, проверка вызовов, поиск регрессий и контроль тестов. * Commands: Используются для четких последовательностей действий по одной короткой команде. Команда /fix-bug может автоматически запускать алгоритм: анализ описания бага, поиск кода, определение причины, предложение решения, запуск тестов и вывод diff. Это освобождает пользователя от описания рутинных шагов вручную.

Доступ к внешним источникам и безопасность

Эффективный агент должен знать не только код в текущем репозитории, но и информацию из таск-трекеров, баз знаний и Git-репозиториев. Для этого используется либо MCP-серверы, либо прямой доступ через REST API.

На собственном опыте с GitLab было установлено важное правило: не следует усложнять систему ради MCP. В ходе настройки возникли проблемы с возвращаемой схемой инструментов, требующие создания обёрток, что не всегда срабатывало. Оказалось, что штатный REST API GitLab решает задачи поиска проектов, чтения файлов и анализа маршрутов быстрее и стабильнее. Вывод прост: если традиционный API или локальный скрипт эффективны, их использование предпочтительнее сложной интеграции через MCP.

Код как источник контекста

Одним из мощнейших сценариев является использование реальной кодовой базы как источника фактов. Агент может самостоятельно проверить существующие модели данных, валидации и обработку ошибок. Запрос в формате «Изучи реализацию создания пользователя и определи изменения для поля department_id» позволяет агенту опираться на факты из кода, а не только на текст описания задачи.

Ограничения и безопасность прав доступа

Самая критичная часть настройки — это управление правами доступа. Существует фундаментальное различие между текстовой инструкцией «не делай push» и техническим запретом выполнения команды git push. ИИ-модель может проигнорировать текстовый промт, но обойти программный запрет прав доступа не сможет.

Рекомендуется применять принцип минимально необходимых прав: * Read-only: Использовать токены и доступы только для чтения там, где это возможно (например, для анализа Jira или документации). * Ask: Выставлять режим ask для редкого использования shell-команд, чтобы пользователь подтверждал опасные действия. * Deny: Запрещать опасные операции в глобальной конфигурации (например, git push), если работа с файлами не критична.

Управление секретами

Секреты, такие как токены доступа, должны храниться в отдельных файлах или переменных окружения, а не в workspace проекта. В Windows это реализуется через Environment::SetEnvironmentVariable. Однако важно понимать, что переменные окружения не заменяют полноценное хранилище секретов. Для защиты от неавторизованного доступа используются: минимальные scope-ы токенов, отдельные ключи для разных сервисов и отсутствие секретов в логах.

Практическая пошаговая настройка

Для тех, кто начинает работу с AI-агентами с нуля, рекомендуется следующий порядок действий:

1. Подключение LLM: Убедиться, что OpenCode успешно взаимодействует с выбранной моделью и может ответить на базовый запрос (например, прочитать README). 2. Базовый глобальный конфиг: Настроить минимальные права в ~/.config/opencode/opencode.json, включив подтверждение (ask) перед редактированием файлов или выполнением команд shell, и отключив автоматический шеринг. 3. Создание AGENTS.md: Добавить в корень проекта файл с базовыми правилами: запрещать выдумывать факты, требовать изучения кода перед изменениями и запрещать деплой без разрешения. 4. Тестирование на реальных задачах: Провести серию запросов по анализу endpoint-ов и поиску ошибок. Создание навыков (skills) должно происходить только тогда, когда один и тот же алгоритм требуется объяснять неоднократно. 5. Разработка первого навыка: Создать структуру .opencode/skills/code-review/SKILL.md, описывающую пошаговую проверку изменений. 6. Интеграция внешних источников: Добавлять подключения к Jira, Confluence или GitLab только по мере необходимости.

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

*Примечание: Написание таких правил требует времени и дисциплины, но результат — автоматизация рутинных процессов и снижение риска человеческих ошибок — оправдывает вложенные усилия.*