Podman

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

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

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

پیش‌نیازها

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

شروع سریع

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

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

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

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

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

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

متغیرهای محیطی اختیاری برای ساخت/راه‌اندازی:

• OPENCLAW_IMAGE یا OPENCLAW_PODMAN_IMAGE -- به‌جای ساختن openclaw:local، از یک ایمیج موجود/دریافت‌شده استفاده کنید
• OPENCLAW_IMAGE_APT_PACKAGES -- هنگام ساخت ایمیج، بسته‌های apt اضافی نصب کنید (همچنین OPENCLAW_DOCKER_APT_PACKAGES قدیمی را می‌پذیرد)
• OPENCLAW_IMAGE_PIP_PACKAGES -- هنگام ساخت ایمیج، بسته‌های Python اضافی نصب کنید؛ نسخه‌ها را pin کنید و فقط از package indexهایی استفاده کنید که به آن‌ها اعتماد دارید
• OPENCLAW_EXTENSIONS -- وابستگی‌های Plugin را هنگام ساخت از پیش نصب کنید
• OPENCLAW_INSTALL_BROWSER -- Chromium و Xvfb را برای خودکارسازی مرورگر از پیش نصب کنید (برای فعال‌سازی روی 1 تنظیم کنید)

شروع کانتینر:

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

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

راه‌اندازی اولیه:

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

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

احراز هویت مدل در Podman:

• هنگام راه‌اندازی، از احراز هویت مدیریت‌شده توسط OpenClaw استفاده کنید: کلیدهای API Anthropic برای Anthropic، یا احراز هویت OAuth مرورگر/کد دستگاه OpenAI Codex برای OpenAI پشتیبانی‌شده توسط Codex.
• راه‌انداز Podman خانه‌های اعتبارنامه CLI میزبان مانند ~/.claude یا ~/.codex را داخل کانتینر راه‌اندازی یا Gateway mount نمی‌کند.
• ورودهای CLI موجود روی میزبان مسیرهای سهولت استفاده روی همان میزبان هستند. برای نصب‌های کانتینری، احراز هویت ارائه‌دهنده را در وضعیت mount‌شده ~/.openclaw نگه دارید که راه‌اندازی آن را مدیریت می‌کند.

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

export OPENCLAW_CONTAINER=openclaw

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

openclaw dashboard --no-openopenclaw gateway status --deep   # includes extra service scanopenclaw doctoropenclaw channels login

در macOS، ماشین Podman ممکن است باعث شود مرورگر برای Gateway غیرمحلی به نظر برسد. اگر Control UI پس از راه‌اندازی خطاهای احراز هویت دستگاه گزارش کرد، از راهنمای Tailscale در Podman و Tailscale استفاده کنید.

Podman و Tailscale

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

نکته مخصوص Podman:

• میزبان publish در 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

دستورهای مفید:

• شروع: 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-reloadsystemctl --user restart openclaw.service

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

sudo loginctl enable-linger "$(whoami)"

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

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

اسکریپت اجرا و Quadlet وضعیت میزبان را داخل کانتینر bind-mount می‌کنند:

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

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

متغیرهای محیطی مفید برای راه‌انداز دستی:

• 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

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

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

نکته Quadlet:

• سرویس Quadlet تولیدشده عمداً یک شکل پیش‌فرض ثابت و سخت‌سازی‌شده را نگه می‌دارد: پورت‌های منتشرشده روی 127.0.0.1، --bind lan داخل کانتینر، و فضای نام کاربری 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) را منتشر می‌کند.
• ~/.openclaw/.env را به‌عنوان EnvironmentFile زمان اجرا برای مقادیری مانند OPENCLAW_GATEWAY_TOKEN می‌خواند، اما allowlist بازنویسی مخصوص Podman راه‌انداز دستی را مصرف نمی‌کند.
• اگر به پورت‌های publish سفارشی، میزبان publish سفارشی، یا flagهای دیگر اجرای کانتینر نیاز دارید، از راه‌انداز دستی استفاده کنید یا مستقیماً ~/.config/containers/systemd/openclaw.container را ویرایش کنید، سپس سرویس را reload و restart کنید.

دستورهای مفید

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

عیب‌یابی

• Permission denied (EACCES) روی پیکربندی یا workspace: کانتینر به‌صورت پیش‌فرض با --userns=keep-id و --user <your uid>:<your gid> اجرا می‌شود. مطمئن شوید مسیرهای پیکربندی/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 شکست می‌خورد: مورد انتظار است. ایمیج را دوباره بسازید/دریافت کنید، سپس کانتینر یا سرویس Quadlet را restart کنید.
• سرویس Quadlet شروع نمی‌شود: systemctl --user daemon-reload را اجرا کنید، سپس systemctl --user start openclaw.service. روی سیستم‌های بدون نمایشگر، ممکن است به sudo loginctl enable-linger "$(whoami)" هم نیاز داشته باشید.
• SELinux جلوی bind mountها را می‌گیرد: رفتار mount پیش‌فرض را دست‌نخورده بگذارید؛ راه‌انداز وقتی SELinux در حالت enforcing یا permissive باشد، روی Linux به‌صورت خودکار :Z را اضافه می‌کند.

مرتبط

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