OpenClaw + NixOS: декларативный AI-ассистент с долгосрочной памятью / Хабр

Введение

Большинство AI-ассистентов не помнят ваш разговор за пределами одного окна чата. OpenClaw на NixOS решает эту проблему: декларативная конфигурация, долгосрочная память через QMD, Telegram-канал, GLM-4.7-flash - и всё это воспроизводится на любой машине одной командой.

Для кого эта статья?

Для разработчиков и системных администраторов, которые:

уже используют NixOS;
хотят превратить AI-ассистента в воспроизводимую инфраструктуру;
ищут готовую модульную конфигурацию с Telegram, памятью и секретами.

Предварительные требования

Перед тем как повторять примеры из статьи, убедитесь, что у вас настроено:

Архитектура решения

OpenClaw Gateway связывает все компоненты:

Telegram - канал взаимодействия с пользователем;
Workspace - файлы личности и поведения ассистента;
LLM - модель для генерации ответов;
QMD - долгосрочная память на базе векторного поиска.

Почему NixOS?

Потому что мы хотим описать сложную систему один раз и получить идентичный результат на любой машине. Без Nix каждый компонент - ручная операция, подверженная дрифту версий. С Nix всё это становится данными в flake.nix.

Разбор flake.nix

Начнём с корня:

{
  description = "NixOS configuration with Hyprland";

  inputs = {
    nixpkgs.url = "nixpkgs";
    home-manager.url = "github:nix-community/home-manager";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";
    agenix.url = "github:ryantm/agenix";
    agenix.inputs.nixpkgs.follows = "nixpkgs";
    nix-openclaw.url = "github:openclaw/nix-openclaw";
    openclaw-workspace = {
      url = "path:/home/vokrob/.config/openclaw";
      flake = false;
    };
  };

  outputs = { self, nixpkgs, home-manager, agenix, nix-openclaw, openclaw-workspace, ... }@inputs: {
    nixosConfigurations.vokrob = nixpkgs.lib.nixosSystem {
      specialArgs = { inherit nix-openclaw openclaw-workspace; };
      system = "x86_64-linux";
      modules = [
        home-manager.nixosModules.home-manager
        agenix.nixosModules.default
        ./hosts/nixos
      ];
    };
  };
}

Ключевые моменты:

nix-openclaw - flake из github:openclaw/nix-openclaw, включающий модули Home Manager, overlay для пакетов и бинарный кэш на cache.garnix.io. Благодаря garnix сборка OpenClaw не пересобирает зависимости с нуля;
openclaw-workspace - путь без flake. Директория с файлами, которые определяют поведение ассистента;
specialArgs - механизм передачи внешних инпутов вглубь модульной системы.

Хост единственный - vokrob. В реальном проекте сюда можно добавить несколько хостов: домашний ПК, сервер, ноутбук - с одинаковой конфигурацией OpenClaw.

Модульная архитектура

Конфигурация разделена на два уровня.

Системные модули

Подключаются через modules/nixos/default.nix:

Модуль	Назначение
`base.nix`	Загрузчик, ядро
`networking.nix`	NetworkManager
`services.nix`	Hyprland, AmneziaWG
`security.nix`	Polkit: отключение питания без пароля
`users.nix`	vokrob, agenix, zsh

В base.nix применяется overlay:

nixpkgs.overlays = [
  nix-openclaw.overlays.default
  (import ../../overlays)
];

Это добавляет пакеты OpenClaw в pkgs, включая openclaw-gateway.

Пользовательские модули

Подключаются через modules/home/default.nix. Ключевой модуль: features/openclaw.nix.

Также в hosts/nixos/default.nix подключается модуль OpenClaw как shared-модуль Home Manager:

home-manager.sharedModules = [nix-openclaw.homeManagerModules.openclaw];

sharedModules делает модуль доступным во всех конфигурациях Home Manager, включая другие хосты.

Разбор ключевого модуля

Файл modules/home/features/openclaw.nix - основа всей конфигурации.

Workspace

programs.openclaw.workspace.bootstrapFiles = {
  agents = "${openclaw-workspace}/AGENTS.md";
  soul = "${openclaw-workspace}/SOUL.md";
  tools = "${openclaw-workspace}/TOOLS.md";
  identity = "${openclaw-workspace}/IDENTITY.md";
  user = "${openclaw-workspace}/USER.md";
};

Bootstrap-файлы определяют личность ассистента:

AGENTS.md - роли агентов и правила маршрутизации;
SOUL.md - базовая инструкция;
TOOLS.md - описание инструментов и команд;
IDENTITY.md - представление и взаимодействие ассистента;
USER.md - информация о пользователе.

Эти файлы находятся в ~/.config/openclaw/, что позволяет менять поведение ассистента без пересборки системы. Однако сам факт их наличия декларируется в Nix.

Секреты

programs.openclaw.environment = {
  ZHIPU_API_KEY = "/run/agenix/openclaw-zhipu-key";
  OPENCLAW_GATEWAY_TOKEN = "/run/agenix/openclaw-gateway-token";
};

Значения - это пути к файлам, а не сами ключи. OpenClaw читает секреты из файлов, что сочетается с agenix. Nix подставляет пути на этапе сборки. Agenix расшифровывает секреты на этапе активации конфигурации и размещает их в /run/agenix/.

Токен для Telegram передаётся через tokenFile:

channels.telegram.tokenFile = "/run/agenix/openclaw-telegram-token";

Интеграции

config = {
  gateway.mode = "local";

  channels.telegram = {
    tokenFile = "/run/agenix/openclaw-telegram-token";
    allowFrom = [5748618304];
  };
};

Режим local означает, что gateway работает без привязки к OpenClaw Cloud. Gateway запускается на той же машине, слушает локальный порт и авторизует запросы через gateway token из /run/agenix/openclaw-gateway-token. Доступ к каналу ограничен списком allowFrom.

GLM-4.7-flash

models.providers.openai = {
  baseUrl = "https://open.bigmodel.cn/api/paas/v4";
  apiKey = {
    source = "env";
    provider = "default";
    id = "ZHIPU_API_KEY";
  };
  models = [{
    name = "glm-4.7-flash";
    id = "glm-4.7-flash";
    api = "openai-completions";
    contextWindow = 131072;
  }];
};

Несмотря на то, что провайдер называется openai, baseUrl ведёт на API Z.ai, потому что Z.ai предоставляет OpenAI-совместимый эндпоинт.

api = "openai-completions" - OpenClaw использует стандартный OpenAI SDK для общения с моделью. Модель glm-4.7-flash - бесплатная с контекстным окном 128K токенов.

QMD

memory.backend = "qmd";

Одна строка включает долгосрочную память на базе Qdrant.

QMD - сайдкар, не требующий отдельного сервера.

Как это работает:

сообщения от пользователя и ответы ассистента векторизуются;
эмбеддинги сохраняются в QMD с метаданными;
семантический поиск по новому запросу находит фрагменты из прошлого;
эти фрагменты подмешиваются в промпт как контекст.

Это отличает OpenClaw от обычного чата с LLM: ассистент помнит контекст между сессиями.

Доказательство:

Команды “запомни” и “забудь” работают через MEMORY.md. QMD добавляет поверх этого семантический поиск по всей истории.

Повышенные привилегии

tools.elevated = {
  enabled = true;
  allowFrom = {
    telegram = [5748618304];
  };
};

Секция tools.elevated даёт определённым пользователям доступ к опасным инструментам: выполнение команд на хосте (выключение и перезагрузка), установка пакетов, управление процессами и системой в целом.

Вы пишете в Telegram “Выключи компьютер через 10 минут” - агент выполняет shutdown -h +10.

Дополнительные опции

Конфигурация:

agents.defaults = {
  model.primary = "openai/glm-4.7-flash";
  thinkingDefault = "low";
  compaction.reserveTokensFloor = 20000;
};

reloadScript.enable = true;

bundledPlugins = {
  summarize.enable = true;
};

thinkingDefault - глубина рассуждений агента;
compaction.reserveTokensFloor - резервирует 20K токенов под память, инструменты и системный промпт;
reloadScript - генерирует скрипт для перезагрузки конфигурации OpenClaw без перезапуска gateway;
bundledPlugins.summarize - автоматическая суммаризация URL и PDF.

Gateway запускается как systemd user service:

сервис стартует при входе пользователя в систему;
перезапускается при падении;
логи - journalctl --user -u openclaw-gateway -f;
в случае проблем - systemctl --user restart openclaw-gateway.

Управление секретами

Три секрета обслуживают OpenClaw:

Секрет	Назначение
`openclaw-telegram-token.age`	Токен Telegram-бота
`openclaw-zhipu-key.age`	API-ключ Z.ai
`openclaw-gateway-token.age`	Токен для локального gateway

Определение:

age.secrets = {
  "openclaw-telegram-token" = {
    file = ../../secrets/openclaw-telegram-token.age;
    owner = "vokrob";
    group = "users";
    mode = "0400";
  };
};

Agenix шифрует файлы с помощью age. Ключ хранится локально в ~/.config/agenix/age-key.txt. Расшифровка происходит на этапе активации системы. В Nix store секреты никогда не попадают.

Ключи не хранятся в /nix/store/ и не могут быть случайно закоммичены или оказаться в бинарном кэше garnix.io. Даже получив доступ к store, злоумышленник не увидит API-ключи.

Жизненный цикл

Вот как работает полный цикл обработки одного сообщения:

вы пишете сообщение Telegram-боту;
Telegram пересылает его на gateway;
gateway проверяет allowFrom;
gateway вызывает QMD для семантического поиска контекста из прошлых разговоров;
gateway формирует промпт: системные инструкции + контекст из памяти + ваше сообщение;
промпт отправляется в GLM-4.7-flash через API;
ответ модели gateway сохраняет через QMD как новый фрагмент памяти;
ответ отправляется обратно в Telegram.

Ошибки и решения

Сервис не стартует

Причина: agenix не применил скрипт активации.

Решение: выполните sudo nixos-rebuild switch и проверьте наличие файлов в /run/agenix/:

ls -la /run/agenix/

Если файлов нет, проверьте определения age.secrets.

Telegram-бот не отвечает

Причина: неверный allowFrom или токен бота.

Решение: узнайте ваш Telegram ID через @userinfobot и сравните с указанным в allowFrom. Проверьте токен:

journalctl --user -u openclaw-gateway | grep -i telegram

QMD не находит контекст

Причина: эмбеддинги ещё не накопились.

Решение: продолжайте общаться с ассистентом.

Несоответствие токена gateway

Причина: токен не совпадает с тем, что ожидает gateway.

Решение: пересоздайте токен:

agenix -e secrets/openclaw-gateway-token.age

Перезапустите сервис:

systemctl --user restart openclaw-gateway

Заключение

С OpenClaw на NixOS вы получаете воспроизводимого AI-ассистента с долгосрочной памятью.

Преимущества:

идентичная конфигурация на новой машине за несколько минут;
откат к предыдущему поколению;
модуль переиспользуется на нескольких хостах.

Склонируйте репозиторий, замените секреты и соберите одной командой.