Podman

Запускайте OpenClaw Gateway у безпривілейованому контейнері Podman, яким керує поточний користувач без прав root.

Модель роботи:

• Podman запускає контейнер Gateway.
• Встановлений на хості CLI openclaw слугує площиною керування.
• За замовчуванням постійні дані зберігаються на хості в ~/.openclaw.
• Для повсякденного керування використовуйте openclaw --container <name> ... замість sudo -u openclaw, podman exec або окремого службового користувача.

Передумови

• Podman у безпривілейованому режимі
• CLI OpenClaw, установлений на хості
• Необов’язково: systemd --user, якщо потрібен автоматичний запуск під керуванням Quadlet
• Необов’язково: sudo, лише якщо потрібно виконати loginctl enable-linger "$(whoami)" для збереження автозапуску після завантаження на хості без графічного інтерфейсу

Швидкий початок

./scripts/podman/setup.sh --quadlet

./scripts/run-openclaw-podman.sh launch

./scripts/run-openclaw-podman.sh launch setup

export OPENCLAW_CONTAINER=openclaw

openclaw dashboard --no-openopenclaw gateway status --deep   # включає додаткове сканування службopenclaw doctoropenclaw channels login

Ручний засіб запуску читає з ~/.openclaw/.env лише невеликий дозволений список ключів, пов’язаних із Podman, і передає контейнеру явно визначені змінні середовища виконання; він не передає Podman увесь файл середовища.

Podman і Tailscale

Для доступу через HTTPS або віддалений браузер дотримуйтеся основної документації Tailscale.

Примітки щодо Podman:

• Залишайте адресу публікації Podman рівною 127.0.0.1.
• Віддавайте перевагу керованій хостом команді tailscale serve, а не openclaw gateway --tailscale serve.
• У macOS, якщо контекст автентифікації пристрою в локальному браузері працює ненадійно, використовуйте доступ через Tailscale замість тимчасових обхідних рішень із локальними тунелями.

Див. Tailscale і Control UI.

Systemd (Quadlet, необов’язково)

Якщо ви виконали ./scripts/podman/setup.sh --quadlet, налаштування встановлює файл Quadlet у ~/.config/containers/systemd/openclaw.container.

Після редагування файлу Quadlet:

systemctl --user daemon-reloadsystemctl --user restart openclaw.service

Щоб автозапуск зберігався після завантаження на хостах із доступом через SSH або без графічного інтерфейсу, увімкніть тривале виконання для поточного користувача:

sudo loginctl enable-linger "$(whoami)"

Згенерована служба Quadlet зберігає фіксовану, посилену за замовчуванням конфігурацію: порти, опубліковані на 127.0.0.1 (18789 для Gateway, 18790 для мосту), --bind lan усередині контейнера, простір імен користувача keep-id, OPENCLAW_NO_RESPAWN=1, Restart=on-failure і TimeoutStartSec=300. Вона читає ~/.openclaw/.env як EnvironmentFile середовища виконання для таких значень, як OPENCLAW_GATEWAY_TOKEN, але не використовує дозволений список перевизначень для Podman із ручного засобу запуску. Щоб налаштувати власні опубліковані порти, адресу публікації або інші параметри запуску контейнера, натомість використовуйте ручний засіб запуску або безпосередньо відредагуйте ~/.config/containers/systemd/openclaw.container, а потім перезавантажте конфігурацію та перезапустіть службу.

Конфігурація, середовище та сховище

• Каталог конфігурації: ~/.openclaw
• Каталог робочого простору: ~/.openclaw/workspace
• Файл токена: ~/.openclaw/.env
• Допоміжний засіб запуску: ./scripts/run-openclaw-podman.sh

Сценарій запуску та Quadlet монтують стан із хоста в контейнер: OPENCLAW_CONFIG_DIR -> /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace. За замовчуванням це каталоги хоста, а не анонімний стан контейнера, тому openclaw.json, файли auth-profiles.json окремих агентів, стан каналів і постачальників, сеанси та робочий простір зберігаються після заміни контейнера. Налаштування також додає початкові значення gateway.controlUi.allowedOrigins для 127.0.0.1 і localhost на опублікованому порту Gateway, щоб локальна панель керування працювала з прив’язкою контейнера не до local loopback.

Корисні змінні середовища для ручного засобу запуску (збережіть їх у ~/.openclaw/.env; засіб запуску читає цей файл перед остаточним визначенням значень за замовчуванням для контейнера й образу):

Якщо ви використовуєте нестандартне значення OPENCLAW_CONFIG_DIR або OPENCLAW_WORKSPACE_DIR, задавайте ті самі змінні як для ./scripts/podman/setup.sh, так і для подальших команд ./scripts/run-openclaw-podman.sh launch — засіб запуску з репозиторію не зберігає власні перевизначення шляхів між сеансами оболонки.

Оновлення образів

Після повторного збирання або завантаження нового образу перезапустіть контейнер чи службу Quadlet. Під час першого запуску нової версії OpenClaw Gateway виконує безпечне відновлення стану та плагінів, перш ніж повідомити про готовність.

Якщо Gateway завершує роботу замість переходу в стан готовності, один раз запустіть той самий образ із openclaw doctor --fix для того самого підключеного стану й конфігурації, а потім перезапустіть Gateway у звичайному режимі:

OPENCLAW_CONFIG_DIR="${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}"OPENCLAW_WORKSPACE_DIR="${OPENCLAW_WORKSPACE_DIR:-$OPENCLAW_CONFIG_DIR/workspace}"OPENCLAW_PODMAN_IMAGE="${OPENCLAW_PODMAN_IMAGE:-${OPENCLAW_IMAGE:-openclaw:local}}" podman run --rm -it \  --userns=keep-id \  --user "$(id -u):$(id -g)" \  -e HOME=/home/node \  -e NPM_CONFIG_CACHE=/home/node/.openclaw/.npm \  -v "$OPENCLAW_CONFIG_DIR:/home/node/.openclaw:rw" \  -v "$OPENCLAW_WORKSPACE_DIR:/home/node/.openclaw/workspace:rw" \  "$OPENCLAW_PODMAN_IMAGE" \  openclaw doctor --fix

На хостах із SELinux додайте ,Z до обох монтувань, якщо Podman блокує доступ до підключеного стану.

Корисні команди

• Журнали контейнера: podman logs -f openclaw
• Зупинити контейнер: podman stop openclaw
• Видалити контейнер: podman rm -f openclaw
• Відкрити URL панелі керування з CLI хоста: openclaw dashboard --no-open
• Перевірка працездатності та стану через CLI хоста: openclaw gateway status --deep (перевірка RPC + додаткове сканування служб)

Усунення несправностей

• Відмовлено в доступі (EACCES) до конфігурації або робочого простору: За замовчуванням контейнер працює з --userns=keep-id і --user <ваш uid>:<ваш gid>. Переконайтеся, що каталоги конфігурації та робочого простору на хості належать поточному користувачеві.
• Запуск Gateway заблоковано (відсутнє gateway.mode=local): Переконайтеся, що файл ~/.openclaw/openclaw.json існує та містить gateway.mode="local". scripts/podman/setup.sh створює його, якщо він відсутній.
• Контейнер перезапускається після оновлення образу: Виконайте одноразову команду openclaw doctor --fix із розділу Оновлення образів, а потім знову запустіть Gateway.
• Команди CLI контейнера спрямовуються не до тієї цілі: Явно використовуйте openclaw --container <name> ... або експортуйте OPENCLAW_CONTAINER=<name> у своїй оболонці.
• openclaw update завершується помилкою з --container: Це очікувана поведінка. Повторно зберіть або завантажте образ, а потім перезапустіть контейнер чи службу Quadlet.
• Служба Quadlet не запускається: Виконайте systemctl --user daemon-reload, а потім systemctl --user start openclaw.service. У системах без графічного інтерфейсу також може знадобитися sudo loginctl enable-linger "$(whoami)".
• SELinux блокує монтування: Не змінюйте стандартну поведінку монтування; коли SELinux працює в примусовому або дозвільному режимі, засіб запуску автоматично додає :Z у Linux.

Пов’язані матеріали

• Docker
• Фоновий процес Gateway
• Усунення несправностей Gateway