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

Введение

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

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

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

• уже используют NixOS;

• хотят превратить AI-ассистента в воспроизводимую инфраструктуру;

• ищут готовую модульную конфигурацию с Telegram, памятью и секретами.

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

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

• Flakes;

• Home Manager;

• agenix;

• Telegram-бот;

• API-ключ.

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

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 применяется 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 — сайдкар, не требующий отдельного сервера.

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

1. сообщения от пользователя и ответы ассистента векторизуются;

2. эмбеддинги сохраняются в QMD с метаданными;

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

4. эти фрагменты подмешиваются в промпт как контекст.

Это отличает 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:

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

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-ключи.

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

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

1. вы пишете сообщение Telegram-боту;

2. Telegram пересылает его на gateway;

3. gateway проверяет allowFrom;

4. gateway вызывает QMD для семантического поиска контекста из прошлых разговоров;

5. gateway формирует промпт: системные инструкции + контекст из памяти + ваше сообщение;

6. промпт отправляется в GLM-4.7-flash через API;

7. ответ модели gateway сохраняет через QMD как новый фрагмент памяти;

8. ответ отправляется обратно в 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-ассистента с долгосрочной памятью.

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

• идентичная конфигурация на новой машине за несколько минут;

• откат к предыдущему поколению;

• модуль переиспользуется на нескольких хостах.

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