openclaude-LLM-local/docs/quickstart-30min.md

OpenClaude + Local LLM: Quickstart 30 min

Короткий маршрут "с нуля до рабочего стенда" на Ubuntu.

Если вы на Windows, установите Ollama и Node.js локально, затем для запуска OpenClaude на локальной модели следуйте docs/install-openclaude-cli.md (блоки PowerShell и порядок шагов там же). Полный стек ниже (Docker, bash-скрипты, пути ~/...) удобнее повторять в WSL2 или на Linux-сервере с тем же репозиторием.

0) Что получится

• локальный LLM через Ollama
• openclaude в CLI
• локальный RAG-поиск через MCP (search_docs)

1) Установка зависимостей

sudo apt update
sudo apt install -y curl git docker.io docker-compose-plugin python3 python3-venv python3-pip direnv
sudo systemctl enable docker
sudo systemctl start docker

Если на Ubuntu 24.04 вы видите ошибку Unable to locate package docker-compose-plugin, подключите официальный Docker APT-репозиторий и установите пакеты оттуда:

sudo rm -f /etc/apt/sources.list.d/docker.list
sudo rm -f /etc/apt/keyrings/docker.gpg
sudo apt update
sudo apt install -y ca-certificates curl gnupg

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu noble stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
docker compose version

2) Установка Ollama

Ниже — типичный путь для Ubuntu/сервера. Для macOS, Windows и winget см. docs/install-openclaude-cli.md (раздел про установку Ollama).

curl -fsSL https://ollama.com/install.sh | sh
sudo systemctl enable ollama
sudo systemctl start ollama
curl -s http://127.0.0.1:11434/api/tags

3) Установка OpenClaude

npm install -g @gitlawb/openclaude

Для очень слабого сервера можно использовать минимальный установщик:

cd ~/openclaude-LLM-local/docs/rag-mcp-starter
chmod +x install-minimal.sh
./install-minimal.sh --model qwen2.5:3b

4) (Опционально) Хранить модели Ollama на втором диске

Если системный диск маленький, заранее перенесите путь хранения моделей (например, на /mnt/data).

sudo mkdir -p /mnt/data/ollama-models
sudo chown -R ollama:ollama /mnt/data/ollama-models

sudo mkdir -p /etc/systemd/system/ollama.service.d
sudo tee /etc/systemd/system/ollama.service.d/override.conf > /dev/null <<'EOF'
[Service]
Environment="OLLAMA_MODELS=/mnt/data/ollama-models"
EOF

sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama -p Environment

После этого новые ollama pull ... будут сохраняться в OLLAMA_MODELS.

5) (Опционально) Перенести Docker data-root на второй диск

Если вы поднимаете Qdrant/контейнеры и хотите экономить системный диск, перенесите хранилище Docker (образы, volumes, слой контейнеров) на /mnt/data/docker.

docker info | grep "Docker Root Dir"

sudo systemctl stop docker
sudo systemctl stop docker.socket

sudo mkdir -p /mnt/data/docker
sudo chown root:root /mnt/data/docker
sudo chmod 711 /mnt/data/docker

sudo rsync -aHAXx --numeric-ids /var/lib/docker/ /mnt/data/docker/

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json > /dev/null <<'EOF'
{
  "data-root": "/mnt/data/docker"
}
EOF

sudo systemctl daemon-reload
sudo systemctl start docker
docker info | grep "Docker Root Dir"

Ожидаемый результат: Docker Root Dir: /mnt/data/docker.

6) Скачать стартовые модели

ollama pull qwen2.5-coder:7b
ollama pull nomic-embed-text
ollama pull llava:7b
ollama pull minicpm-v
ollama pull qwen2.5vl

llava / minicpm-v / qwen2.5vl полезны для анализа картинок и OCR-сценариев (vision), а не для генерации изображений "с нуля". Для image generation смотрите docs/free-graphical-models.md.

7) Поднять Qdrant

Qdrant — это векторная база данных. В этом проекте она хранит embeddings (векторы) фрагментов ваших документов и быстро ищет наиболее похожие фрагменты по запросу пользователя.

Зачем он нужен в нашем контуре:

• index.py превращает текст документов в embeddings и записывает их в Qdrant;
• mcp_server.py при вызове search_docs ищет релевантные чанки в Qdrant;
• OpenClaude получает найденный контекст и отвечает уже на основе ваших данных (RAG), а не только на "общих знаниях" модели.

Без Qdrant связка RAG в текущем starter-стеке работать не будет.

cd ~/openclaude-LLM-local/docs/rag-mcp-starter
docker compose up -d
curl -s http://127.0.0.1:6333/collections

8) Подготовить Python окружение

cd ~/openclaude-LLM-local/docs/rag-mcp-starter
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

9) Проиндексировать документы

cd ~/openclaude-LLM-local/docs/rag-mcp-starter
mkdir -p docs
# Добавьте в docs/ файлы .md .txt .pdf
python index.py

10) Запустить MCP сервер

cd ~/openclaude-LLM-local/docs/rag-mcp-starter
source .venv/bin/activate
python mcp_server.py

11) Подключить MCP в OpenClaude

Добавьте в ~/.claude/settings.json:

{
  "mcpServers": {
    "local-rag": {
      "command": "/home/USER/openclaude-LLM-local/docs/rag-mcp-starter/.venv/bin/python",
      "args": ["/home/USER/openclaude-LLM-local/docs/rag-mcp-starter/mcp_server.py"]
    }
  }
}

Замените USER на вашего пользователя.

12) Запуск OpenClaude на локальной модели

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

Проверка в чате: попросите агента использовать search_docs по вашему запросу.

13) Проверка готовности стенда

cd ~/openclaude-LLM-local/docs/rag-mcp-starter
chmod +x healthcheck.sh
./healthcheck.sh --mode full

14) Быстрый статус в одном экране

cd ~/openclaude-LLM-local/docs/rag-mcp-starter
chmod +x status.sh
./status.sh

15) Бэкап перед обновлениями

cd ~/openclaude-LLM-local/docs/rag-mcp-starter
chmod +x backup.sh
./backup.sh

16) Восстановление из бэкапа

cd ~/openclaude-LLM-local/docs/rag-mcp-starter
chmod +x restore.sh
./restore.sh --from /path/to/backup_YYYYMMDD_HHMMSS

17) Безопасное обновление стенда

cd ~/openclaude-LLM-local/docs/rag-mcp-starter
chmod +x upgrade.sh
./upgrade.sh