knowledge-base/projects/dttb/openclaw.md

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
• 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)

# 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.

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.

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

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-режим:

#!/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.

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".

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

# Бэкап
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 внутри контейнера.

Обновление

# Версия установленная 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 — схема меняется.

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

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.

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

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.
• 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.