diff --git a/docs/uk/install/podman.md b/docs/uk/install/podman.md index 9cf771b16..a4a202fa9 100644 --- a/docs/uk/install/podman.md +++ b/docs/uk/install/podman.md @@ -1,75 +1,76 @@ --- read_when: - - Ви хочете контейнеризований gateway з Podman замість Docker -summary: Запустити OpenClaw у rootless-контейнері Podman + - Ви хочете контейнеризований Gateway із Podman замість Docker +summary: Запустіть OpenClaw у контейнері Podman без root-прав title: Podman x-i18n: - generated_at: "2026-04-23T20:57:45Z" - model: gpt-5.4 + generated_at: "2026-04-28T20:52:39Z" + model: gpt-5.5 provider: openai - source_hash: 559ac707e0a3ef173d0300ee2f8c6f4ed664ff5afbf1e3f1848312a9d441e9e4 + source_hash: bfdcbbdb62c2f8ca2d6d370b742003e6f92f6921a38c00ba19e810d83e350647 source_path: install/podman.md - workflow: 15 + workflow: 16 --- -Запустіть Gateway OpenClaw у rootless-контейнері Podman, яким керує ваш поточний користувач без root. +Запускайте OpenClaw Gateway у rootless-контейнері Podman, яким керує ваш поточний користувач без прав root. -Запланована модель така: +Передбачена модель така: -- Podman запускає контейнер gateway. -- Ваш хостовий CLI `openclaw` є control plane. -- Постійний стан типово зберігається на хості в `~/.openclaw`. -- Щоденне керування виконується через `openclaw --container ...` замість `sudo -u openclaw`, `podman exec` або окремого користувача служби. +- Podman запускає контейнер Gateway. +- Ваш хостовий CLI `openclaw` є площиною керування. +- Сталий стан за замовчуванням зберігається на хості в `~/.openclaw`. +- Повсякденне керування використовує `openclaw --container ...` замість `sudo -u openclaw`, `podman exec` або окремого службового користувача. ## Передумови -- **Podman** у rootless-режимі -- **OpenClaw CLI** встановлений на хості -- **Необов’язково:** `systemd --user`, якщо ви хочете автозапуск із керуванням через Quadlet -- **Необов’язково:** `sudo`, лише якщо ви хочете `loginctl enable-linger "$(whoami)"` для збереження після перезавантаження на headless-хості +- **Podman** у режимі rootless +- **CLI OpenClaw**, встановлений на хості +- **Необов’язково:** `systemd --user`, якщо потрібен автозапуск під керуванням Quadlet +- **Необов’язково:** `sudo` лише якщо потрібно `loginctl enable-linger "$(whoami)"` для збереження запуску після завантаження на headless-хості ## Швидкий старт - З кореня repo запустіть `./scripts/podman/setup.sh`. + З кореня репозиторію виконайте `./scripts/podman/setup.sh`. - - Запустіть контейнер через `./scripts/run-openclaw-podman.sh launch`. + + Запустіть контейнер командою `./scripts/run-openclaw-podman.sh launch`. - + Виконайте `./scripts/run-openclaw-podman.sh launch setup`, потім відкрийте `http://127.0.0.1:18789/`. - - Установіть `OPENCLAW_CONTAINER=openclaw`, а потім використовуйте звичайні команди `openclaw` з хоста. + + Установіть `OPENCLAW_CONTAINER=openclaw`, потім використовуйте звичайні команди `openclaw` з хоста. Деталі налаштування: -- `./scripts/podman/setup.sh` типово збирає `openclaw:local` у вашому rootless-сховищі Podman або використовує `OPENCLAW_IMAGE` / `OPENCLAW_PODMAN_IMAGE`, якщо ви їх задали. -- Він створює `~/.openclaw/openclaw.json` з `gateway.mode: "local"`, якщо файл відсутній. +- `./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 vars runtime до контейнера; він не передає Podman увесь env-файл. +- Для ручних запусків допоміжний скрипт читає з `~/.openclaw/.env` лише невеликий allowlist ключів, пов’язаних із Podman, і передає контейнеру явні змінні середовища виконання; він не передає Podman увесь env-файл. -Налаштування з керуванням через Quadlet: +Налаштування під керуванням Quadlet: ```bash ./scripts/podman/setup.sh --quadlet ``` -Quadlet — це лише Linux-варіант, оскільки він залежить від служб користувача systemd. +Quadlet є опцією лише для Linux, оскільки залежить від користувацьких служб systemd. -Ви також можете задати `OPENCLAW_PODMAN_QUADLET=1`. +Також можна задати `OPENCLAW_PODMAN_QUADLET=1`. -Необов’язкові env vars для build/setup: +Необов’язкові змінні середовища для збірки/налаштування: -- `OPENCLAW_IMAGE` або `OPENCLAW_PODMAN_IMAGE` -- використовувати наявний/завантажений образ замість збирання `openclaw:local` -- `OPENCLAW_DOCKER_APT_PACKAGES` -- встановити додаткові apt-пакети під час збирання образу -- `OPENCLAW_EXTENSIONS` -- попередньо встановити залежності Plugin під час build +- `OPENCLAW_IMAGE` або `OPENCLAW_PODMAN_IMAGE` -- використати наявний/завантажений образ замість збирання `openclaw:local` +- `OPENCLAW_DOCKER_APT_PACKAGES` -- установити додаткові apt-пакети під час збірки образу +- `OPENCLAW_EXTENSIONS` -- попередньо встановити залежності плагінів під час збірки +- `OPENCLAW_INSTALL_BROWSER` -- попередньо встановити Chromium і Xvfb для автоматизації браузера (задайте `1`, щоб увімкнути) Запуск контейнера: @@ -77,23 +78,23 @@ Quadlet — це лише Linux-варіант, оскільки він зале ./scripts/run-openclaw-podman.sh launch ``` -Скрипт запускає контейнер від вашого поточного uid/gid з `--userns=keep-id` і bind-mount-ить ваш стан OpenClaw у контейнер. +Скрипт запускає контейнер із вашими поточними uid/gid, використовуючи `--userns=keep-id`, і bind-монтує ваш стан OpenClaw у контейнер. -Онбординг: +Onboarding: ```bash ./scripts/run-openclaw-podman.sh launch setup ``` -Потім відкрийте `http://127.0.0.1:18789/` і використайте токен з `~/.openclaw/.env`. +Потім відкрийте `http://127.0.0.1:18789/` і використайте токен із `~/.openclaw/.env`. -Типове значення для хостового CLI: +Типовий хостовий CLI: ```bash export OPENCLAW_CONTAINER=openclaw ``` -Тоді такі команди автоматично виконуватимуться всередині цього контейнера: +Після цього такі команди автоматично виконуватимуться всередині цього контейнера: ```bash openclaw dashboard --no-open @@ -102,8 +103,8 @@ openclaw doctor openclaw channels login ``` -На macOS Podman machine може зробити браузер для gateway нелокальним. -Якщо після запуску Control UI повідомляє про помилки device-auth, скористайтеся вказівками Tailscale в +На macOS машина Podman може зробити браузер для Gateway таким, що виглядає не локальним. +Якщо Control UI після запуску повідомляє про помилки автентифікації пристрою, скористайтеся вказівками щодо Tailscale у [Podman + Tailscale](#podman--tailscale). @@ -114,11 +115,11 @@ openclaw channels login Примітка, специфічна для Podman: -- Залишайте Podman publish host на `127.0.0.1`. -- Надавайте перевагу `tailscale serve`, яким керує хост, замість `openclaw gateway --tailscale serve`. -- На macOS, якщо контекст device-auth локального браузера ненадійний, використовуйте доступ через Tailscale замість тимчасових локальних обхідних тунелів. +- Залишайте хост публікації Podman на `127.0.0.1`. +- Надавайте перевагу керованому хостом `tailscale serve` замість `openclaw gateway --tailscale serve`. +- На macOS, якщо локальний браузерний контекст автентифікації пристрою ненадійний, використовуйте доступ через Tailscale замість спеціальних обхідних рішень із локальними тунелями. -Див.: +Дивіться: - [Tailscale](/uk/gateway/tailscale) - [Control UI](/uk/web/control-ui) @@ -133,83 +134,83 @@ openclaw channels login Корисні команди: -- **Запустити:** `systemctl --user start openclaw.service` -- **Зупинити:** `systemctl --user stop openclaw.service` +- **Запуск:** `systemctl --user start openclaw.service` +- **Зупинка:** `systemctl --user stop openclaw.service` - **Стан:** `systemctl --user status openclaw.service` -- **Логи:** `journalctl --user -u openclaw.service -f` +- **Журнали:** `journalctl --user -u openclaw.service -f` -Після редагування файла Quadlet: +Після редагування файлу Quadlet: ```bash systemctl --user daemon-reload systemctl --user restart openclaw.service ``` -Для збереження після перезавантаження на SSH/headless-хостах увімкніть lingering для поточного користувача: +Для збереження запуску після завантаження на SSH/headless-хостах увімкніть lingering для поточного користувача: ```bash sudo loginctl enable-linger "$(whoami)" ``` -## Конфігурація, env і сховище +## Конфігурація, середовище та сховище - **Каталог конфігурації:** `~/.openclaw` - **Каталог робочого простору:** `~/.openclaw/workspace` - **Файл токена:** `~/.openclaw/.env` - **Допоміжний скрипт запуску:** `./scripts/run-openclaw-podman.sh` -Скрипт запуску й Quadlet bind-mount-ять стан хоста в контейнер: +Скрипт запуску та Quadlet bind-монтують хостовий стан у контейнер: - `OPENCLAW_CONFIG_DIR` -> `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR` -> `/home/node/.openclaw/workspace` -Типово це каталоги хоста, а не анонімний стан контейнера, тому -`openclaw.json`, `auth-profiles.json` для кожного агента, стан каналів/провайдерів, -сесії та робочий простір переживають заміну контейнера. -Налаштування Podman також ініціалізує `gateway.controlUi.allowedOrigins` для `127.0.0.1` і `localhost` на опублікованому порту gateway, щоб локальна панель працювала з не-loopback-прив’язкою контейнера. +За замовчуванням це хостові каталоги, а не анонімний стан контейнера, тому +`openclaw.json`, агентні `auth-profiles.json`, стан каналів/провайдерів, +сесії та робочий простір зберігаються після заміни контейнера. +Налаштування Podman також засіває `gateway.controlUi.allowedOrigins` для `127.0.0.1` і `localhost` на опублікованому порту Gateway, щоб локальна dashboard працювала з не-loopback bind контейнера. -Корисні env vars для ручного launcher: +Корисні змінні середовища для ручного launcher: -- `OPENCLAW_PODMAN_CONTAINER` -- ім’я контейнера (типово `openclaw`) +- `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` -- режим прив’язки gateway усередині контейнера; типово `lan` -- `OPENCLAW_PODMAN_USERNS` -- `keep-id` (типово), `auto` або `host` +- `OPENCLAW_PODMAN_PUBLISH_HOST` -- хостовий інтерфейс для опублікованих портів; за замовчуванням `127.0.0.1` +- `OPENCLAW_GATEWAY_BIND` -- режим bind Gateway усередині контейнера; за замовчуванням `lan` +- `OPENCLAW_PODMAN_USERNS` -- `keep-id` (за замовчуванням), `auto` або `host` -Ручний launcher читає `~/.openclaw/.env` перед остаточним визначенням типових значень контейнера/образу, тож ви можете зберігати їх там. +Ручний launcher читає `~/.openclaw/.env` перед остаточним визначенням стандартних значень контейнера/образу, тож ви можете зберегти їх там. -Якщо ви використовуєте нетиповий `OPENCLAW_CONFIG_DIR` або `OPENCLAW_WORKSPACE_DIR`, задайте ті самі змінні і для `./scripts/podman/setup.sh`, і для подальших команд `./scripts/run-openclaw-podman.sh launch`. Launcher з локального repo не зберігає перевизначення користувацьких шляхів між оболонками. +Якщо ви використовуєте нетиповий `OPENCLAW_CONFIG_DIR` або `OPENCLAW_WORKSPACE_DIR`, задайте ті самі змінні як для `./scripts/podman/setup.sh`, так і для подальших команд `./scripts/run-openclaw-podman.sh launch`. Репозиторний launcher не зберігає власні перевизначення шляхів між shell-сеансами. Примітка щодо Quadlet: -- Згенерована служба 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` (bridge). -- Вона читає `~/.openclaw/.env` як runtime `EnvironmentFile` для значень на кшталт `OPENCLAW_GATEWAY_TOKEN`, але не використовує allowlist Podman-специфічних перевизначень із ручного launcher. -- Якщо вам потрібні власні publish ports, publish host або інші прапорці запуску контейнера, використовуйте ручний launcher або безпосередньо відредагуйте `~/.config/containers/systemd/openclaw.container`, а потім перезавантажте й перезапустіть службу. +- Згенерована служба 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` (bridge). +- Вона читає `~/.openclaw/.env` як runtime `EnvironmentFile` для значень на кшталт `OPENCLAW_GATEWAY_TOKEN`, але не використовує allowlist Podman-специфічних перевизначень ручного launcher. +- Якщо вам потрібні власні порти публікації, хост публікації або інші прапорці запуску контейнера, використовуйте ручний launcher або редагуйте `~/.config/containers/systemd/openclaw.container` напряму, потім перезавантажте й перезапустіть службу. ## Корисні команди -- **Логи контейнера:** `podman logs -f openclaw` +- **Журнали контейнера:** `podman logs -f openclaw` - **Зупинити контейнер:** `podman stop openclaw` - **Видалити контейнер:** `podman rm -f openclaw` -- **Відкрити URL панелі з хостового CLI:** `openclaw dashboard --no-open` +- **Відкрити URL dashboard із хостового CLI:** `openclaw dashboard --no-open` - **Health/status через хостовий CLI:** `openclaw gateway status --deep` (RPC probe + додаткове - сканування служб) + сканування служби) -## Усунення проблем +## Усунення несправностей -- **Permission denied (EACCES) для конфігурації або робочого простору:** Контейнер типово запускається з `--userns=keep-id` і `--user :`. Переконайтеся, що шляхи конфігурації/робочого простору на хості належать вашому поточному користувачу. -- **Запуск Gateway заблоковано (немає `gateway.mode=local`):** Переконайтеся, що `~/.openclaw/openclaw.json` існує і має `gateway.mode="local"`. `scripts/podman/setup.sh` створює це, якщо файл відсутній. -- **Команди CLI контейнера звертаються не до тієї цілі:** Явно використовуйте `openclaw --container ...` або експортуйте `OPENCLAW_CONTAINER=` у вашій оболонці. -- **`openclaw update` не працює з `--container`:** Це очікувано. Перезберіть/перезавантажте образ, а потім перезапустіть контейнер або службу Quadlet. -- **Служба Quadlet не запускається:** Виконайте `systemctl --user daemon-reload`, потім `systemctl --user start openclaw.service`. На headless-системах вам також може знадобитися `sudo loginctl enable-linger "$(whoami)"`. -- **SELinux блокує bind mounts:** Не змінюйте типову поведінку монтування; launcher автоматично додає `:Z` у Linux, коли SELinux працює в режимі enforcing або permissive. +- **Permission denied (EACCES) для конфігурації або робочого простору:** Контейнер за замовчуванням запускається з `--userns=keep-id` і `--user :`. Переконайтеся, що хостові шляхи конфігурації/робочого простору належать вашому поточному користувачу. +- **Запуск Gateway заблоковано (відсутній `gateway.mode=local`):** Переконайтеся, що `~/.openclaw/openclaw.json` існує та задає `gateway.mode="local"`. `scripts/podman/setup.sh` створює це, якщо відсутнє. +- **Команди CLI контейнера потрапляють не в ту ціль:** Використовуйте `openclaw --container ...` явно або експортуйте `OPENCLAW_CONTAINER=` у вашій 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](/uk/install/docker) -- [Gateway background process](/uk/gateway/background-process) -- [Gateway troubleshooting](/uk/gateway/troubleshooting) +- [Фоновий процес Gateway](/uk/gateway/background-process) +- [Усунення несправностей Gateway](/uk/gateway/troubleshooting)