OpenClaude + Local LLM Handbook

Практическая документация по запуску openclaude на сервере, подключению локальных и облачных моделей, работе с MCP/RAG и планированию железа под разные бюджеты.

1) Что такое LLM и токены

• LLM (Large Language Model) - большая языковая модель, которая генерирует текст токен за токеном.
• Токен - кусок текста (слово, часть слова, знак, пробел), не всегда "целое слово".
• Скорость 1-5 токенов/с - скорость генерации ответа моделью (decode speed).
• Очень грубо: 5 ток/с часто ощущается как ~15-25 символов/с, но это зависит от языка и модели.

2) Что такое MCP и зачем он нужен

MCP (Model Context Protocol) - стандарт для подключения инструментов и источников данных к AI-агенту.

Простая схема:

• Модель = "мозг"
• MCP-сервер = "шлюз к инструментам"
• MCP-инструменты = конкретные действия (search_docs, run_sql, create_ticket и т.д.)

Польза MCP:

• Подключение к актуальным данным (документы, БД, API)
• Контролируемое выполнение действий через схемы входа/выхода
• Повторяемая интеграция для локальных и облачных сценариев

3) Основные сценарии работы OpenClaude

openclaude поддерживает разные провайдеры, включая:

• OpenAI-compatible API
• Ollama (локально)
• DeepSeek (через OpenAI-compatible endpoint)
• Gemini, GitHub Models, Codex и др.

4) Быстрый запуск OpenClaude

4.1 Установка

npm install -g @gitlawb/openclaude

4.2 Локальный Ollama-профиль (бесплатно)

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
export OPENAI_MODEL=qwen2.5-coder:7b
openclaude

4.3 OpenAI-профиль

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-...
export OPENAI_MODEL=gpt-4o
openclaude

4.4 DeepSeek-профиль

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=https://api.deepseek.com/v1
export OPENAI_API_KEY=sk-...
export OPENAI_MODEL=deepseek-chat
openclaude

5) Локальные бесплатные модели: где брать и что ставить

Где брать

• Проще всего через Ollama: https://ollama.com/library

Рекомендуемый старт

• qwen2.5-coder:7b - хороший баланс для кода
• qwen2.5:3b - если сервер слабый
• llama3.1:8b - универсальный сильный baseline
• deepseek-r1:8b - reasoning-ориентированный вариант

Команды

ollama pull qwen2.5-coder:7b
ollama pull qwen2.5:3b
ollama pull llama3.1:8b
ollama pull deepseek-r1:8b
ollama list

6) Важный вопрос: локальные модели "дообучаются сами"?

Короткий ответ: нет.

• Обычная работа в чате не дообучает модель автоматически.
• Качество повышают обычно так:
  • обновляют модель/тег (ollama pull ...)
  • улучшают системные промпты
  • подключают RAG (документы + retrieval)
• Полноценный finetune/LoRA - отдельный ML-процесс.

7) Профили и переключение через direnv

7.1 Профили

Создать:

mkdir -p ~/.config/openclaude/profiles

~/.config/openclaude/profiles/local.env

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
export OPENAI_MODEL=qwen2.5-coder:7b
unset OPENAI_API_KEY

~/.config/openclaude/profiles/openai.env

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=https://api.openai.com/v1
export OPENAI_API_KEY=sk-REPLACE_ME
export OPENAI_MODEL=gpt-4o

~/.config/openclaude/profiles/deepseek.env

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=https://api.deepseek.com/v1
export OPENAI_API_KEY=sk-REPLACE_ME
export OPENAI_MODEL=deepseek-chat

Права:

chmod 600 ~/.config/openclaude/profiles/*.env

7.2 Установка direnv

sudo apt update
sudo apt install -y direnv

Для bash:

echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
source ~/.bashrc

Для zsh:

echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
source ~/.zshrc

7.3 Автопрофиль на папку проекта

В корне проекта:

cat > .envrc <<'EOF'
source_env ~/.config/openclaude/profiles/local.env
EOF
direnv allow

8) Минимальный RAG стек (локально)

Рекомендуемая база:

• Embeddings: nomic-embed-text (через Ollama)
• Vector DB: Qdrant
• Retrieval tool: MCP search_docs

Минимальная схема:

1. Сложить документы (md/txt/pdf)
2. Разбить на чанки (chunk_size ~1000, overlap ~120)
3. Сделать embeddings
4. Записать в Qdrant
5. Поднять MCP-инструмент search_docs
6. Вызывать его из OpenClaude

9) Быстрый чек-лист, если MCP "не виден"

1. MCP-сервер стартует вручную:

python mcp_server.py

2. Импорты и зависимости установлены:

python -c "import fastmcp, qdrant_client, requests; print('ok')"

3. Пути в ~/.claude/settings.json корректны (command, args)
4. Qdrant доступен: curl http://127.0.0.1:6333/collections
5. Ollama доступен: curl http://127.0.0.1:11434/api/tags

10) План закупки железа под 3 бюджета

Ориентиры даны для Linux-сервера и локального запуска LLM (Ollama/OpenAI-compatible).

Бюджет A: Минимальный (CPU-only)

Для кого: старт, RAG, базовые задачи, без требований к высокой скорости.

• CPU: 8-12 vCPU (современные ядра)
• RAM: 32 GB (минимум 16 GB, но хуже)
• Disk: NVMe 512 GB
• GPU: нет

Ожидания:

• модели 3B-7B с умеренной скоростью
• ориентир decode: примерно 1-6 ток/с (зависит от модели и квантизации)

Рекомендованные модели:

• qwen2.5:3b
• qwen2.5-coder:7b (если хватает RAM/терпения)

Бюджет B: Комфортный (1x GPU среднего класса)

Для кого: ежедневная работа 1-3 пользователей, код + RAG в комфортном режиме.

• CPU: 8-16 vCPU
• RAM: 32-64 GB
• GPU: 1x NVIDIA 12-16 GB VRAM (например, RTX 3060 12GB / 4070 Ti Super 16GB)
• Disk: NVMe 1 TB

Ожидания:

• стабильная работа 7B/8B, лучше latency и throughput
• ориентир decode: примерно 10-35 ток/с

Рекомендованные модели:

• qwen2.5-coder:7b
• llama3.1:8b
• deepseek-r1:8b

Бюджет C: Производительный (1-2 GPU высокого класса)

Для кого: команда, многозадачность, более тяжелые модели и высокая отзывчивость.

• CPU: 16+ vCPU
• RAM: 64-128 GB
• GPU:
  • вариант 1: 1x NVIDIA 24 GB VRAM (RTX 4090 / L40-class по бюджету)
  • вариант 2: 2x GPU по 16-24 GB для масштабирования
• Disk: NVMe 2 TB

Ожидания:

• уверенная работа 14B+ (квантизованные), параллельные запросы
• ориентир decode: 25-80+ ток/с в зависимости от модели/батча

Рекомендованные модели:

• 14B-класс инструкт/кодовые варианты
• mix моделей: одна "быстрая дешевая", одна "качественная тяжелая"

Что критично кроме железа

• стабильная версия драйверов CUDA (если NVIDIA)
• быстрый NVMe (модели занимают много места)
• мониторинг температуры/памяти/IO
• резерв свободного диска под новые веса

11) Практика обновления и обслуживания моделей

• Смотреть установленные:

ollama list

• Обновлять нужные:

ollama pull qwen2.5-coder:7b

• Удалять старые:

ollama rm <model:tag>

• Проверять занятое место:

sudo du -h --max-depth=2 /usr/share/ollama /var/lib/ollama 2>/dev/null | sort -h | tail -n 30

12) Подключение к приватным GitHub репозиториям без постоянного ввода PAT

Рекомендуемый вариант:

gh auth login
gh auth status

Для HTTPS git credentials сохранять через credential helper (или использовать SSH-ключи).

13) Частые проблемы и быстрые фиксы

13.1 Скрипт запуска падает с #!/usr/bin/env: No such file or directory

Причина: BOM в начале файла.

Фикс:

sed -i '1s/^\xEF\xBB\xBF//' script.sh
chmod +x script.sh

13.2 Почему после выбора зеркала apt все еще ходит в ru.archive.ubuntu.com

Обычно источники лежат в *.sources (deb822), а не только в sources.list. Нужно менять и URIs: в deb822-блоках.

---

Roadmap продолжения

Когда вернемся к теме, логично идти так:

1. Проверка текущего сервера (CPU/RAM/GPU/NVMe)
2. Выбор стартового профиля (local/openai/deepseek)
3. Поднятие openclaude + smoke test
4. Запуск минимального RAG с Qdrant
5. Добавление MCP-инструментов под ваши рабочие данные
6. Оптимизация скорости и стоимости (routing между моделями)

Дополнительные материалы в репозитории

• Быстрый гайд: docs/quickstart-30min.md
• Готовый starter: docs/rag-mcp-starter/
• Работа с GitHub/GitLab/Gitea: docs/openclaude-with-repositories.md
• Примеры cron-автоматизации: docs/cron-examples.md