Интеграция локальных LLM и Claude Code: автоматизация запуска через Go-лаунчер

# Как подружить llama-server и Claude Code: автоматизация локальной работы с LLM

В последние годы библиотека llama.cpp эволюционировала из простого формата загрузчика файлов GGUF в полноценный фреймворк для развертывания локальных больших языковых моделей. Современный движок поддерживает OpenAI-совместимый API, инструменты для выполнения кода, шаблонизацию Jinja и гибкую разгрузку по процессорам или видеокартам. Однако для повседневной практики, особенно при работе с агентными системами, отсутствие удобного «обертки» остаётся барьером.

В этой статье разбирается вторая версия утилиты llama-runner, написанной на языке Go. Программа решает задачу автоматического запуска связки llama-server (локальный инференс) и Claude Code (терминальный агент от Anthropic), устраняя необходимость параллельного управления двумя терминалами и вручную подстраивать тысячи переменных окружения.

Архитектура связки и задачи автоматизации

Исходная проблема была очевидна: запуск локального сервера и клиентского приложения требовал отдельного открытия окон терминала. Пользователь должен был вручную указывать адрес сервера, порт и подбирать совместимые имена моделей для Claude Code, который по умолчанию ожидает названия вроде claude-sonnet-4, не существующие в локальном репозитории llama.cpp.

Цель разработки заключалась в создании единого вызова, который: 1. Запускает llama-server с заданной моделью. 2. Ожидает его полной готовности. 3. Автоматически запускает Claude Code, передавая корректные переменные окружения.

При этом должно сохраняться «устаревшее» поведение для случаев, когда пользователю нужен только сервер (например, для доступа к веб-интерфейсу WebUI), без запуска агента.

Реализованные механизмы

Для решения задачи были внедрены ключевые изменения в логику программы: * Режимы работы: Флаг -server активирует только запуск сервера с выводом логов в консоль. В отсутствие этого флага программа автоматически поднимает и агента. * Автоматическая подстановка имен: Используется флаг -alias, который, по умолчанию, принимает значение local. Это имя сервер получает как псевдоним модели, а клиенту передаются переменные ANTHROPIC_DEFAULT_*_MODEL, привязывающие его к локальному имени. * Обработка готовности: Программа реализует опрос эндпоинта /health с настраиваемым таймаутом перед запуском агента, гарантируя стабильность соединения.

Технические вызовы и их решения

Процесс интеграции выявил три специфических препятствия, характерных для работы с агентными интерфейсами в консоли.

Конфликт потоков вывода

Интерфейс Claude Code реализован через текстовый пользовательский интерфейс (TUI), использующий сложные ANSI-последовательности для отрисовки невидимого курсора и динамического обновления экрана. Когда локальный llama-server отправляет в тот же терминальный поток метрики (заполненность слотов, тайминги, предупреждения), экран агента начинает искажаться: текст наслаивается друг на друга, а курсор «глюкит».

Решение: В режиме работы с агентом программой перенаправляется stdout и stderr сервера в отдельный файл по умолчанию ~/.cache/llama-runner/llama-server.log. В режиме чистого запуска -server логи остаются в терминале. Дополнительно реализован флаг -quiet-server для молчаливого старта и -log-file для изменения пути к логу.

Проблема шаблонов чата и Jinja

Серверная часть llama-server поддерживает различные форматы контекста чата через файлы шаблонов Jinja. Стандартный шаблон для моделей семейства Qwen 3.8 содержит строгое условие: системное сообщение должно находиться в начале диалога.

Агент Claude Code при попытке восстановления после сбоя может отправлять системное сообщение позже, что вызывает ошибку 500: Error: Jinja Exception: System message must be at the beginning. Это запускает цикл повторных попыток (retries), который в логах выглядит как бесконечный набор ошибок.

Решение: В llama-runner встроена проверка и скачивание исправленного шаблона из репозитория froggeric/Qwen-Fixed-Chat-Templates (файл chat_template.jinja). Утилита автоматически загружает его в папку с моделями (~/GGUF). Если файл не найден, программа выводит предупреждение, но продолжает запуск сервера со встроенным шаблоном, что позволяет избежать полного падения процесса. Пользователь может явно указать путь к шаблону через флаг -chat-template или полностью отключить его передачу, установив пустое значение.

Управление процессами

Программа корректно обрабатывает сигналы выхода. При завершении работы в интерфейсе агента (через команду /exit, Ctrl+C или EOF) лаунчер автоматически отправляет сигнал SIGINT дочернему процессу сервера, обеспечивая его корректное завершение и освобождение портов без оставления «висящих» процессов.

Возможности и гибкость конфигурации

Новая версия поддерживает расширенную настройку гиперпараметров запуска. Помимо базовых опций, доступны параметры для управления размером контекста (-c), батча (-b, -ub), включением Flash Attention (-fa), количеством параллельных слотов (--parallel) и режимом работы инструментов (-tools).

Особое внимание уделено совместимости с инструментами для доступа к сети через MCP (Model Context Protocol). При запуске с флагом -webui-mcp-proxy программа дополнительно активирует сервер mcp-search-server на порту 8090, позволяя агенту выполнять поиск информации в интернете.

Код проекта открыт и доступен в репозитории на GitHub. Сборка осуществляется стандартными средствами Go и не требует сложной настройки окружения. Инструмент особенно актуален для разработчиков, работающих с моделями MoE (Mixture of Experts) класса Qwen 3.8 на ограниченном оборудовании, стремящихся развернуть автономную агентную среду без оплаты облачных API и ежемесячных подписок.

*Редакторское замечание:* Использование флага --tools all в связке с локальным сервером открывает доступ к сетевым ресурсам. В целях безопасности рекомендуется явно ограничивать доступные инструменты через флаг -tools только тем, что необходимо для конкретной задачи.*