# Базовые понятия Opencode и начало работы

Svartsinn1

Svartsinn1

Базовые понятия Opencode и начало работы

Origin: http://samlib.ru/s/svartsinn1/bazowyeponjatijaopencodeinachaloraboty.shtml

Создан: 20/08/2026, изменен: 20/08/2026, 32k

Статья: Нет

____________________________________________________________

## Системный взгляд на Opencode: основные понятия и связи между ними

Представьте, что вы наняли очень умного помощника, который умеет читать код, писать программы, искать файлы и общаться с внешними сервисами. Этот помощник работает в терминале, сидит рядом с вашим проектом и готов выполнить почти любую задачу по программированию. Звучит как фантастика, но именно так устроен Opencode - открытый AI-агент для разработки, который существует как приложение для терминала, десктоп или расширение для IDE.

За этой простой картинкой скрывается сложная система из десятков понятий. Там есть модели, агенты, скиллы, провайдеры, MCP-серверы, токены, контекстные окна и контейнерные оркестраторы. Каждое слово по отдельности понятно, но без системы они превращаются в кашу. Эта статья - попытка собрать их в одну картину, чтобы вы поняли не только термины, но и связи между ними.

Я разберу Opencode как набор слоёв: от большой языковой модели внизу до оркестрации агентов сверху. Пройду по каждому уровню, объясню простыми словами и покажу, как части цепляются друг за друга. В конце вы увидите не список фич, а живую архитектуру, в которой у каждого винта есть своё место.

### Что вообще такое Opencode

Opencode - это не одна программа, а связка из нескольких компонент. Снизу лежит языковая модель, которая умеет продолжать текст и вызывать функции. Выше - агент, который оборачивает модель в цикл "получил задачу - подумал - вызвал инструмент - проверил результат". Ещё выше - интерфейс (терминальный TUI, веб, IDE), через который пользователь разговаривает с агентом. И наконец, по бокам висят инструменты: чтение файлов, bash, поиск, MCP-серверы, скиллы.

Такая слоистая архитектура позволяет заменять части без переписывания целого. Хотите другую модель - переключаете провайдера. Не нравится интерфейс - берёте десктоп вместо терминала. Нужно добавить доступ к Jira - подключаете MCP-сервер. В этом и есть системная идея: ядро остаётся, периферия меняется.

Всё это описывается конфигурацией в файле opencode.json или opencode.jsonc. Там задаётся, какая модель стоит по умолчанию, какие MCP-серверы подключены, какие агенты доступны, какие у них права. На проекте ещё создаются файлы AGENTS.md и SKILL.md - они помогают агенту понять проект и подгрузить специализированные сценарии.

### Модель, провайдер и варианты

Модель - это, грубо говоря, большой математический объект, который научили предсказывать следующий токен в тексте. Именно она и есть "мозг". Провайдер - это место, где модель живёт и откуда вы её вызываете. Это может быть Anthropic, OpenAI, Google, локальный Ollama или LM Studio. В конфиге модель записывается как пара provider/model-id, например anthropic/claude-sonnet-4-5-20250929 или ollama/llama2.

Модели делятся на классы. Есть большие коммерческие модели (Claude, GPT, Gemini) - они сильные, но платные и закрытые. Есть открытые модели (Llama, Qwen, DeepSeek, Gemma) - их можно скачать и крутить у себя. По характеру работы модели различаются на "думающие" (reasoning) и "быстрые". Думающие модели тратят токены на внутренние рассуждения и дают более глубокие ответы, быстрые - отвечают сразу, без видимых размышлений.

У многих моделей есть варианты (variants). Один и тот же GPT-5 может запускаться с низкой, средней или высокой нагрузкой на reasoning. В конфиге это выглядит как объект variants с настройками вроде reasoningEffort: "high". Полезно держать под рукой несколько пресетов: "быстрый" для простых правок, "глубокий" для архитектурных задач.

Разворачивание модели зависит от класса. Коммерческая модель требует только API-ключа, который вы получаете через команду /connect. Открытую модель можно поставить локально через Ollama или LM Studio и указать в конфиге baseURL вроде http://localhost:11434/v1. Можно поднять инференс в облаке (Bedrock, Vertex AI, Modal) и обращаться к нему как к провайдеру. Так один и тот же Opencode работает и с облачными гигантами, и с моделями на вашем ноутбуке.

### Что такое веса и что значит "обучить модель"

Внутри любой современной языковой модели лежит нейросеть из множества слоёв. В каждом слое - миллионы искусственных "нейронов", и каждый нейрон соединён с соседними числами, которые называются весами. Вес - это просто число, чаще дробное, например 0.0231 или -1.7844. Эти числа решают, насколько сильно один нейрон влияет на другой. Когда модель "думает", она перемножает входные сигналы на веса, складывает, прогоняет через нелинейные функции и получает выход.

Когда говорят "модель на 70 миллиардов параметров", имеют в виду именно число весов. 70B - это 70 миллиардов дробных чисел внутри сети. Если каждое число хранить как 16-битное число (так называемый FP16), файл весов займёт около 140 ГБ. Если использовать 8-битный формат (INT8) - 70 ГБ. Если 4-битный квантований формат (GGUF Q4) - около 35 ГБ. Поэтому модели и весят гигабайты: это просто огромные таблицы чисел.

Обучение модели - это не загрузка знаний в базу, а медленная подстройка этих миллиардов чисел. Сначала веса инициализируют случайными значениями, потом долго кормят сеть текстами, картинками или кодом, и параметр за параметром она учится предсказывать, что идёт дальше. На выходе получается файл весов в десятки гигабайт - это и есть "обученная модель".

У обучения есть этапы. Претрейн - модель учится на огромном корпусе текстов и становится общей. На этом этапе тратится основное количество вычислений: GPT-4-класса модели обучают тысячи GPU-часов на тысячах миллиардов токенов. Дообучение (fine-tuning) - модель заново кормят узкими данными, чтобы она стала, например, лучше писать код или отвечать на медицинские вопросы. Это в сотни раз дешевле, чем претрейн. RLHF или RL - финальная шлифовка, когда модель учат поощрению от людей или от другой модели, чтобы ответы были безопасными и полезными.

Для пользователя Opencode это означает простую вещь: вы не обучаете модель сами. Вы выбираете готовую, уже обученную кем-то, и просто подаёте ей свои промпты. Если нужно специализированное поведение, вы тонко настраиваете не модель, а промпт агента или скилл. Это дешевле и быстрее, чем дообучение, и не требует GPU.

### Какое железо нужно для моделей

Для обучения больших моделей нужна серьёзная инфраструктура. Типичный кластер - это сотни или тысячи GPU, соединённых быстрой сетью (InfiniBand, NVLink). Один NVIDIA H100 стоит около 30 000 долларов, и для обучения модели уровня GPT-4 нужны тысячи таких карт. Счёт идёт на десятки миллионов долларов за один прогон. Поэтому обучение моделей удел нескольких крупных лабораторий: OpenAI, Anthropic, Google, Meta, Mistral, DeepSeek.

Для дообучения (fine-tuning) открытой модели хватает скромного железа. LoRA - метод, при котором замораживают основные веса и обучают только маленькие "довески" на несколько десятков миллионов параметров. Это влезает в одну GPU на 24 ГБ видеопамяти (RTX 4090), и стоит в часах, а не в неделях. Большие техники вроде QLoRA позволяют дообучать модель 70B на одной 80 ГБ-карте A100. Для совсем маленьких моделей (7B-8B) хватит карты на 16 ГБ.

Для инференса - то есть когда модель уже обучена и вы просто спрашиваете её вопросы - требования зависят от размера и квантования. Модель 7B в формате Q4 влезает в 6 ГБ видеопамяти, её можно крутить на RTX 3060 или даже на Apple M2 с Unified Memory. Модель 70B в Q4 занимает 40 ГБ, ей нужна A100 80 ГБ или H100 80 ГБ, или пара RTX 4090 с объединением через accelerate. Самые большие модели (400B+) требуют мульти-GPU серверов или квантования в 2-3 бита с потерей качества.

Хостинг железа тоже бывает разный. Локально - это ваш ноутбук или рабочая станция. Полузакрытый - это специализированные облака типа Lambda Labs, RunPod, Vast.ai, где вы арендуете GPU по часам. Дата-центр - это собственный кластер или AWS p5 / GCP A3 / Azure NDm. Уровень железа выбирается под задачу: для разработки подойдёт локальная 7B, для прод-сервиса нужен кластер с A100 и автоскейлингом.

### Экономика моделей: что и сколько стоит

В Opencode экономика расходится на две статьи: обучение и инференс. Обучение платят создатели модели - это единовременная дорогая инвестиция. Инференс платит пользователь каждый раз, когда делает запрос. Поэтому для большинства команд Opencode реальная статья расходов - это не "создать свою модель", а "сколько мы платим за токены".

Цены на инференс у коммерческих провайдеров указываются за 1 миллион токенов. Условный Anthropic Claude Sonnet 4 берёт около 3 долларов за 1М входных токенов и 15 долларов за 1М выходных. GPT-5 - примерно сопоставимо. Reasoning-модели могут стоить в 3-5 раз дороже, потому что внутренние "размышления" считаются как выходные токены. У открытых моделей цена определяется хостингом: у Together, Fireworks, DeepInfra это обычно 0.5-2 доллара за 1М токенов. Локальная Ollama бесплатна, но вы платите за электричество и амортизацию GPU.

Реальный расход в Opencode считается так: (входные токены × цена входа) + (выходные токены × цена выхода) + (reasoning токены × цена размышления). Один час работы агента на сложной задаче может сжечь 50-200 тысяч входных токенов (промпты, описания инструментов, контекст) и 5-20 тысяч выходных. Это означает 0.5-3 доллара на дорогой модели или копейки на локальной Ollama. Подагенты и MCP-серверы увеличивают расход, потому что каждый подагент начинает с холодного контекста и каждый MCP-инструмент добавляет своё описание в окно.

Экономика диктует выбор архитектуры в Opencode. Для дешёвых рутинных задач ставят маленькую быструю модель (Haiku-класса, GPT-5-nano). Для архитектурных решений и сложного кода - тяжёлую модель (Sonnet, Opus, GPT-5). Локальную Ollama используют для приватных задач и для разработки самих скиллов и промптов - когда не жалко итерировать. Корпоративный OpenCode Zen - это компромисс: одна подписка, проверенные модели, понятный счёт.

### Коэффициенты настроек модели: температура и её друзья

Когда модель генерирует ответ, у каждого следующего токена есть вероятность. Модель может выдать "кот" с вероятностью 0.7, "собака" с 0.2, "птица" с 0.1. Как из этих вероятностей выбрать конкретный токен - решают коэффициенты семплинга. Они и задают "характер" ответа.

Температура (temperature) - самый известный коэффициент. Это множитель, который делает распределение вероятностей "острее" или "плоское". При температуре 0.0 модель всегда берёт самый вероятный токен - это детерминированный, сухой режим, идеальный для аналитики и кода. При температуре 1.0 распределение становится более плоским, модель может взять и不太 вероятные варианты, и ответ становится креативнее. При 1.5-2.0 модель часто несёт чушь: на каждый токен есть десяток равновозможных продолжений. Температуру называют "теплотой" (warmth): низкая - холодная, строгая модель; высокая - горячая, творческая, но менее предсказуемая.

В Opencode температура задаётся в конфиге агента. Для plan агента логично ставить 0.1 - меньше фантазии, больше анализа. Для build агента - 0.3, чтобы код был правильным, но не каноничным до занудства. Для brainstorm агента подойдёт 0.7-0.8, где креативность важнее точности. Если температура не указана, Opencode использует дефолт модели: у большинства - 0, у Qwen - 0.55.

Top P (или nucleus sampling) - альтернатива температуре. Вместо того чтобы менять форму распределения, модель берёт только токены из верхнего P-процента суммарной вероятности. При top_p = 0.9 модель рассмотрит только токены, которые в сумме дают 90% вероятности, остальное отбросит. Это даёт "безопасную" креативность: модель не улетит в редкие слова, но и не зациклится на одном. Часто top_p и температуру не мешают: выбирают что-то одно.

Top K - ещё один вариант фильтрации. Модель рассматривает только K самых вероятных токенов. top_k = 40 значит: взять топ-40 токенов, остальные выкинуть, среди этих сорока выбрать по распределению. Жёстче, чем top_p, потому что K фиксировано и не зависит от формы распределения.

Max tokens (или max output) - верхний лимит на длину ответа. Модель не может выдать больше этого числа токенов за один ход. Если лимит маленький, длинный ответ обрежется на полуслове. В Opencode для локальных моделей (Ollama, llama.cpp) лимит задаётся в конфиге как "limit": {"output": 65536}, чтобы модель не упиралась в потолок при генерации длинного кода.

Frequency penalty и presence penalty - это штрафы за повторения. Frequency уменьшает вероятность токена, который уже часто встречался в ответе. Presence уменьшает вероятность токена, который уже появлялся хотя бы раз. Это спасает от эффекта "заедания", когда модель повторяет одно и то же слово или фразу. В Opencode эти коэффициенты редко трогают - для кода повторения не так критичны, как для литературного текста.

Reasoning effort - коэффициент, специфичный для reasoning-моделей (GPT-5, Claude с thinking). Он задаёт, сколько модель будет "думать" перед ответом. "reasoningEffort": "high" - долгий путь рассуждений, дорогой и качественный. "low" - короткий, быстрый, дешёвый. В конфиге это задаётся как вариант модели или как опция провайдера. На сложных задачах имеет смысл держать два варианта одной модели: "быстрый" для итераций, "глубокий" для финального решения.

Budget tokens (thinking budget) - у Anthropic Claude с включённым thinking задаётся как {"type": "enabled", "budgetTokens": 16000}. Это явный лимит токенов на размышление. Меньше бюджет - короче "размышление", дешевле. Больше бюджет - модель может дойти до правильного вывода в сложном случае, но дороже. Подбирается экспериментально под тип задач.

Все эти коэффициенты - это не "кнопки включения/выключения", а ручки настройки. Хороший агентский конфиг - это компромисс: температура достаточно низкая, чтобы модель не галлюцинировала, reasoning effort достаточно высокий для архитектурных задач, но не на максимум, чтобы не разориться на токенах. В Opencode можно держать несколько пресетов (через variants) и переключаться между ними по ситуации.

### Почему "теплота" - это ключевая метафора

Температуру часто называют "теплотой" модели, и это не случайность. Физическая аналогия очень точная: при низкой температуре газ "замёрзший" - все молекулы стоят на местах, выход детерминированный. При высокой температуре газ "горячий" - молекулы скачут, выход непредсказуемый. В моделях "тепло" буквально меняет распределение вероятностей так, как будто вы подогреваете систему.

Для пользователя Opencode эта метафора полезна не как красивость, а как способ быстро интуитивно выбрать настройку. Если задача холодная и точная - "напиши миграцию базы данных", "исправь баг по тесту", "сделай code review" - ставьте низкую температуру, около 0.1. Если задача тёплая и творческая - "придумай названия для новых функций", "опиши архитектуру в двух абзацах" - средняя, 0.5-0.6. Если задача горячая и исследовательская - "сгенерируй десять идей для нового модуля", "напиши черновик маркетингового текста" - высокая, 0.8-1.0. Это рабочий способ управлять моделью без понимания математики.

Важно, что температура - это не "включатель умности". Высокая температура не делает модель умнее, она делает её более случайной. Наоборот, на сложных логических задачах высокая температура вредит: модель начинает "прыгать" по вероятностям и попадает в неверные рассуждения. Поэтому для кода и алгоритмов холодная модель почти всегда лучше тёплой. Для креативных задач - наоборот, тёплая лучше, потому что холодная зацикливается на очевидных вариантах.

### Контекст и контекстное окно

Контекст - это весь текст, который модель видит в текущий момент разговора. Сюда входят ваш промпт, системный промпт агента, история сообщений, возвращаемые результаты инструментов, описания доступных инструментов. Когда вы общаетесь с Opencode, контекст растёт с каждым шагом: вы сказали - агент подумал - вызвал инструмент - получил ответ - снова подумал. Всё это накапливается.

У каждой модели есть контекстное окно - максимальный объём текста, который она способна "увидеть" за один раз. Условно говоря, 128 000 токенов или 200 000 токенов. Если контекст превышает это число, его приходится обрезать или сжимать. Поэтому MCP-серверы с большим количеством инструментов буквально съедают окно: каждое описание инструмента лежит в контексте, даже если вы им не пользуетесь.

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

### Токены и на что они тратятся

Токен - это кусочек текста длиной примерно в 3-4 символа. Слово "programming" обычно разбивается на 2-3 токена, слово "кот" - на 1-2. Модель не работает с буквами или словами напрямую, она работает с токенами, и каждый токен представлен числом в её внутреннем словаре.

Токены тратятся на всё. На ваш вопрос - да. На системный промпт агента - да. На каждый вызов инструмента и его ответ - да. На внутренние рассуждения reasoning-моделей - да, и это часто самая большая статья расхода: модель может "продумать" 10 000 токенов, прежде чем выдать короткий ответ. Плюс описания всех MCP-инструментов лежат в контексте и тоже считаются.

Считают токены просто: подсчёт идёт по словарю конкретной модели. Приближённая оценка - 1 токен ≈ 4 символа для английского текста или ≈ 1-2 символа для русского (кириллица дробится мельче). Цена рассчитывается как (входные токены × цена входа) + (выходные токены × цена выхода). У reasoning-моделей добавляется третья статья - токены размышления, и они обычно платные. Поэтому "думающая" модель в Opencode иногда стоит в десятки раз дороже "быстрой" на той же задаче.

### Агенты, подагенты и в чём разница

В Opencode есть два уровня агентов. Первичный агент (primary) - это тот, с кем вы общаетесь напрямую. У него есть полный цикл работы и доступ к инструментам. По умолчанию доступны два: Build (всё разрешено, кодит и правит) и Plan (только планирует, файлы не трогает). Переключаются между ними клавишей Tab.

Подагент (subagent) - это специалист, которого первичный агент вызывает через специальный инструмент Task для узкой задачи. Встроенных три: General (многоцелевой), Explore (быстрый поиск по коду, только чтение), Scout (исследование внешних репозиториев и документации). Подагенты можно вызывать и вручную, через @explore или @general в сообщении.

Разница между агентом и подагентом в режиме работы, а не в "мозге". У обоих может быть та же модель. Но первичный агент ведёт основной разговор, а подагент - запускается на короткое задание, отдаёт результат и выключается. Это позволяет распараллеливать работу: главный агент может запустить несколько подагентов одновременно, например, один ищет в коде, второй копается в документации, третий смотрит PR на GitHub.

Конфигурируется агент в JSON или в Markdown-файле. У него есть описание, режим (primary/subagent), модель, температура, права на инструменты и системный промпт. Markdown-агенты кладутся в ~/.config/opencode/agents/ или в .opencode/agents/ проекта, имя файла становится именем агента. Это делает создание нового агента простым делом: написал review.md с фронматтером - и он уже появился в списке.

### Скиллы: чем они отличаются от агентов

Скилл - это не агент, а инструкция, которую агент подгружает по запросу. Скилл лежит в файле SKILL.md в папке .opencode/skills/<name>/ или в ~/.config/opencode/skills/<name>/. У него есть YAML-фронматтер с name и description, и дальше идёт текст инструкций.

Главное отличие от агента - у скилла нет своего цикла, своей модели или своих прав. Это просто текст, который агент подгружает через инструмент skill, когда понимает, что задача подходит под описание скилла. Например, у вас скилл git-release с описанием "Create consistent releases and changelogs". Агент видит это описание, и если пользователь просит выпустить релиз, он вызывает инструмент skill с именем git-release, и в его контекст загружаются все инструкции скилла.

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

### MCP и протоколы общения

MCP (Model Context Protocol) - это открытый стандарт, через который модель получает доступ к внешним инструментам и данным. Грубо говоря, это USB-разъём для AI: подключил MCP-сервер - у модели появились новые инструменты, независимо от того, кто её сделал.

В Opencode MCP-серверы бывают двух типов. Локальные запускаются как подпроцесс - Opencode вызывает команду, например ["npx", "-y", "@modelcontextprotocol/server-everything"], и общается с ней через стандартный ввод-вывод (stdio). Удалённые работают через HTTP, часто с OAuth-авторизацией: вы даёте URL сервера, и Opencode сам проходит логин через браузер, получает токен и сохраняет его в ~/.local/share/opencode/mcp-auth.json.

Транспортно MCP поддерживает несколько схем: stdio (для локальных серверов), HTTP+SSE (потоковый удалённый), Streamable HTTP (современная удалённая схема с одним эндпоинтом). Для пользователя это неважно - он просто пишет в конфиге "type": "local" или "type": "remote", остальное делает Opencode.

uvx - это команда из пакета uv, быстрого менеджера Python-окружений от Astral. Когда MCP-сервер написан на Python, его удобно запускать через uvx <package>: эта команда сама ставит нужную версию пакета в изолированное виртуальное окружение и запускает. Альтернатива для JavaScript - npx или bun x. В конфиге это выглядит одинаково: ["uvx", "mcp-server-time"] или ["npx", "-y", "my-mcp"].

Чтобы создать собственный MCP-сервер, достаточно описать инструменты в одном из SDK - Python, TypeScript, Go. Каждый инструмент имеет имя, описание, схему аргументов и функцию-обработчик. Сервер поднимается по stdio или HTTP, и Opencode сам опрашивает его на старте, забирает список инструментов и прокидывает в контекст модели. Когда модель решает вызвать инструмент, Opencode перенаправляет вызов на MCP-сервер, получает ответ и кладёт его обратно в контекст.

### Команда агентов и оркестрация

Один агент решает одну задачу. Команда агентов - это когда несколько агентов работают вместе над сложной целью. В Opencode это делается через инструмент Task: первичный агент может запускать подагентов, передавать им описания задач и получать результат. Это базовая оркестрация: главный дирижёр, подчинённые исполнители.

Границы команды задаются правами. В конфиге агента есть permission.task с glob-паттернами: можно разрешить одному агенту вызывать только orchestrator-*, а другого держать подальше от Task-инструмента вовсе. Это не позволяет главному агенту бесконтрольно плодить подагентов и тратить токены.

Оркестрация полезна для длинных задач. Например, надо зарелизить большой фич. Главный агент разбивает её на части: один подагент пишет тесты, второй копается в зависимостях, третий обновляет документацию. Каждый подагент работает в своей сессии, в своём контексте, со своим набором инструментов. Результаты сходятся к главному, который их синтезирует.

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

### Разворачивание агентов в Kubernetes

Kubernetes здесь нужен не для самой модели, а для инфраструктуры вокруг неё. Сама модель чаще живёт в облаке (Anthropic, OpenAI) или локально на GPU-сервере через Ollama. А вот Opencode как агентский рантайм можно упаковать в контейнер и гонять в K8s как сервис.

Типовой сценарий - корпоративная установка OpenCode Server или SDK. Контейнер поднимается как Deployment, ему пробрасывают секреты (API-ключи провайдеров, токены MCP-серверов), на старте он читает конфиг из ConfigMap. Для работы с внешними MCP через OAuth токены сохраняются в persistent volume, чтобы не логиниться каждый раз. Ingress или Service открывает API наружу для интеграций CI/CD.

Для Amazon Bedrock в K8s удобно использовать AWS_WEB_IDENTITY_TOKEN_FILE и AWS_ROLE_ARN - Kubernetes Service Account с OIDC-аннотациями сам подкладывает токен в под. Это免去 необходимости держать долгоживущие ключи в секрете. Аналогично с GCP Workload Identity для Vertex AI.

Масштабируется такая установка по числу одновременных сессий. Каждая сессия - это отдельный агентский процесс со своим контекстом, поэтому поды можно реплицировать и балансировать нагрузку. Если локальная модель крутится на GPU, то отдельный StatefulSet с Ollama экспонирует OpenAI-совместимый endpoint, а поды Opencode идут к нему по внутренней сети кластера.

### Ollama и инфраструктура доставки моделей

Ollama - это локальный сервер для запуска открытых моделей (Llama, Qwen, Gemma, DeepSeek, Mistral). Она ставится как обычная программа, после чего команда ollama pull llama3 скачивает модель, а ollama serve поднимает HTTP-сервер на localhost:11434. Этот сервер даёт OpenAI-совместимый API, поэтому Opencode подключается к нему как к обычному провайдеру, только baseURL указывает на локалхост.

Инфраструктура доставки моделей устроена слоями. Сначала авторы публикуют модель на Hugging Face Hub в виде весов и конфигурации. Ollama и LM Studio тянут оттуда GGUF-формат, оптимизированный под CPU и бытовые GPU. Для дата-центров есть vLLM, TGI, llama.cpp server, NVIDIA NIM - это тяжелые инференс-движки, заточенные под батчинг и параллелизм на нескольких GPU. Облака (AWS Bedrock, GCP Vertex, Together, Fireworks) поднимают модели у себя и дают API по подписке.

Цепочка доставки модели до агента выглядит так: автор обучил модель и выложил веса → инференс-провайдер (Ollama локально, vLLM в дата-центре или облако) загрузил веса и поднял API → Opencode подключил этого провайдера в конфиге → агент начал вызывать модель через этот endpoint. На каждом слое можно выбрать свою точку баланса между ценой, приватностью и скоростью. Локальная Ollama бесплатна и приватна, но медленна; облако быстро, но платно и не приватно; корпоративный кластер на vLLM - средний путь.

В Opencode есть специальный режим OpenCode Zen - это отобранная командой подборка моделей, которые гарантированно хорошо работают в агентском сценарии (то есть умеют вызывать инструменты и не путаются в длинных диалогах). Это удобно как стартовая точка: если вы не хотите разбираться, что выбирать, берёте Zen - и получаете проверенный набор.

### Пропущенные понятия, без которых картина не сложится

Permissions - система прав на инструменты. Для каждого агента можно сказать: "редактировать файлы - спрашивай", "выполнять bash - разрешай", "читать - всегда". Без этой системы агент был бы опасен: он мог бы по своей инициативе запустить rm -rf или отправить PR. Права задаются в JSON с уровнями allow / ask / deny и поддерживают glob-паттерны для конкретных команд.

AGENTS.md - это файл-инструкция в корне проекта, который агент читает автоматически. Туда кладут правила оформления кода, описание архитектуры, конвенции коммитов. Это не скилл, а постоянный контекст. Если вы коммитите AGENTS.md в git, то все, кто работает над проектом через Opencode, получают одинаковый набор правил.

References - это способ подключать внешние файлы-инструкции к агенту по ссылке. Вы пишете в конфиге "prompt": "{file:./prompts/build.txt}", и Opencode подгружает содержимое файла в системный промпт. Удобно для длинных правил, которые не хочется тащить в сам JSON.

Custom tools и plugins - способы расширить агента за пределы MCP. Плагины - это npm-пакеты, которые добавляют провайдеров или инструменты (например, opencode-gitlab-plugin даёт доступ к GitLab). Custom tools - это встроенные инструменты, которые вы описываете прямо в конфиге, без запуска внешнего сервера. Лёгкий путь, когда MCP-сервер писать не хочется.

LSP (Language Server Protocol) - интеграция с языковыми серверами, которые обычно используются в IDE. Opencode умеет их подгружать, чтобы модель понимала типы, определения, переходы по коду. Это даёт более умные правки, чем простой текстовый поиск. Без LSP модель читает файл как текст, с LSP - как структурированную программу.

Share и sessions - возможность отправить ссылку на разговор с агентом. Каждый разговор - это сессия с историей, инструментами и контекстом. Команда /share генерирует публичную ссылку. Это полезно для дебага: коллега может посмотреть, что вы спросили и что ответил агент, без воспроизведения у себя.

### Как всё это связано

Теперь соберём картину. Внизу - модель (через провайдера, локального или облачного). Над ней - агент с системным промптом, температурой, правами и доступом к инструментам. Агент работает в сессии и общается с пользователем через один из интерфейсов (TUI, IDE, веб). Для специализированных задач агент подгружает скиллы или запускает подагентов через инструмент Task. Внешний мир подключается через MCP-серверы и custom tools. Контекст ограничен контекстным окном, и когда оно переполняется, включается compaction. Все настройки лежат в opencode.json, а правила проекта - в AGENTS.md. Вся эта конструкция может крутиться на ноутбуке или в Kubernetes как сервис.

Связи между понятиями - не произвольные, а подчинённые идее композируемости. Каждый слой можно заменить, не ломая соседей. Можно поменять модель, не трогая агента. Можно сменить интерфейс, не трогая скиллы. Можно переехать с локальной Ollama на Bedrock, не меняя конфигурацию агентов. Эта свобода и есть причина, почему Opencode называют системным продуктом, а не просто "CLI-обёрткой над ChatGPT".

Для школьника суть простая. Представьте конструктор. Модель - это мотор, агент - рама, скиллы - насадки, MCP - провода к другим игрушкам, контекст - багажник, токены - бензин. Хотите ехать быстрее - ставите другой мотор. Хотите везти больше - берёте раму побольше. Хотите подключить лампочку - кидаете провод через MCP. И всё это собирается в один механизм, который едет по вашему коду и делает работу.

Opencode в этом смысле - не волшебный ящик, а хорошо продуманная система модулей. Когда вы понимаете, какой модуль за что отвечает, пропадает страх перед "AI-агентом". Это уже не магия, а инженерия: где-то модель, где-то цикл, где-то права, где-то инструменты. И каждый винт можно выкрутить, заменить и закрутить обратно.

____________________________________________________________

© Svartsinn1. Базовые понятия Opencode и начало работы

Origin: http://samlib.ru/s/svartsinn1/bazowyeponjatijaopencodeinachaloraboty.shtml

Создан: 20/08/2026, изменен: 20/08/2026, 32k

Статья: Нет