# 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 Установка

```bash
npm install -g @gitlawb/openclaude
```

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

```bash
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-профиль

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

### 4.4 DeepSeek-профиль

```bash
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](https://ollama.com/library)

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

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

### Команды

```bash
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 Профили

Создать:

```bash
mkdir -p ~/.config/openclaude/profiles
```

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

```bash
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`

```bash
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`

```bash
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
```

Права:

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

### 7.2 Установка direnv

```bash
sudo apt update
sudo apt install -y direnv
```

Для bash:

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

Для zsh:

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

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

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

```bash
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-сервер стартует вручную:

```bash
python mcp_server.py
```

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

```bash
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) Практика обновления и обслуживания моделей

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

```bash
ollama list
```

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

```bash
ollama pull qwen2.5-coder:7b
```

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

```bash
ollama rm <model:tag>
```

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

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

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

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

```bash
gh auth login
gh auth status
```

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

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

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

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

Фикс:

```bash
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`
- Точка входа: `docs/START-HERE.md`
- Готовый starter: `docs/rag-mcp-starter/`
- Работа с GitHub/GitLab/Gitea: `docs/openclaude-with-repositories.md`
- Примеры cron-автоматизации: `docs/cron-examples.md`
- Автоустановка cron: `scripts/install-cron.sh`
- Каталог моделей: `docs/model-catalog.md`
- Выбор runtime: `docs/runtime-choice.md`
- Локальный Cursor-like стек: `docs/cursor-like-stack.md`
- Честные ожидания: `docs/expectations.md`
- Шаблон benchmark: `docs/bench-template.md`