# OpenClaw — основной AI-бот (LXC 137)

Справочник по установке, настройке и починке OpenClaw. Обновлён 2026-04-17.

## Что это

**OpenClaw** (в Telegram/Nextcloud — "Максимка") — основной AI-бот Олега. Multi-channel AI gateway: принимает сообщения из Telegram и Nextcloud Talk, отвечает через OmniRoute (бесплатные модели) и умеет делегировать сложные задачи на code-server (Opus 4.7 через Max подписку).

- **NPM пакет:** [`openclaw`](https://www.npmjs.com/package/openclaw)
- **GitHub:** https://github.com/openclaw/openclaw
- **Автор конфига:** установлен и ведётся Олегом под персонажа "Максимка" 🤖

## Где живёт

| Параметр | Значение |
|----------|----------|
| Proxmox LXC | **137** (hostname `openclaw`) |
| IP | 10.0.0.239 (LAN) / 100.70.167.54 (NetBird) |
| CPU / RAM | 2 vCPU / 6 GB |
| Node.js | v24.x |
| Доступ | `sshpass -p '1qaz!QAZ' ssh root@10.0.0.250 "pct exec 137 -- bash"` |

## Установка (из чистого LXC)

```bash
# Ubuntu LXC с Node ≥ 20
apt update && apt install -y nodejs npm
npm install -g openclaw
openclaw setup              # интерактивный онбординг
openclaw configure          # настройка каналов, моделей, креденшалов
```

Бинарь попадает в `/usr/bin/openclaw` (shim), код в `/usr/lib/node_modules/openclaw/`.

## Структура на диске

```
/root/.openclaw/                      ← state dir (OPENCLAW_STATE_DIR)
├── openclaw.json                     ← главный config
├── openclaw.json.bak                 ← автобэкап (последний)
├── openclaw.json.bak-YYYY-MM-DD-...  ← ручные бэкапы (сам делай перед правками)
├── agents/
│   ├── main/
│   │   ├── sessions/
│   │   │   ├── sessions.json         ← индекс сессий (key → id, model, tokens)
│   │   │   ├── <uuid>.jsonl          ← полная переписка сессии (messages, tool calls)
│   │   │   └── <uuid>.jsonl.reset.*  ← архив после /reset
│   │   └── agent/models.json         ← модели доступные агенту (в кэше)
│   ├── codex/
│   └── claude-code/
├── nextcloud-talk/                   ← state Nextcloud Talk канала
├── credentials/
├── memory/                           ← векторная память (если включена)
├── canvas/                           ← Canvas host контент
├── delivery-queue/
├── flows/
├── exec-approvals.json               ← whitelist команд для exec tool
└── storage.sqlite? (нет в openclaw, только у omniroute)

/root/clawd/                          ← рабочая папка бота (workspace)
├── IDENTITY.md                       ← личность бота (имя, язык, аватар)
├── INFRASTRUCTURE.md                 ← карта инфраструктуры для бота
├── TOOLS.md                          ← креды, порты, ссылки (важно держать актуальным)
├── DELEGATION.md                     ← инструкция как делегировать на Opus/code-server
├── MEMORY.md                         ← что помнить постоянно
├── SOUL.md                           ← характер, вайб
├── USER.md                           ← что знать про пользователя (Олега)
├── AGENTS.md                         ← про суб-агентов
├── HEARTBEAT.md                      ← статус-флаг для self-check
├── HAPP-VPN.md                       ← текущие VPN настройки пользователя
├── tasks.md                          ← TODO бота
├── scripts/                          ← рабочие скрипты (wrapper, monitor, cron)
│   ├── claude-code-wrapper.sh        ← **делегирование на Opus 4.7**
│   ├── email_monitor.py              ← cron */10, Авито уведомления
│   ├── znam-pairing-check.sh         ← cron */3
│   └── nextcloud-talk-bot.py         ← legacy (старый бот, не используется)
├── knowledge-base/                   ← база знаний бота
├── memory/                           ← его заметки
├── projects/                         ← проекты
├── prompts/                          ← системные промпты
└── claude-code-sessions/             ← сессии claude CLI на этой машине (не на code-server)

/root/.config/systemd/user/
└── openclaw-gateway.service          ← **systemd --user** service (не /etc/systemd/system!)
```

## Сервис (systemd user)

OpenClaw gateway — systemd **user**-level unit, не system. Все команды с `--user`.

```bash
systemctl --user status openclaw-gateway.service
systemctl --user restart openclaw-gateway.service
systemctl --user reset-failed openclaw-gateway.service  # при restart loop
journalctl --user -u openclaw-gateway.service -n 50 --no-pager
```

Unit запускает:
```
ExecStart=/usr/bin/node /usr/lib/node_modules/openclaw/dist/index.js gateway --port 18789
```

Порты:
- **18789** — gateway (WebSocket + HTTP), в `.env` `OPENCLAW_GATEWAY_PORT`
- **18789/__openclaw__/canvas/** — Canvas host (UI)
- Если запущен в `--dev`: gateway 19001

## Конфигурация: `openclaw.json`

Единый JSON, валидируется zod-схемой с `additionalProperties: false` на большинстве секций. **Любой лишний ключ ломает старт** с `Config invalid`.

### Просмотр и правка

```bash
openclaw config file                        # путь к активному конфигу
openclaw config get gateway.port            # значение по dot-path
openclaw config set gateway.port 18789      # изменить
openclaw config unset acp.agents            # удалить ключ
openclaw config schema                      # полная JSON schema — узнать какие поля допустимы
openclaw config validate                    # проверить без рестарта
openclaw doctor                             # диагностика
openclaw doctor --fix                       # автофикс (не всесильный, делай бэкап)
```

### Секции конфига (по schema)

- `env` — переменные окружения gateway
- `update` — auto-update настройки, канал релизов
- `agents` — defaults (модель, workspace, concurrency) + **list** (массив агентов, не объект!)
- `acp` — Agent Control Protocol. Допустимые ключи: `enabled, dispatch, backend, defaultAgent, allowedAgents, maxConcurrentSessions, stream, runtime`. **`agents` запрещён!**
- `auth` — API ключи профилей
- `channels` — telegram, nextcloud-talk, discord и т.д.
- `messages` — маршрутизация сообщений
- `commands` — кастомные slash-команды
- `hooks` — webhook и event-хуки
- `skills` — skill-паки
- `tools` — browser, search, file, runtime и пр.
- `gateway` — настройки WS-сервера (порт, auth, binding)
- `wizard` — состояние setup wizard
- `meta` — версия/метаданные
- `logging` — уровни и вывод логов
- `browser` — headless browser настройки
- `ui` — UI preferences
- `models` — провайдеры + каталог моделей
- `bindings` — key bindings
- `broadcast` — broadcast/notification
- `audio` — входы/выходы аудио
- `session` — управление сессиями и persistence
- `cron` — scheduled tasks через gateway
- `web` — web server / API
- `discovery` — service discovery (Tailscale + CoreDNS)
- `canvasHost` — Canvas
- `talk` — голос/речь
- `plugins` — плагины
- `diagnostics` — OpenTelemetry, cache-trace
- `cli` — CLI баннер, startup
- `secrets` — secret providers
- `mcp` — MCP-сервера

### Провайдеры моделей (наш стек)

В `openclaw.json → models.providers` у Олега настроены:
- `openrouter`
- `anthropic`
- `zai` — OmniRoute через ZenAI адаптер
- `omniroute` — прямой OmniRoute (localhost:20128 на code-server)
- `zai-orig` — оригинальный zai endpoint

### Модели в сессиях — **НЕ ТРОГАЙ**

В `agents/main/sessions/sessions.json` и `agent/models.json` модели хранятся в формате:
- `kr/claude-sonnet-4.5` — Kiro провайдер
- `cx/gpt-5.4` — Codex (OpenAI)
- `gh/claude-sonnet-4.5` — GitHub Models
- `glm/glm-5.1` — Z.AI GLM
- `gemini-cli/gemini-2.5-pro` — Google Gemini CLI

**Не добавляй префикс `zai/`!** Это прямая адресация Kiro/Codex/GH/GLM провайдеров. Работает.

`openclaw models list` показывает только `zai/*` — это view того что openclaw регистрирует локально, но провайдеры резолвят и `kr/...` напрямую.

Лог вида:
```
[diagnostic] FailoverError: Unknown model: kr/claude-sonnet-4.5 ... next=zai/kr/claude-sonnet-4.5
```
— **безвредный warning** с автофоллбеком. Игнорируй. Это НЕ причина того что бот не отвечает.

## Делегирование на code-server (Opus 4.7)

Для сложных задач (большой рефакторинг, генерация кода) бот делегирует на LXC 132 (code-server) где установлен Claude Code CLI с Max подпиской.

**Wrapper:** `/root/clawd/scripts/claude-code-wrapper.sh`

Текущая (рабочая, 2026-04-17) реализация — non-interactive print-режим:
```bash
#!/bin/bash
# Wrapper: делегирует задачу на code-server (LXC 132), Opus 4.7.
# Использование:
#   claude-code-wrapper.sh "текст задачи"
#   echo "задача" | claude-code-wrapper.sh
set -e
if [ -t 0 ] && [ $# -eq 0 ]; then
  echo "ERROR: нужен prompt в аргументе или на stdin" >&2
  exit 2
fi
PROMPT="${*:-$(cat)}"
PROMPT_B64=$(printf %s "$PROMPT" | base64 -w0)
ssh -o StrictHostKeyChecking=no root@10.0.0.250 \
  "pct exec 132 -- bash -c \"cd /root && echo $PROMPT_B64 | base64 -d | claude -p --output-format text\""
```

Ключевое: **`claude -p`** (print-режим). Без `-p` запускается REPL и виснет.

Инструкция для самого бота — в `/root/clawd/DELEGATION.md`.

## Каналы

### Telegram
- Bot token хранится в `channels.telegram.token` (через `ref:env` или напрямую)
- `dmPolicy` и `groupPolicy` — доступ. **Open policy небезопасно** (security audit ругается), используй `allowlist` + `allowFrom`
- Bot username указан в openclaw status

### Nextcloud Talk
- URL `http://10.0.0.230:11001` (Nextcloud AIO)
- Пользователь `maximka` / `MaximkaBot2026`
- Основная беседа token: `aecax6yg`
- Админ: `admin` / `1qaz!QAZ`

## Частые проблемы и их решения

### Проблема: `Config invalid ... Unrecognized key`
Новая версия openclaw ужесточила schema. Старые поля больше не принимаются.
1. `cp /root/.openclaw/openclaw.json /root/.openclaw/openclaw.json.bak-$(date +%F-%H%M)`
2. `openclaw doctor --fix` — мигрирует что может
3. Если не помогло — получить expected schema: `openclaw config schema` (JSON), сравнить со своим config
4. Частые исправления:
   - `acp.agents` → перенести содержимое в `agents.list` (**массив**!), удалить из acp
   - `agents.list` как `{"name": {...}}` → переделать в `[{"id":"name", ...}]`
   - Удалить неизвестные top-level ключи

### Проблема: Gateway падает с `Cannot find module 'dist/index.js'`
Временная ошибка во время `npm install` (файлы распаковываются). Подождать, сервис сам поднимется через Restart=always.

### Проблема: Bot "залип" — не отвечает в Telegram/Talk
Порядок проверки:
1. `pct status 137` — LXC запущен?
2. `pct exec 137 -- systemctl --user is-active openclaw-gateway.service` — gateway активен?
3. `pct exec 137 -- openclaw status` — каналы ON? сессии есть?
4. `journalctl --user -u openclaw-gateway.service --since "10 min ago" | grep -iE "error|fail"` — последние ошибки
5. Если gateway в restart-loop: `systemctl --user reset-failed openclaw-gateway.service` перед рестартом

### Проблема: Бот застревает при делегировании на Opus
Wrapper запускал `claude` без `-p` → интерактивный REPL → висел. Решение уже в wrapper (2026-04-17). Если опять: проверить что `/root/clawd/scripts/claude-code-wrapper.sh` использует `claude -p --output-format text`, а не голый `claude`.

### Проблема: периодические сбои `sendChatAction failed: Network request failed` и "Something went wrong" (причина — IPv6)

**Корень (обнаружено 2026-04-17):** в LXC 137 IPv6 настроен, но наружу не маршрутизируется. `curl -4 https://api.telegram.org/` → 302 OK; `curl -6 https://api.telegram.org/` → connection failed. Node.js по умолчанию может резолвить AAAA первым и застревать на IPv6. Это даёт случайные `Network request failed` в Telegram API → у бота не отправляется typing-индикатор и ответ, пользователь видит "Something went wrong".

**Починка:** форсировать IPv4 через `NODE_OPTIONS=--dns-result-order=ipv4first` в systemd unit.

```bash
UNIT=/root/.config/systemd/user/openclaw-gateway.service
cp $UNIT $UNIT.bak-$(date +%F-%H%M)
sed -i "/^Environment=OPENCLAW_GATEWAY_PORT=/a Environment=NODE_OPTIONS=--dns-result-order=ipv4first" $UNIT
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway.service
```

Проверка: после рестарта в логах gateway не должно быть `sendChatAction failed: Network request failed` при нормальной работе.

### Проблема: `FailoverError: Unknown model: kr/...`

Ошибка пользователю "⚠️ Something went wrong while processing your request. Please try again, or use /new to start a fresh session." отправляется OpenClaw когда *external run* не вернул осмысленную ошибку (не OAuth, не API key, не session mismatch — см. `buildExternalRunFailureText` в `agent-runner.runtime-*.js`). То есть это fallback-сообщение для **неклассифицированных** ошибок.

**Корень на нашей инсталляции (2026-04-17):**
В `openclaw.json → models.providers` **дублированы** два провайдера, указывающие на один и тот же OmniRoute (`10.0.0.179:20128`):
- `zai` — модели `kr/claude-sonnet-4.5`, `gh/claude-sonnet-4.5`, `glm/glm-5.1`, `cx/gpt-5.4`
- `omniroute` — те же модели

В 2026.4.15 openclaw регистрирует модели **с префиксом провайдера** (`zai/kr/...`). Запрос без префикса (`kr/claude-sonnet-4.5`, как хранится в старых сессиях) не резолвится → FailoverError → fallback на `zai/kr/claude-sonnet-4.5` через `agents.defaults.model.fallbacks`. Fallback обычно успешен (+3-8 сек к ответу), но иногда падает → пользователь видит "Something went wrong".

**Как починить окончательно (рекомендуется):**

```bash
# Бэкап
cp /root/.openclaw/openclaw.json /root/.openclaw/openclaw.json.bak-dedup-$(date +%F)

# Вариант A: удалить дубликат-провайдер omniroute (оставить zai)
openclaw config unset models.providers.omniroute

# Вариант B: обновить model в индексе сессий (НЕ в .jsonl файлах!)
python3 <<'PY'
import json
p = '/root/.openclaw/agents/main/sessions/sessions.json'
d = json.load(open(p))
for k, v in d.items():
    m = v.get('model')
    if m and not m.startswith('zai/') and not m.startswith('openai/'):
        v['model'] = 'zai/' + m
json.dump(d, open(p, 'w'), indent=2)
PY

# После любого варианта:
systemctl --user restart openclaw-gateway.service
```

**ВАЖНО — что НЕ делать (уроки 2026-04-17):**
- НЕ трогай `agent/models.json` — там `id` моделей из registry провайдеров; замена id на `zai/...` сломает Kiro провайдер (бот "перестаёт отвечать").
- НЕ трогай `.jsonl` файлы в `sessions/` — это неизменяемая история сообщений.
- **Даже точечное изменение поля `model` в sessions.json для одной сессии — ломает бота** (проверено: обновил только `agent:main:telegram:group:@heartbeat` с `kr/...` на `zai/kr/...`, бот перестал отвечать, откат из бэкапа вернул работу). Причина не совсем ясна, возможно конфликт между session.model и зарегистрированными в runtime моделями.
- НЕ удалять провайдер `zai` или `omniroute` — оба пробовали, ломает.

**Реальная причина периодических "Something went wrong" — IPv6**, не провайдеры моделей. См. раздел выше про `NODE_OPTIONS=--dns-result-order=ipv4first`. FailoverError `kr/...` → `zai/kr/...` — это автофоллбек который работает, не трогай.

### Проблема: CPU/load высокий
В LXC 137 `/proc/loadavg` показывает **нагрузку хоста Proxmox**, не контейнера. Смотри реальную нагрузку через `top`/`ps aux --sort=-%cpu` внутри контейнера.

## Обновление

```bash
# Версия установленная vs актуальная
cat /usr/lib/node_modules/openclaw/package.json | grep version
npm view openclaw version

# Обновить
npm install -g openclaw@latest

# Перезапустить gateway
systemctl --user restart openclaw-gateway.service
systemctl --user status openclaw-gateway.service

# После обновления часто нужно:
openclaw doctor --fix
```

**Перед обновлением делай бэкап** `/root/.openclaw/openclaw.json` — схема меняется.

## Полезные команды

```bash
openclaw status                         # общий статус + сессии + каналы
openclaw status --all                   # расширенный
openclaw logs --follow                  # live tail gateway
openclaw gateway probe                  # диагностика reachability
openclaw models list                    # модели (только zai/*)
openclaw sessions list                  # все сессии
openclaw doctor                         # health-check
openclaw security audit                 # аудит безопасности (ACP/каналы)
openclaw security audit --deep          # подробный
openclaw memory status --deep           # состояние векторной памяти
openclaw --version                      # версия
openclaw config file                    # путь к config
openclaw config schema                  # JSON schema
```

## Что связано с OpenClaw (не путать)

- **LXC 129** — `clawdbot-1` (старый бот, @maxim_dttb_bot). **Удалён 2026-04-14**. Данные перенесены в `/root/clawd/` на LXC 137.
- **LXC 132** — `code-server` (VS Code IDE + OmniRoute + CLIProxy). Не бот, а dev-среда + backend для ресёрча.
- **LXC 134** — `ZnamSecurityBot`. Отдельный Telegram-бот безопасности, не OpenClaw.

## Бэкап и восстановление

```bash
openclaw backup create                  # архив state (/root/.openclaw/backups/)
openclaw backup verify <archive>        # проверка
# Или ручной:
tar czf /root/openclaw-state-$(date +%F).tar.gz /root/.openclaw /root/clawd
```

Ключевые файлы для ручного бэкапа:
- `/root/.openclaw/openclaw.json` — конфиг
- `/root/.openclaw/agents/main/sessions/` — история сессий
- `/root/clawd/*.md` — personality и инструкции
- `/root/.config/systemd/user/openclaw-gateway.service` — systemd unit

## История изменений (релевантное)

- **2026-04-14** — LXC 129 (старый Clawdbot) удалён, данные в `/root/clawd/` на LXC 137. Решение: [decisions/2026-04-14-openclaw-claude-code-pipeline.md](../../decisions/2026-04-14-openclaw-claude-code-pipeline.md).
- **2026-04-17** — обновление 2026.4.10 → 2026.4.15, починка config (удалён `acp.agents`, `agents.list` object → удалён), починка wrapper (`claude` → `claude -p`), создан DELEGATION.md. Решение: [decisions/2026-04-17-code-server-upgrade.md](../../decisions/2026-04-17-code-server-upgrade.md).