Podman

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​

Передумови

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

​

Швидкий старт

• ./scripts/podman/setup.sh за замовчуванням збирає openclaw:local у вашому rootless-сховищі Podman або використовує OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE, якщо ви задали одне з них.
• Він створює ~/.openclaw/openclaw.json із gateway.mode: "local", якщо файл відсутній.
• Він створює ~/.openclaw/.env із OPENCLAW_GATEWAY_TOKEN, якщо файл відсутній.
• Для ручних запусків допоміжний скрипт читає лише невеликий allowlist пов’язаних із Podman ключів із ~/.openclaw/.env і передає явні змінні середовища виконання до контейнера; він не передає повний env-файл до Podman.

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

• OPENCLAW_IMAGE або OPENCLAW_PODMAN_IMAGE — використати наявний/завантажений образ замість збирання openclaw:local
• OPENCLAW_DOCKER_APT_PACKAGES — установити додаткові apt-пакети під час збирання образу
• OPENCLAW_EXTENSIONS — попередньо встановити залежності Plugin під час збирання
• OPENCLAW_INSTALL_BROWSER — попередньо встановити Chromium і Xvfb для браузерної автоматизації (установіть 1, щоб увімкнути)

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

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

export OPENCLAW_CONTAINER=openclaw

openclaw dashboard --no-open
openclaw gateway status --deep   # includes extra service scan
openclaw doctor
openclaw channels login

​

Podman і Tailscale

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

• Tailscale
• Інтерфейс керування

​

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

~/.config/containers/systemd/openclaw.container

• Запустити: systemctl --user start openclaw.service
• Зупинити: systemctl --user stop openclaw.service
• Стан: systemctl --user status openclaw.service
• Журнали: journalctl --user -u openclaw.service -f

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

sudo loginctl enable-linger "$(whoami)"

​

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

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

• OPENCLAW_CONFIG_DIR -> /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace

• OPENCLAW_PODMAN_CONTAINER — назва контейнера (openclaw за замовчуванням)
• OPENCLAW_PODMAN_IMAGE / OPENCLAW_IMAGE — образ для запуску
• OPENCLAW_PODMAN_GATEWAY_HOST_PORT — порт хоста, зіставлений із контейнерним 18789
• OPENCLAW_PODMAN_BRIDGE_HOST_PORT — порт хоста, зіставлений із контейнерним 18790
• OPENCLAW_PODMAN_PUBLISH_HOST — інтерфейс хоста для опублікованих портів; за замовчуванням 127.0.0.1
• OPENCLAW_GATEWAY_BIND — режим bind Gateway усередині контейнера; за замовчуванням lan
• OPENCLAW_PODMAN_USERNS — keep-id (за замовчуванням), auto або host

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

​

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

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

​

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

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

​

Пов’язане

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