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

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

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

Следующим моим шагом стало собрать вокруг модели рабочую среду. В моем случае такой средой стал OpenCode. Хотя этот агент в первую очередь ассоциируется с разработкой, его можно использовать гораздо шире. По сути, это оболочка, в которой LLM получает доступ к файлам, инструкциям, локальным инструментам, API и MCP-серверам, а затем использует все это для решения задач конкретного пользователя.

Привет, Хабр! Я Арина, аналитик в Selectel. В этой статье я покажу не столько «как установить OpenCode», сколько как организовать вокруг него рабочее пространство, чтобы агент выдавал более стабильный результат и действительно снимал часть рутинной работы.

Подключаем модель

Для личных и pet-проектов можно подключить удобного внешнего провайдера — OpenCode поддерживает множество моделей. В настройках доступен список популярных провайдеров, для которых даже не надо ничего настраивать — просто скопируйте API ключ из вашего любимого сервиса и пользуйтесь.

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

Если у вас в компании или на личной машине развернута локальная LLM, которая точно не передаст все ваши конфиденциальные данные злоумышленникам, то вы также можете подключить ее в OpenCode. Для этого нажмите Настройки → Провайдеры → Выбрать провайдера → Подключить.

Заполните поля:

• ID провайдера,

• Отображаемое имя,

• Базовый URL,

• Ключ API,

• Доступные модели.

Дальнейшие настройки агента практически не зависят от конкретного провайдера или мощности модели. Цель первого этапа — подключить «мозги», куда дальше будут загружаться знания. Поэтому на этом шаге вы можете подключить любую удобную модель или даже использовать встроенные, коротким сообщением проверив, что агент отвечает и не выдает ошибку.

Разделяем global config и настройки проекта

Следующим шагом я рекомендую сразу разделить конфигурацию на два уровня.

Global config

Общие настройки пользователя:

~/.config/opencode/
├─ opencode.json
├─ AGENTS.md
└─ skills/

Сюда удобно вынести провайдеров и модели, общие разрешения (permissions), универсальные инструкции и skills, используемые во всех проектах.

Пример opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "your_model": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "your_model",
      "options": {
        "baseURL": "https://ai.your_model.org/api",
        "apiKey": "$apiKey"
      },
      "models": {
        "glm-5.3": {
          "name": "glm-5.3"
          "limit": {
            "context": 262000,
            "output": 66000
        },
        "kimi-k2.6": {
          "name": "kimi-k2.6"
          "limit": {
            "context": 203000,
            "output": 66000
        }
      }
    }
  },
  "mcp": {
 },
  "model": "your_model/glm-5.3",
  "small_model": "your_model/kimi-k2.6",
  "default_agent": "plan"
}

Project config

В репозитории или отдельном workspace остается то, что относится к конкретному проекту:

project/
├─ AGENTS.md
├─ opencode.json
├─ docs/
├─ contexts/
├─ scripts/
└─ .opencode/
   ├─ skills/
   ├─ commands/
   └─ agents/

Здесь прописываются архитектурные ограничения, команды сборки и тестирования, документация, инструкции по работе с репозиторием и project-specific skills. Такое разделение позволяет глобальной конфигурации не дублироваться между проектами, а проектным правилам — не превращаться в один огромный общий промт.

AGENTS.md

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

Не стоит складывать сюда все инструкции проекта. Чем объемнее AGENTS.md, тем сложнее поддерживать его актуальность и понимать, какие правила действительно важны.

Skills

Если один и тот же алгоритм приходится регулярно объяснять агенту, его лучше вынести в skill. Например:

.opencode/
└─ skills/
   ├─ code-review/
   │  └─ SKILL.md
   ├─ api-analysis/
   │  └─ SKILL.md
   └─ debugging/
      └─ SKILL.md

Так, skill для code review может задавать последовательную проверку: сначала агент изучает измененные файлы, затем проверяет связанные вызовы, ищет возможные регрессии, контролирует обработку ошибок и наличие тестов, а в конце выводит найденные проблемы и рекомендации.

Commands

Commands удобны, когда важна не только инструкция, но и четкая последовательность действий. Например, команда /fix-bug может запускать следующий алгоритм:

1. Изучи описание бага. 2. Найди связанный код. 3. Определи вероятную причину. 4. Предложи решение. 5. После подтверждения измени код. 6. Запусти тесты. 7. Покажи итоговый diff и возможные риски.

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

ИИ‑роутер — доступ к 300+ моделям из одной панели

Подключите OpenAI‑совместимый шлюз по единому API‑ключу. Настраивайте сквозную аналитику, отслеживайте лимиты и квотируйте ресурсы.

Запустить ИИ‑роутер →

Разные агенты для разных задач

Если конфигурация разрастается, полезно разделить роли, создав отдельных агентов, выполняющих ограниченный набор задач. Например, набор может выглядеть так: developer, reviewer, researcher и docs. У них будут отличаться доступные инструменты, модель, промпт, permissions и skills.

Так, скажем, агент reviewer может работать только в режиме read-only, а developer — иметь доступ к изменению файлов. Это удобнее и безопаснее, чем давать одному универсальному агенту максимальные права.

Подключаем документацию и рабочие системы

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

Можно каждый раз копировать данные вручную, но тогда значительная часть преимуществ агента теряется. Через MCP или API ему можно дать доступ к дополнительным источникам знаний, включая GitLab, GitHub, Jira, Confluence, внутренние API и сервисы документации.

Тогда становится возможен сценарий вроде такого:

Прочитай задачу → найди связанную документацию → изучи текущую реализацию → найди необходимые изменения.

На собственном опыте с GitLab я убедилась, почему не стоит строить всю архитектуру исключительно вокруг MCP.

Сначала я пыталась подключить его через MCP-сервер. В моей конфигурации на момент настройки сервер запускался, но при получении списка инструментов (tools) возникала проблема: возвращаемая схема не соответствовала той, которую ожидал OpenCode. Я попробовала нормализовать ее через дополнительный wrapper, но это не сработало, и я решила, что уходить в долгую борьбу с MCP нет никакого смысла.

К тому же штатный GitLab REST API уже закрывал все мои задачи: поиск проекта, чтение файлов, просмотр структуры репозитория и README, анализ маршрутов (routes), моделей и миграций. Вывод тут простой: если REST API или обычный локальный скрипт решает задачу быстрее и стабильнее, лучше использовать их и не усложнять систему на ровном месте.

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

Один из самых полезных сценариев работы с OpenCode лично для меня — возможность изучить реальную кодовую базу перед ответом.

Например, агент может самостоятельно проверить существующие модели данных, используемые поля, валидации, API endpoints, обработку ошибок, существующие тесты и ограничения legacy-кода. Вместо запроса в формате «Вот DTO, вот контроллер, вот модель, а теперь скажи, как добавить новое поле» можно сформулировать задачу так:

Изучи текущую реализацию создания пользователя и определи, какие части системы потребуется изменить, если добавить обязательное поле department_id.

В таком случае код используется как источник фактов, на которые можно опираться при описании нового функционала. В следующей своей статье я как раз хочу подсчитать, насколько получилось ускорить и оптимизировать работу по анализу требований за счет активного использования агента. Спойлер: цифры получаются очень даже впечатляющими!

Ограничения лучше задавать технически

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

Инструкцию LLM может нарушить: неправильно понять запрос, потерять часть контекста или выбрать неправильное действие. Поэтому я придерживаюсь принципа минимально необходимых прав: при необходимости читать GitLab или анализировать Jira — использовать токены и доступы read-only. Для редкого использования shell выставлять режим ask. А при отсутствии работы с файлами устанавливать deny (ниже будет приложен пример кода).

Не храните токены в workspace

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

Например, в Windows настройка будет выглядеть так:

[Environment]::SetEnvironmentVariable(
    "GITLAB_TOKEN",
    "<token>",
    "User"
)

После этого скрипты и интеграции используют имя переменной только при необходимости обращения к конкретному сервису.

Но здесь тоже важно не поддаваться ложному ощущению безопасности: переменные окружения защищают ключи от случайного попадания в репозиторий, но не заменяют собой полноценное хранилище секретов. Любой процесс, у которого есть доступ к переменной, потенциально может ее прочитать.

Поэтому в связке с переменными окружениями желательно использовать комплексную защиту:

• минимально необходимые права (scopes);

• отдельные токены для разных сервисов или агентов;

• доступ read-only везде, где нет необходимости для более высокого уровня прав;

• отсутствие секретов в логах;

• permissions самого OpenCode;

• правила вашей компании — учитывайте внутренние политики безопасности.

Только так возможно создать безопасный контур для работы агента и не попасть на радар бдительных коллег из отдела ИБ.

Как я бы настраивала OpenCode с нуля сейчас

Если вы раньше не работали с AI-агентами, лучше не начинать сразу с MCP, нескольких агентов и десятка skills. Соберите минимальную конфигурацию, проверьте ее на реальной задаче и только потом добавляйте инструменты.

Шаг 1. Подключите LLM

Сначала достаточно добиться простой цепочки: OpenCode → выбранная LLM → ответ. На этом этапе проверьте, что OpenCode видит текущий проект и может ответить, например:

Прочитай README текущего проекта и кратко объясни, что делает этот сервис.

Шаг 2. Добавьте базовый global config

Общие настройки OpenCode хранятся в ~/.config/opencode/opencode.json.

Для старта достаточно минимальной конфигурации:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },
  "share": "disabled"
}

Так OpenCode будет спрашивать подтверждение перед изменением файлов и выполнением shell-команд, а автоматический sharing будет отключен.

Если хотите сразу запретить потенциально опасные Git-команды, добавьте:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git diff *": "allow",
      "git commit *": "deny",
      "git push *": "deny"
    },
    "edit": "ask"
  },
  "share": "disabled"
}

Шаг 3. Создайте минимальный AGENTS.md

В корне проекта добавьте файл AGENTS.md и дайте стартовую инструкцию:

# Общие правила

- Не придумывай отсутствующие факты.
- Перед изменением кода сначала изучи существующую реализацию.
- Если задача неоднозначна — задай уточняющие вопросы.
- Не выполняй commit, push и merge без явного разрешения.
- После изменений перечисли затронутые файлы и возможные риски.

Этого уже достаточно, чтобы задать базовое поведение агента.

Шаг 4. Проверьте агента на реальной задаче

Не создавайте skills заранее. Сначала попробуйте несколько обычных запросов:

Изучи обработку этого endpoint. Покажи основные сценарии ошибок и связанные тесты.

Если один и тот же алгоритм приходится объяснять повторно — тогда его уже стоит вынести в skill.

Шаг 5. Создайте первый skill

Например, для code review создайте:

.opencode/
└── skills/
    └── code-review/
        └── SKILL.md

И положите в SKILL.md:

---
name: code-review
description: Проверка изменений в коде на ошибки, регрессии и отсутствие тестов
---

# Code review

1. Изучи измененные файлы.
2. Проверь связанные вызовы и зависимости.
3. Найди возможные регрессии.
4. Проверь обработку ошибок.
5. Проверь наличие тестов.
6. Не предлагай изменения, не связанные с задачей.
7. В конце выведи найденные проблемы и рекомендации.

OpenCode автоматически обнаруживает skills в .opencode/skills/<name>/SKILL.md. Для skill нужны name и description, чтобы агент мог корректно определить, когда его использовать.

Шаг 6. Подключите внешние источники

Когда станет понятно, какой информации агенту не хватает, добавляйте конкретную интеграцию. Каждая система закрывает свой пласт знаний: Jira дает контекст по задачам, Confluence — по документации, а GitLab или GitHub открывают доступ к репозиторию. Если же агенту нужно дотянуться до внутренних сервисов компании, подтяните их через REST API или MCP.

В итоге рабочая архитектура полноценного самостоятельного агента выглядит так:

Этого уже достаточно, чтобы перейти от обычного чата с LLM к агенту, который знает правила проекта, умеет самостоятельно собирать локальный контекст и может выполнять повторяемые задачи.

А в остальном пробуйте новые сценарии, ищите или пишите сами полезные скиллы и помните о безопасности, потому что искусственный интеллект даже проще обмануть, чем естественный!