# OpenClaw Lite

`OpenClaw Lite` — Python lite-рантайм в стиле OpenClaw: локальный агент, Telegram-бот, skills с hot-reload, multi-provider LLM слой, pairing auth и self-modification через tools.

## Что внутри

- `openclaw_lite/core/runtime.py` — основной рантайм, session store, auth, reload и wiring tools/providers/skills.
- `openclaw_lite/core/agent.py` — агентный loop с progress callbacks, tool-repair и session end.
- `openclaw_lite/providers/` — `OpenAI`, `Gemini` и `OpenAI-compatible/custom` API.
- `openclaw_lite/skills/` — manifest-based skills: `skill.json` + `SKILL.md` + optional `main.py`.
- `openclaw_lite/interfaces/telegram_bot.py` — long-polling Telegram bot на `aiogram` с pairing/owner auth.
- `openclaw_lite/tools/telegram_tools.py` — Telegram actions для текста и медиа.
- `workspace/skills/self_describe/` — стартовый skill для объяснения структуры агента.

## Возможности

- Провайдеры: `OpenAI`, `Gemini`, `OpenAI-compatible/custom`.
- Модели: листинг через API провайдера и переключение на лету.
- Telegram: `/status`, `/safe on`, `/safe off`, `/mode`, `/providers`, `/models`, `/skills`, `/sessions`, `/end`, `/reload`, `/exec`, `/pair`, `/auth`, `/approve`, `/openclaw`.
- Pairing/access: owner по `user_id/chat_id`, обычный доступ по allowlists или pairing code.
- Agent mode: iterative tool-calling, progress updates, session close tool, self-repair после ошибок инструментов.
- Self-modification: файлы, config, skills, shell, web/HTTP tools.
- Shell modes: `safe`, `yolo`, `god`.

## Установка

Если проект лежит на `/sdcard`, обычный venv может падать из-за symlink-ограничений файловой системы. Надёжный вариант — держать venv вне `/sdcard`.

### Из PyPI

```bash
python3 -m venv --copies "$HOME/.venvs/openclaw-lite"
source "$HOME/.venvs/openclaw-lite/bin/activate"
python3 -m pip install -U openclaw-lite
```

### Из локального checkout в editable-режиме

```bash
python3 -m venv --copies "$HOME/.venvs/openclaw-lite"
source "$HOME/.venvs/openclaw-lite/bin/activate"
python3 -m pip install -U -e /sdcard/openclaw_lite[dev]
```

После установки доступны обе команды:

```bash
liteclaw --help
openclaw-lite --help
```

## Быстрый старт

```bash
cd /sdcard/openclaw_lite
liteclaw init --config config.yaml
liteclaw onboard --config config.yaml
liteclaw doctor --config config.yaml
liteclaw pair create --config config.yaml
liteclaw web --config config.yaml --host 127.0.0.1 --port 8787
liteclaw run --config config.yaml
```

Заполни в `config.yaml` или через env:

- `telegram.bot_token`
- `telegram.owner_user_ids` и/или `telegram.owner_chat_ids`
- `providers.items.openai.api_key`
- `providers.items.gemini.api_key`
- любые кастомные провайдеры в `providers.items.*`

## CLI

Основная терминальная команда — `liteclaw`; `openclaw-lite` доступен как совместимый alias того же CLI.

### Quickstart onboarding

```bash
liteclaw onboard --config config.yaml
```

Команда запускает интерактивный терминальный quickstart-мастер: Telegram Bot Token, выбор default provider, API key и модель. После подтверждения конфиг сохраняется, и бот стартует сразу в этом же процессе.

### Агентный запуск

```bash
liteclaw agent --config config.yaml "покажи статус и доступные skills"
```

`agent` — alias для `ask`.

По умолчанию внутренний agent mode уже без локального лимита на историю и число agent-шагов:

```yaml
runtime:
  max_tool_rounds: 0
  history_limit: 0
```

Здесь `0` трактуется как `unlimited`: рантайм не обрезает историю и не ставит внутренний cap на число шагов агента.

Пример продолжения того же локального сеанса:

```bash
liteclaw agent --config config.yaml --session-id main "создай skill для поиска"
liteclaw agent --config config.yaml --session-id main "теперь используй его"
```

### Просмотр конфига

```bash
liteclaw config show --config config.yaml
liteclaw config get --config config.yaml providers.default
```

### Просмотр локальных сеансов

```bash
liteclaw sessions --config config.yaml
liteclaw sessions --config config.yaml --json
```

### Pairing/access CLI

```bash
liteclaw pair create --config config.yaml
liteclaw pair show --config config.yaml --json
```

Новый пользователь в Telegram может ввести:

```text
/pair ABC123
```

И получить доступ без перезапуска рантайма.

## Директории

- `config.yaml` — основной конфиг.
- `workspace/skills/` — skills с hot reload.
- `data/` — session state и `auth.json`.
- `logs/tool_audit.log` — журнал tool calls.
- `backups/` — бэкапы конфига/файлов/skills.

## Security modes

- `safe` — строгий allowlist для shell.
- `yolo` — мягче, но всё ещё owner-only и в рамках проектных roots.
- `god` — полный доступ для владельца.

`/safe off` переводит текущую сессию в `god`: локально больше нет sandbox-ограничений, path-boundary ограничений, внутреннего shell-timeout и локального лимита на stdout/stderr. Ограничения со стороны самого LLM/API провайдера при этом остаются внешними и зависят уже от выбранной модели/endpoint.

## Skills

Каждый skill — директория вида:

```text
workspace/skills/<name>/
  skill.json
  SKILL.md
  main.py   # optional
```

`main.py` может вернуть prompt fragments и дополнительные tool definitions. После создания или обновления skill не нужен рестарт: достаточно `/reload` или tool `reload_skills`.


## Web UI

Локальная web-морда теперь есть. Она позволяет поставить `Telegram Bot Token`, `OpenAI API Key`, `Gemini API Key` и другие базовые поля без ручного редактирования `config.yaml`:

```bash
liteclaw web --config config.yaml --host 127.0.0.1 --port 8787
```

После сохранения открой Telegram и сделай `/reload`, либо перезапусти рантайм.

## Telegram trigger rules

Бот теперь отвечает только если:

- сообщение является reply на сообщение самого бота;
- или сообщение начинается с `/openclaw ...`;
- или в этом чате уже есть незакрытая agent-сессия этого же пользователя;
- или это одна из служебных команд вроде `/pair`, `/status`, `/safe`, `/exec`.

Обычный шум в чате он игнорирует, пока сессия не активирована. После первого `/openclaw` или reply на бота дальнейшие сообщения того же пользователя продолжают текущую сессию до `/end` или `session_end`. Ответы и служебные сообщения бот отправляет reply-ответом на исходное сообщение пользователя.
