Очередная гигаультрамощногеймченджерная система работы с ИИ для разработчиков
Озвучка статьиТестовая voice-версия с главами1:20:49
Главы
Этот гайдик включает в себя инфу по 3м модулям "системы" в отдельности и в связке:
wireguard (для того, чтобы подключаться удаленно).
1. OPENCODEZ SOLO
Базовый гайд
Opencodez сам по себе соотвествует следующей формуле: opencode (оригинальный репозиторий, который позволяет подключить любую нейросеть и гибко настраивать рабочий процесс) + z (мой кастомный функционал).
Установка очень проста и для актуальной команды, которая сама всё установит можно идти на гитхаб и посмотреть ридмишку. Обновлять можно очень просто: opencodez update.
Главная фишка кастомной части — управление System prompt во всех основных интерфейсах OpenCodez. В терминальном интерфейсе текущий выбор показывается рядом с моделью в виде S: ...: промпт можно переключить через окно выбора, найти по имени или задать командой /system. В веб-интерфейсе такой же переключатель находится рядом с полем ввода. Выбор сохраняется вместе с сессией, поэтому системный промпт можно менять прямо во время работы и не настраивать заново после каждого открытия. Если пользователь ничего не выбирал вручную, OpenCodez берет подходящий вариант из настроек модели.
Вторая важная часть — настраиваемые значения по умолчанию для моделей и семейств ИИ. В ~/.config/opencodez/opencode.jsonc через opencodez.responses.system можно указать общий System prompt или выбрать отдельные промпты для конкретных моделей, пар провайдер/модель и целых семейств. Это позволяет заранее назначить подходящее поведение для разных нейросетей и не выбирать системный промпт вручную в каждой новой сессии.
Еще один кастом — более безопасные дефолты для индексации файлов/папок. OpenCodez старается не превращать старт сервиса в бесконечный рекурсивный обход файловой системы и по умолчанию избегает тяжелого/непредсказуемого системно-поискового поведения. В частности, OPENCODE_DISABLE_FFF включен по умолчанию, и поиск файлов опирается на более предсказуемый ripgrep path. Это особенно важно для моментов, если есть желание врубить web-версию (команда opencodez web), ибо при длительных сессиях или постоянном включении это будет жрать невообразимое количество ресурсов устройства, что приведет к его перегреву (мой сервер достигал температуры в 83 градуса). В будущем будет обратно отключены такие штуки, когда завезут или я завезу адекватный рекурсивный поиск, чтобы с web-интерфейса можно было удобно смотреть на собственную файловую систему.
Мультихост и/или LAN (Локальная сеть)
Еще одна важная часть OpenCodez — удобная работа с несколькими машинами в одной локальной сети. Идея простая: на каждой машине поднимается свой сервер OpenCodez, а в web-интерфейсе можно переключаться между ними как между отдельными пространствами. Например, есть kuk, duk, suk, и у каждого из них могут быть свои проекты, свои сессии и свой локальный доступ к файловой системе. При этом открывается один web-интерфейс, а работа идет со всеми хостами из одного места.
На каждой машине, которую хочется подключить как отдельное пространство, нужно запустить OpenCodez server наружу в LAN:
opencodez serve --hostname 0.0.0.0 --port 4096 --cors http://192.168.1.75(ЭТО АЙПИ ЛОКАЛЬНОЙ МАШИНЫ):4098
Здесь 4096 — порт backend-а на конкретной машине, а --cors должен указывать адрес web-интерфейса, с которого можно открывать OpenCodez в браузере. Например, если web открыт на kuk как http://192.168.1.75:4098, то остальные машины должны принимать это.
На главной машине, где будет открыт web UI, можно запустить web-версию:
opencodez web --hostname 0.0.0.0 --port 4098
После этого web-интерфейс будет доступен в локалке, например:
Чтобы OpenCodez сам показал список нужных серверов в Settings -> Servers, можно перед запуском web/server процесса передать список через переменную окружения:
export OPENCODE_WEB_SERVERS_JSON='[ { "name": "kuk", "url": "http://192.168.1.75:4096" }, { "name": "duk", "url": "http://192.168.1.124:4096" }, { "name": "suk", "url": "http://192.168.1.156:4096" } ]'
После этого web UI при загрузке сам добавит эти хосты в список серверов. Важно понимать модель: при выборе, например, duk, браузер работает с duk напрямую, а не проксирует всё через kuk. Поэтому duk должен быть доступен из браузера по своему адресу в локальной сети, а CORS должен разрешать источник главной страницы.
Для домашней сети это дает очень удобную схему: один постоянный сервер держит web UI, а остальные машины подключаются как рабочие пространства.
ВАЖНО: это всё можно делать в рамках и одного хоста, который в локальной сети работает. Т.е. мультихост скорее расширение базового функционала для LAN.
2. OPENCODEZ + WIREGUARD
OpenCodez можно использовать не только в локальной сети, но и удаленно, если поднять WireGuard. Смысл WireGuard в этом сценарии простой: удаленное устройство, например ноутбук или телефон через мобильный интернет, подключается к домашней сети так, будто оно физически находится внутри LAN.
В нормальной схеме не нужно открывать opencodez web или opencodez serve напрямую в интернет. То есть порты 4098 и 4096 лучше не публиковать наружу. Наружу на роутере открывается только порт WireGuard, например UDP 51820, который прокидывается на домашнюю машину с WireGuard-сервером. После подключения WireGuard удаленное устройство получает доступ к домашним LAN-адресам вида:
192.168.1.75 192.168.1.124 192.168.1.156
Тогда OpenCodez открывается так же, как дома:
Если до этого уже был настроен LAN/multihost, то схема остается той же. Главный web-интерфейс может жить на kuk, а остальные машины остаются отдельными пространствами. Когда выбран duk, браузер через WireGuard напрямую ходит на http://192.168.1.124:4096; когда выбран suk, ходит на http://192.168.1.156:4096.
Важно, чтобы WireGuard-клиент имел маршрут до домашней подсети, например 192.168.1.0/24, а firewall на домашних машинах разрешал доступ с WireGuard-подключений к портам OpenCodez.
В итоге WireGuard дает удобный режим: дома работает обычный LAN, снаружи работает тот же LAN, только через защищенный туннель. OpenCodez при этом не торчит в открытый интернет, а остается доступным только тем устройствам, которые подключены к WireGuard.
3. OPENCODEZ + OPENCODEBOT (WIREGUARD ОПЦИОНАЛЕН)
opencodebot - это Telegram-клиент и зеркало серверной части OpenCodez. Через него можно быстро начать задачу, написать в уже идущую сессию, получить уведомление о завершении, отправить файл, получить результат или расшифровать голосовое сообщение.
При этом opencodebot не заменяет OpenCodez и не создает отдельную систему сессий. Веб-интерфейс OpenCodez и Telegram смотрят на одну и ту же серверную часть. В браузере остается полный интерфейс: история, рабочая директория, выбор сервера и нормальная навигация. В Telegram остаются те действия, которые удобно делать из чата.
Главная рабочая единица здесь - тема в Telegram-группе. Одна тема может быть привязана к одной сессии OpenCodez. Когда сессия появляется в OpenCodez, бот может создать под нее тему. Сообщение в такой теме уходит в соответствующую сессию. Когда агент отвечает, бот присылает обратно основные события: сообщения пользователя, краткие события инструментов, финальный ответ, ссылку на веб-интерфейс и служебный статус.
В итоге работа идет в обе стороны. Можно начать сессию через Telegram и потом открыть ее в веб-интерфейсе. Можно начать работу в браузере и увидеть ее в Telegram. Можно не держать вкладку открытой, писать с телефона, получать финальные ответы, прикладывать файлы, а сама работа все равно будет выполняться на домашней машине или сервере.
Отдельно сделаны финальные уведомления. Во время работы у темы можно спокойно выключить уведомления, потому что в ней могут появляться вызовы инструментов, промежуточные события и ответы агента. Когда агент закончил работу, бот присылает личное сообщение с короткой выжимкой: откуда задача, на каком сервере она выполнялась, какой был исходный запрос, есть ли закрытый список задач, и кнопку Open topic, чтобы сразу перейти к нужному месту. Включается это через /notify_on, выключается через /notify_off, состояние можно посмотреть через /notify_status.
Создание новой темы сейчас делается командой /new. В ней можно выбрать сервер, готовый профиль, рабочую директорию и название будущей темы. Профиль хранит обычный набор настроек новой сессии: агента, модель, уровень рассуждений и System prompt. Благодаря этому одни и те же параметры не приходится выставлять вручную при каждом запуске.
/new [сервер] [профиль] [dir:<путь>] [название]
Сервер - это его короткий идентификатор из servers.json. В начальных настройках такой сервер называется local. Если сервер не указан, бот возьмет сервер по умолчанию.
Профиль - это заранее сохраненный способ запуска из раздела promptProfiles в конфигурации бота. В публичной версии из коробки доступны профили d4flash, d4pro, solm, solh, sol и solmax. Первые два предназначены для DeepSeek, остальные выбирают разные уровни рассуждений модели Sol. При желании в настройки можно добавить собственные профили.
dir:<путь> говорит, в какой директории на выбранном сервере надо создать сессию OpenCodez. Если директорию не указать, используется домашняя директория сервера из servers.json. Поэтому сессия из Telegram может сразу начинаться в папке нужного проекта.
Последняя часть команды - название темы в Telegram. Если название не указано, бот возьмет его из автоматического названия веб-сессии или временно использует нейтральное имя вроде OpenCodez local.
Вот несколько примеров:
/new
/new local
/new local sol
/new local sol Починить загрузку файлов
/new local d4pro dir:/home/user/demo-bot обнови README
После /new бот создает тему в Telegram и готовит новую сессию OpenCodez. Команда задает сервер, профиль, директорию и название, а первый обычный текст в этой теме становится первым запросом. Дальше в тему можно писать обычные сообщения, и они будут уходить в ту же сессию.
Основные команды теперь лучше понимать не как длинную справку, а как набор действий вокруг текущей темы:
/session
/q <текст>
/q status
/q delete <номер>
/kill
/artifacts_here
/sounds_here
/notify_on /notify_off
/notify_status
/mirror_on /mirror_off
/mode full
/mode economy
/help
/session показывает, к какой сессии OpenCodez привязана текущая тема, какой сервер и рабочая директория используются, какая выбрана модель и где открыть сессию в веб-интерфейсе. /mirror_on и /mirror_off включают и выключают передачу событий из OpenCodez в Telegram. Команда /mode full показывает работу подробнее, а /mode economy сокращает количество промежуточных технических сообщений. /help выводит справку и доступные профили.
Очередь через /q очень важна именно для Telegram. В чате легко получается ситуация: агент еще работает, а следующее задание уже нужно записать. Вместо того чтобы ломать текущий запуск, можно заранее положить новый запрос в очередь. Бот отправит его только после того, как OpenCodez освободит сессию, а предыдущий финальный ответ успеет появиться в Telegram. Если сессия остановится без финального ответа и без явной ошибки, бот сообщит об этом в теме и затем сможет продолжить очередь. Так следующий запрос не обгоняет предыдущий ответ, а очередь не зависает навсегда.
Управляется очередь несколькими короткими командами:
/q следующий запрос
/q status
/q delete 1
Если текущую работу надо остановить и заодно очистить очередь, используется /kill. Команда действует только на ту тему, в которой была отправлена.
Файлы и картинки можно отправлять прямо в рабочую тему Telegram. Бот принимает фото, документы, подписи и группы файлов. Можно отправить файл с подписью, а можно сначала отправить вложения, а следующим сообщением объяснить, что с ними сделать. Маленькие файлы могут попасть в запрос сразу, большие сохраняются как обычные файлы в файловую систему, а агенту передается путь и описание. Поэтому можно написать что-то вроде «посмотри этот скрин» и прикрепить картинку, или скинуть лог, архив, PDF, таблицу, а потом дать задачу.
Если сервер удаленный, файл может быть перенесен в его uploadRoot, в том числе через настроенную передачу файлов. Если включен локальный Telegram Bot API, боту удобнее работать с большими файлами и лимитами локального режима Telegram. Но это не безлимит, а отдельный режим, который явно включается и настраивается. Для него отдельно нужны TELEGRAM_API_ID и TELEGRAM_API_HASH, которые берутся в инструментах разработчика Telegram.
Собственно сам https://my.telegram.org/
Есть и обратная сторона: агент может отправлять файлы в Telegram. Для этого используется специальная тема:
/artifacts_here
Эта команда выбирает текущую тему как место для артефактов работы и как приемник файлов. После этого туда можно складывать скриншоты, логи, архивы, картинки, отчеты, документы и другие материалы.
Важная часть: агент не получает токен Telegram-бота. Он передает файл или текст в отдельный шлюз opencodebot, шлюз проверяет свой токен, а уже бот доставляет результат в Telegram. В репозитории для этого лежат дополнение для OpenCodez с инструментом opencodebot_send_artifact и готовый навык telegram-artifact-send. После их подключения агент может отправить один файл, несколько файлов, изображение или текст. Использовать этот инструмент он должен только тогда, когда пользователь явно попросил что-то отправить в Telegram или в тему с результатами.
Подключаем дополнение в настройках OpenCodez, после чего перезапускаем сервис
Еще одна важная возможность - распознавание речи. Для этого должна быть создана отдельная тема:
/sounds_here
/sounds_status
/sounds_off
После /sounds_here текущая тема становится местом для голосовых сообщений и аудиофайлов. Бот отправляет запись в OpenRouter и возвращает расшифровку в ту же тему. По умолчанию используется Whisper V3 Turbo, а другие добавленные в настройки модели можно выбирать через закрепленное сообщение. Это не заменяет рабочие темы: обычный текст отсюда не отправляется в OpenCodez как задача. Зато появляется удобный режим: наговорил голосом, получил аккуратную расшифровку, потом отправил результат в нужную рабочую сессию.
То есть в Telegram теперь есть несколько разных типов тем, и их лучше не смешивать. Рабочая тема привязана к сессии OpenCodez, тема для артефактов принимает файлы и материалы от агента, а тема для голосовых занимается только расшифровкой записей.
Начальные файлы настроек можно создать командой npm run init-config. Она подготовит config.local.json и servers.json, после чего останется отдельно создать файл с секретами token.env. Изменяемые данные бот будет хранить в каталоге state/.
В итоге рядом с установленным ботом появляются такие файлы и каталоги:
config.local.json
servers.json
token.env
state/ или state.json
config.local.json - основной файл настроек: идентификатор Telegram-чата, разрешенные пользователи, сервер по умолчанию, профили новых сессий, уведомления, вложения, шлюз для артефактов, распознавание речи, а также режим и адрес Telegram Bot API.
servers.json - список серверов OpenCodez. Там задаются их идентификаторы, URL, домашние директории, папки для загруженных файлов и правила переноса файлов. Именно эти идентификаторы потом используются в командах вроде /new local ....
token.env - секреты: токен Telegram-бота, токены для шлюза артефактов, ключ OpenRouter для распознавания речи, а при локальном Telegram Bot API еще и значения Telegram API. Это не надо печатать, пересылать или сохранять в git.
state/ или state.json - память бота. Там хранится связь между темой Telegram и сессией OpenCodez, выбранная тема для артефактов, тема для голосовых, состояние зеркалирования, включенные уведомления, уже отраженные сообщения и прочая рабочая история. Это не настройка, а текущее состояние сервиса.
WireGuard для связки opencodez + opencodebot не обязателен. Telegram сам по себе уже дает удаленное управление: можно писать боту не из домашней сети, запускать задачи, получать ответы и файлы. Но WireGuard все равно полезен рядом, потому что иногда удобнее открыть веб-интерфейс OpenCodez и руками посмотреть сессию, переключить сервер, увидеть длинный контекст или поработать с интерфейсом.
ВАЖНО: обновлять OpenCodez и opencodebot нужно отдельно. После первичной установки OpenCodez обычно достаточно обновлять сам OpenCodez своим способом, а opencodebot обновляется как отдельный сервис.
Для обновления opencodebot базово достаточно подтянуть код и пересобрать контейнер:
git pull
docker compose up -d --build opencodebot
Но если обновление затрагивает дополнение для отправки артефактов или навык telegram-artifact-send, их тоже нужно обновить в OpenCodez и перезапустить тот процесс, где агент должен увидеть новый инструмент. Если менялись файлы настроек, отдельно проверяются config.local.json, servers.json, token.env и путь к state, потому что именно там теперь живет большая часть поведения.