commit f5c6ce61699c1b5c939c61267cf9d9408f44bb8e
Author: Andrey Lutsenko <papatramp@gmail.com>
Date:   Mon Apr 20 22:53:26 2026 +1000

    Add OpenClaude local LLM deployment handbook.
    
    Made-with: Cursor

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f41ce48
--- /dev/null
+++ b/README.md
@@ -0,0 +1,354 @@
+# 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 между моделями)