Containers
Podman
Gateway در OpenClaw را در یک کانتینر Podman بدون دسترسی root اجرا کنید که توسط کاربر فعلی و غیر root شما مدیریت میشود.
مدل کار:
- Podman کانتینر Gateway را اجرا میکند.
- CLI میزبان شما، یعنی
openclaw، صفحه کنترل است. - حالت پایدار بهطور پیشفرض در میزبان و زیر
~/.openclawنگهداری میشود. - برای مدیریت روزمره، بهجای
sudo -u openclaw،podman execیا یک کاربر سرویس جداگانه، ازopenclaw --container <name> ...استفاده میشود.
پیشنیازها
- Podman در حالت بدون root
- نصب بودن CLI در OpenClaw روی میزبان
- اختیاری: اگر میخواهید راهاندازی خودکار توسط Quadlet مدیریت شود،
systemd --user - اختیاری: فقط اگر میخواهید روی یک میزبان بدون نمایشگر، ماندگاری پس از راهاندازی سیستم را با
loginctl enable-linger "$(whoami)"فعال کنید،sudo
شروع سریع
راهاندازی یکباره
از ریشه مخزن، ./scripts/podman/setup.sh را اجرا کنید.
این کار openclaw:local را در فضای ذخیرهسازی Podman بدون root شما میسازد (یا در صورت تنظیم بودن، OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE را دریافت میکند)، در صورت نبودن ~/.openclaw/openclaw.json آن را همراه با gateway.mode: "local" ایجاد میکند و در صورت نبودن ~/.openclaw/.env آن را همراه با یک OPENCLAW_GATEWAY_TOKEN تولیدشده ایجاد میکند.
متغیرهای محیطی اختیاری زمان ساخت:
| متغیر | اثر |
|---|---|
OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE |
بهجای ساخت openclaw:local، از یک ایمیج موجود یا دریافتشده استفاده میکند |
OPENCLAW_IMAGE_APT_PACKAGES |
هنگام ساخت ایمیج، بستههای apt اضافی را نصب میکند (همچنین OPENCLAW_DOCKER_APT_PACKAGES قدیمی را میپذیرد) |
OPENCLAW_IMAGE_PIP_PACKAGES |
هنگام ساخت ایمیج، بستههای Python اضافی را نصب میکند؛ نسخهها را ثابت کنید و فقط از ایندکسهای بستهای استفاده کنید که به آنها اعتماد دارید |
OPENCLAW_EXTENSIONS |
Pluginهای انتخابشده و پشتیبانیشده را کامپایل/بستهبندی میکند و وابستگیهای زمان اجرای آنها را نصب میکند |
OPENCLAW_INSTALL_BROWSER |
Chromium و Xvfb را برای خودکارسازی مرورگر از پیش نصب میکند (روی 1 تنظیم کنید) |
برای راهاندازی تحت مدیریت Quadlet بهجای آن (فقط Linux و سرویسهای کاربری systemd):
./scripts/podman/setup.sh --quadletیا OPENCLAW_PODMAN_QUADLET=1 را تنظیم کنید.
راهاندازی کانتینر Gateway
./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 استفاده کنید.
احراز هویت مدل: هنگام راهاندازی از احراز هویت مدیریتشده توسط OpenClaw استفاده کنید (کلیدهای API مربوط به Anthropic، یا احراز هویت OAuth مرورگر/کد دستگاه OpenAI Codex برای OpenAI مبتنی بر Codex). راهانداز Podman، محل نگهداری اعتبارنامههای CLI میزبان مانند ~/.claude یا ~/.codex را داخل کانتینر راهاندازی یا Gateway متصل نمیکند. ورودهای موجود CLI میزبان فقط مسیرهای تسهیلکننده روی همان میزبان هستند -- برای نصبهای کانتینری، احراز هویت ارائهدهنده را در حالت متصلشده ~/.openclaw نگه دارید که فرایند راهاندازی آن را مدیریت میکند.
مدیریت کانتینر در حال اجرا از CLI میزبان
export OPENCLAW_CONTAINER=openclawسپس فرمانهای عادی openclaw بهطور خودکار داخل همان کانتینر اجرا میشوند:
openclaw dashboard --no-openopenclaw gateway status --deep # شامل اسکن سرویس اضافی استopenclaw doctoropenclaw channels loginدر macOS، ماشین Podman ممکن است باعث شود مرورگر از دید Gateway غیرمحلی به نظر برسد. اگر Control UI پس از راهاندازی خطاهای احراز هویت دستگاه را گزارش کرد، از راهنمای Tailscale در Podman و Tailscale استفاده کنید.
راهانداز دستی فقط فهرست مجاز کوچکی از کلیدهای مرتبط با Podman را از ~/.openclaw/.env میخواند و متغیرهای محیطی زمان اجرا را بهصورت صریح به کانتینر میفرستد؛ این راهانداز کل فایل محیطی را در اختیار 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 نصب میکند.
| عملیات | فرمان |
|---|---|
| شروع | 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)"سرویس Quadlet تولیدشده یک ساختار پیشفرض ثابت و سختسازیشده را حفظ میکند: پورتهای منتشرشده 127.0.0.1 (Gateway در 18789، پل در 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، حالت میزبان را با bind mount داخل کانتینر متصل میکنند: 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 مقداردهی اولیه میکند تا داشبورد محلی با اتصال غیر loopback کانتینر کار کند.
متغیرهای محیطی مفید برای راهانداز دستی (این موارد را در ~/.openclaw/.env ماندگار کنید؛ راهانداز پیش از نهاییسازی پیشفرضهای کانتینر/ایمیج، آن فایل را میخواند):
| متغیر | پیشفرض | اثر |
|---|---|---|
OPENCLAW_PODMAN_CONTAINER |
openclaw |
نام کانتینر |
OPENCLAW_PODMAN_IMAGE / OPENCLAW_IMAGE |
openclaw:local |
ایمیج مورد استفاده برای اجرا |
OPENCLAW_PODMAN_GATEWAY_HOST_PORT |
18789 |
پورت میزبان نگاشتشده به 18789 کانتینر |
OPENCLAW_PODMAN_BRIDGE_HOST_PORT |
18790 |
پورت میزبان نگاشتشده به 18790 کانتینر |
OPENCLAW_PODMAN_PUBLISH_HOST |
127.0.0.1 |
رابط میزبان برای پورتهای منتشرشده |
OPENCLAW_GATEWAY_BIND |
lan |
حالت اتصال Gateway داخل کانتینر |
OPENCLAW_PODMAN_USERNS |
keep-id |
keep-id، auto یا host |
اگر از OPENCLAW_CONFIG_DIR یا OPENCLAW_WORKSPACE_DIR غیرپیشفرض استفاده میکنید، همان متغیرها را هم برای ./scripts/podman/setup.sh و هم برای فرمانهای بعدی ./scripts/run-openclaw-podman.sh launch تنظیم کنید -- راهانداز محلی مخزن، بازنویسی مسیرهای سفارشی را بین پوستهها ماندگار نمیکند.
ارتقای ایمیجها
پس از ساخت دوباره یا دریافت یک ایمیج جدید، کانتینر یا سرویس Quadlet را دوباره راهاندازی کنید. در نخستین راهاندازی یک نسخه جدید OpenClaw، Gateway پیش از اعلام آمادگی، تعمیرات ایمن حالت و Plugin را اجرا میکند.
اگر 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، اگر Podman دسترسی به حالت متصلشده را مسدود میکند،
,Z را به هر دو bind mount اضافه کنید.
فرمانهای مفید
- گزارشهای کانتینر:
podman logs -f openclaw - توقف کانتینر:
podman stop openclaw - حذف کانتینر:
podman rm -f openclaw - باز کردن نشانی داشبورد از CLI میزبان:
openclaw dashboard --no-open - سلامت/وضعیت از طریق CLI میزبان:
openclaw gateway status --deep(کاوش RPC + اسکن سرویس اضافی)
عیبیابی
- خطای دسترسی رد شد (EACCES) برای پیکربندی یا فضای کاری: کانتینر بهطور پیشفرض با
--userns=keep-idو--user <your uid>:<your 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>را در پوسته خود export کنید. openclaw updateبا--containerناموفق میشود: مورد انتظار است. ایمیج را دوباره بسازید/دریافت کنید، سپس کانتینر یا سرویس Quadlet را دوباره راهاندازی کنید.- سرویس Quadlet راهاندازی نمیشود:
systemctl --user daemon-reloadو سپسsystemctl --user start openclaw.serviceرا اجرا کنید. در سیستمهای بدون نمایشگر ممکن است بهsudo loginctl enable-linger "$(whoami)"نیز نیاز داشته باشید. - SELinux اتصالهای bind mount را مسدود میکند: رفتار پیشفرض اتصال را تغییر ندهید؛ وقتی SELinux در حالت enforcing یا permissive باشد، راهانداز در Linux بهطور خودکار
:Zرا اضافه میکند.
