Podman

OpenClaw Gateway را در یک کانتینر Podman بدون root اجرا کنید که توسط کاربر غیر root فعلی شما مدیریت می‌شود.

مدل موردنظر این است:

• Podman کانتینر Gateway را اجرا می‌کند.
• CLI میزبان openclaw شما سطح کنترل است.
• وضعیت پایدار به‌صورت پیش‌فرض روی میزبان در ~/.openclaw قرار دارد.
• مدیریت روزمره از openclaw --container <name> ... به‌جای sudo -u openclaw، podman exec، یا یک کاربر سرویس جداگانه استفاده می‌کند.

# پیش‌نیازها

• Podman در حالت بدون root
• OpenClaw CLI نصب‌شده روی میزبان
• اختیاری: systemd --user اگر راه‌اندازی خودکار مدیریت‌شده با Quadlet می‌خواهید
• اختیاری: sudo فقط اگر برای پایداری پس از بوت روی یک میزبان بدون نمایشگر، loginctl enable-linger "$(whoami)" را می‌خواهید

# شروع سریع

جزئیات راه‌اندازی:

• ./scripts/podman/setup.sh به‌صورت پیش‌فرض openclaw:local را در store بدون root Podman شما می‌سازد، یا اگر OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE را تنظیم کرده باشید از آن استفاده می‌کند.
• اگر ~/.openclaw/openclaw.json وجود نداشته باشد، آن را با gateway.mode: "local" ایجاد می‌کند.
• اگر ~/.openclaw/.env وجود نداشته باشد، آن را با OPENCLAW_GATEWAY_TOKEN ایجاد می‌کند.
• برای اجراهای دستی، helper فقط یک allowlist کوچک از کلیدهای مرتبط با Podman را از ~/.openclaw/.env می‌خواند و env varهای runtime صریح را به کانتینر پاس می‌دهد؛ فایل env کامل را به Podman نمی‌دهد.

راه‌اندازی مدیریت‌شده با Quadlet:

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

Quadlet گزینه‌ای فقط برای Linux است، چون به سرویس‌های کاربری systemd وابسته است.

همچنین می‌توانید OPENCLAW_PODMAN_QUADLET=1 را تنظیم کنید.

env varهای اختیاری build/setup:

• OPENCLAW_IMAGE یا OPENCLAW_PODMAN_IMAGE -- به‌جای ساختن openclaw:local از یک image موجود/دریافت‌شده استفاده کنید
• OPENCLAW_DOCKER_APT_PACKAGES -- هنگام ساخت image، بسته‌های apt اضافی نصب کنید
• OPENCLAW_EXTENSIONS -- وابستگی‌های plugin را هنگام build از پیش نصب کنید
• OPENCLAW_INSTALL_BROWSER -- Chromium و Xvfb را برای اتوماسیون مرورگر از پیش نصب کنید (برای فعال‌سازی روی 1 تنظیم کنید)

راه‌اندازی کانتینر:

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

این script کانتینر را با uid/gid فعلی شما و --userns=keep-id شروع می‌کند و وضعیت OpenClaw شما را در کانتینر bind-mount می‌کند.

Onboarding:

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

سپس http://127.0.0.1:18789/ را باز کنید و از token موجود در ~/.openclaw/.env استفاده کنید.

پیش‌فرض CLI میزبان:

export OPENCLAW_CONTAINER=openclaw

سپس فرمان‌هایی مانند این‌ها به‌صورت خودکار داخل آن کانتینر اجرا می‌شوند:

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

در macOS، Podman machine ممکن است باعث شود مرورگر برای Gateway غیرمحلی به نظر برسد. اگر رابط کاربری کنترل پس از launch خطاهای device-auth گزارش کرد، از راهنمای Tailscale در Podman و Tailscale استفاده کنید.

# Podman و Tailscale

برای HTTPS یا دسترسی مرورگر راه دور، از مستندات اصلی Tailscale پیروی کنید.

نکته مخصوص Podman:

• میزبان publish مربوط به Podman را روی 127.0.0.1 نگه دارید.
• tailscale serve مدیریت‌شده توسط میزبان را به openclaw gateway --tailscale serve ترجیح دهید.
• در macOS، اگر context احراز هویت دستگاه مرورگر محلی قابل اتکا نیست، به‌جای راهکارهای موقت tunnel محلی، از دسترسی Tailscale استفاده کنید.

ببینید:

• Tailscale
• رابط کاربری کنترل

# Systemd (Quadlet، اختیاری)

اگر ./scripts/podman/setup.sh --quadlet را اجرا کرده باشید، setup یک فایل 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

پس از ویرایش فایل Quadlet:

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

برای پایداری پس از بوت روی میزبان‌های SSH/بدون نمایشگر، lingering را برای کاربر فعلی خود فعال کنید:

sudo loginctl enable-linger "$(whoami)"

# پیکربندی، env، و ذخیره‌سازی

• دایرکتوری پیکربندی: ~/.openclaw
• دایرکتوری workspace: ~/.openclaw/workspace
• فایل token: ~/.openclaw/.env
• helper راه‌اندازی: ./scripts/run-openclaw-podman.sh

script راه‌اندازی و Quadlet وضعیت میزبان را در کانتینر bind-mount می‌کنند:

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

به‌صورت پیش‌فرض این‌ها دایرکتوری‌های میزبان هستند، نه وضعیت ناشناس کانتینر، بنابراین openclaw.json، فایل‌های auth-profiles.json به‌ازای هر agent، وضعیت channel/provider، sessionها، و workspace پس از جایگزینی کانتینر باقی می‌مانند. setup مربوط به Podman همچنین gateway.controlUi.allowedOrigins را برای 127.0.0.1 و localhost روی پورت منتشرشده Gateway مقداردهی اولیه می‌کند تا dashboard محلی با bind غیر loopback کانتینر کار کند.

env varهای مفید برای launcher دستی:

• OPENCLAW_PODMAN_CONTAINER -- نام کانتینر (به‌صورت پیش‌فرض openclaw)
• OPENCLAW_PODMAN_IMAGE / OPENCLAW_IMAGE -- image برای اجرا
• OPENCLAW_PODMAN_GATEWAY_HOST_PORT -- پورت میزبان که به 18789 کانتینر map می‌شود
• OPENCLAW_PODMAN_BRIDGE_HOST_PORT -- پورت میزبان که به 18790 کانتینر map می‌شود
• OPENCLAW_PODMAN_PUBLISH_HOST -- interface میزبان برای پورت‌های منتشرشده؛ پیش‌فرض 127.0.0.1 است
• OPENCLAW_GATEWAY_BIND -- حالت bind Gateway داخل کانتینر؛ پیش‌فرض lan است
• OPENCLAW_PODMAN_USERNS -- keep-id (پیش‌فرض)، auto، یا host

launcher دستی پیش از نهایی‌کردن پیش‌فرض‌های کانتینر/image، ~/.openclaw/.env را می‌خواند، بنابراین می‌توانید این‌ها را آنجا پایدار کنید.

اگر از OPENCLAW_CONFIG_DIR یا OPENCLAW_WORKSPACE_DIR غیرپیش‌فرض استفاده می‌کنید، همان متغیرها را هم برای ./scripts/podman/setup.sh و هم برای فرمان‌های بعدی ./scripts/run-openclaw-podman.sh launch تنظیم کنید. launcher محلی repo، overrideهای مسیر سفارشی را بین shellها پایدار نمی‌کند.

نکته Quadlet:

• سرویس Quadlet تولیدشده عمداً یک شکل پیش‌فرض ثابت و سخت‌گیرانه را حفظ می‌کند: پورت‌های منتشرشده روی 127.0.0.1، --bind lan داخل کانتینر، و namespace کاربری keep-id.
• OPENCLAW_NO_RESPAWN=1، Restart=on-failure، و TimeoutStartSec=300 را pin می‌کند.
• هر دو 127.0.0.1:18789:18789 (Gateway) و 127.0.0.1:18790:18790 (bridge) را publish می‌کند.
• ~/.openclaw/.env را به‌عنوان EnvironmentFile زمان اجرا برای مقدارهایی مانند OPENCLAW_GATEWAY_TOKEN می‌خواند، اما allowlist override مخصوص Podman در launcher دستی را مصرف نمی‌کند.
• اگر به پورت‌های publish سفارشی، میزبان publish، یا flagهای دیگر اجرای کانتینر نیاز دارید، از launcher دستی استفاده کنید یا ~/.config/containers/systemd/openclaw.container را مستقیماً ویرایش کنید، سپس service را reload و restart کنید.

# فرمان‌های مفید

• لاگ‌های کانتینر: podman logs -f openclaw
• توقف کانتینر: podman stop openclaw
• حذف کانتینر: podman rm -f openclaw
• باز کردن URL داشبورد از CLI میزبان: openclaw dashboard --no-open
• سلامت/وضعیت از طریق CLI میزبان: openclaw gateway status --deep (کاوش RPC + اسکن service اضافی)

# عیب‌یابی

• Permission denied (EACCES) روی config یا workspace: کانتینر به‌صورت پیش‌فرض با --userns=keep-id و --user <your uid>:<your gid> اجرا می‌شود. مطمئن شوید مسیرهای config/workspace میزبان تحت مالکیت کاربر فعلی شما هستند.
• شروع Gateway مسدود شده است (gateway.mode=local موجود نیست): مطمئن شوید ~/.openclaw/openclaw.json وجود دارد و gateway.mode="local" را تنظیم می‌کند. scripts/podman/setup.sh اگر این مورد موجود نباشد، آن را ایجاد می‌کند.
• فرمان‌های CLI کانتینر به مقصد اشتباه می‌خورند: به‌صورت صریح از openclaw --container <name> ... استفاده کنید، یا OPENCLAW_CONTAINER=<name> را در shell خود export کنید.
• openclaw update با --container شکست می‌خورد: مورد انتظار است. image را دوباره build/pull کنید، سپس کانتینر یا سرویس Quadlet را restart کنید.
• سرویس Quadlet شروع نمی‌شود: systemctl --user daemon-reload را اجرا کنید، سپس systemctl --user start openclaw.service. روی سیستم‌های بدون نمایشگر شاید به sudo loginctl enable-linger "$(whoami)" هم نیاز داشته باشید.
• SELinux مانع bind mountها می‌شود: رفتار mount پیش‌فرض را دست‌نخورده بگذارید؛ launcher هنگام enforcing یا permissive بودن SELinux روی Linux، :Z را خودکار اضافه می‌کند.

# مرتبط

• Docker
• فرآیند پس‌زمینه Gateway
• عیب‌یابی Gateway