PostgreSQL-адаптер в OpenClaw: что уходит в Postgres, а что остаётся на SQLite

Коротко

PostgreSQL-адаптер в OpenClaw экспериментальный: в Postgres уезжает только хранилище Workboard, остальные хранилища остаются на SQLite.
DSN хранится в секрете по ссылке типа env, file или exec; ссылки типа store отклоняются.
Смена database.engine не переносит данные: перенос делает команда openclaw database port.
Postgres не даёт нескольких активных Gateway и может потерять последние подтверждённые коммиты при сбое.

Сверено с документацией OpenClaw 2026.10.10, 3 ноября 2026.

OpenClaw по умолчанию использует SQLite, а перенос хранилищ на PostgreSQL делает отдельная команда.

Что нужно заранее

Отдельная база PostgreSQL, выделенная под OpenClaw, и роль, которая может создавать схемы и таблицы.
PostgreSQL 16 или новее, кодировка UTF8 на сервере и клиенте. Эти условия проверяются один раз при загрузке каждого физического хранилища.
DSN в менеджере секретов, переданный в окружение Gateway.
Остановленный Gateway на время переноса данных. Команда отказывается работать при живом владельце и сама сервисы не останавливает.
Хранилище Workboard в установке: сейчас это единственное хранилище с поддержкой PostgreSQL.

Что уезжает в PostgreSQL, а что остаётся на SQLite

Ключ database.engine принимает "sqlite" или "postgres". PostgreSQL применяется к каждому зарегистрированному хранилищу, у которого есть схема PostgreSQL. Хранилище без такой схемы остаётся на SQLite.

Workboard: единственное хранилище с поддержкой PostgreSQL.
Общее состояние, хранилище агентов и сессий, прочие хранилища продолжают работать на SQLite.
Incognito-хранилище остаётся только в памяти.
Хранилище с поддержкой PostgreSQL никогда молча не откатывается на SQLite, если соединение или допуск схемы не прошли.

У каждого хранилища в PostgreSQL остаётся маленький SQLite-якорь по обычному локальному пути. Якорь хранит UUID хранилища, движок и имя схемы. Новые схемы получают имя <schemaPrefix>_<store>_<uuid-prefix>, а перенос якоря сохраняет идентичность.

Конфиг: engine, DSN и schemaPrefix

Строку DSN положите в секрет, а в конфиге укажите ссылку на него.

{
  database: {
    engine: "postgres",
    postgres: {
      connection: { source: "env", provider: "default", id: "OPENCLAW_DATABASE_DSN" },
      schemaPrefix: "openclaw",
    },
  },
}

database.engine по умолчанию "sqlite", допустимы "sqlite" и "postgres".
database.postgres.connection обязателен для PostgreSQL: строка DSN или ссылка на секрет типа env, file или exec.
database.postgres.schemaPrefix по умолчанию "openclaw": от 1 до 27 строчных букв, цифр или подчёркиваний, начиная с буквы или подчёркивания. Существующие якоря сохраняют записанную схему.

SecretRef для DSN

OPENCLAW_DATABASE_DSN в этом примере — имя секрета, а не переменная выбора движка. Передайте его в окружение Gateway через менеджер секретов.

env: имя переменной по маске ^[A-Z][A-Z0-9_]{0,127}$.
file: абсолютный JSON-указатель вида /providers/openai/apiKey, либо литерал value для провайдера в режиме singleValue.
exec: идентификатор по маске ^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$, поддерживаются селекторы вида secret#json_key.
Ссылки типа store для DSN отклоняются: их разрешение требует общей базы, которую это соединение ещё должно открыть.

Для file и exec нужен зарегистрированный провайдер с тем же источником. Псевдонимы источников задаются в secrets.defaults.

{
  secrets: {
    providers: {
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
        jsonOnly: true,
      },
    },
    defaults: {
      file: "filemain",
      exec: "vault",
    },
  },
}

Ссылка разрешается на хосте, а подключение передаётся воркерам базы. DSN считается учётными данными, его не кладут в логи и диагностические снимки. Неверные ссылки на подключение показывает openclaw doctor.

Как перенести существующий Workboard

Остановите Gateway через того владельца сервиса, который им управляет, и остановите встроенных агентов с тем же каталогом состояния.
Задайте database.postgres.connection, но оставьте database.engine без изменений: переключение выполнит сама команда.
Прогоните пробный перенос: он проверяет предпосылки только на чтение и не создаёт манифест, копию или целевое пространство имён.

openclaw database port --to postgres --dry-run
openclaw database port --to postgres

Команда перечисляет все зарегистрированные хранилища Workboard, включая отключённые хранилища плагина, но не создаёт недостающие. Машиночитаемый вывод без строк подключения и данных даёт флаг --json. После успеха запустите Gateway через владельца сервиса.

Как проверить

Перезапустите Gateway после смены движка.
Запустите openclaw doctor и посмотрите выбранный движок по каждому хранилищу.
Убедитесь, что SQLite-якорь остался на прежнем локальном пути.

openclaw doctor

Doctor предупреждает, что PostgreSQL экспериментальный, и перечисляет хранилища, оставшиеся на SQLite из-за отсутствия схемы.

Если что-то пошло не так

Doctor сообщает о неверных ссылках на подключение: ссылки типа store для DSN недопустимы, замените их на env, file или exec. Для file и exec проверьте запись secrets.providers с тем же источником.
Перенос прерван: запуск блокируется манифестом <stateDir>/recovery/database-port/manifest.json. Держите Gateway остановленным и завершите или откатите операцию.
Возврат на SQLite: сначала сделайте обратный перенос, и только потом понижайте версию через npm, pnpm или Homebrew. Эти пути обходят проверки совместимости движков, которые делает openclaw update.
Обновление на версию без postgres в openclaw.databaseEngines отклоняется до изменения данных: сделайте обратный перенос текущим бинарником или оставайтесь на текущей версии.
openclaw backup create с Postgres требует остановленного Gateway, а openclaw backup sqlite отказывается работать с Postgres-якорем.
Сбой сервера или ОС может потерять недавно подтверждённые коммиты: у соединений выставлен synchronous_commit=off.