برنامهٔ لینوکس

Gateway در Linux به‌طور کامل پشتیبانی می‌شود و به Node نیاز دارد. همچنان می‌توان از Bun به‌عنوان نصب‌کنندهٔ وابستگی‌ها یا اجراکنندهٔ اسکریپت‌های بسته استفاده کرد، اما نمی‌تواند OpenClaw را اجرا کند، زیرا node:sqlite را فراهم نمی‌کند.

همراه دسکتاپ

همراه Linux برای OpenClaw یک برنامهٔ دسکتاپ Tauri برای Gateway محلی است. این برنامه:

• هنگامی که OpenClaw CLI و محیط اجرای مدیریت‌شدهٔ Node موجود نباشند، آن‌ها را نصب می‌کند؛ بیلدهای انتشار کانال پایدار را خودکار نصب می‌کنند، درحالی‌که بیلدهای توسعه ابتدا کانال را می‌پرسند
• پیش از تلاش برای تغییر سرویس‌ها، به یک Gateway سالم متصل می‌شود
• عملیات نصب، شروع، توقف و راه‌اندازی مجدد را به سرویس کاربری systemd مدیریت‌شده توسط CLI واگذار می‌کند
• Gatewayهای Bonjour نزدیک را شناسایی می‌کند و رابط کنترل هرکدام را در پنجره‌ای با محدودهٔ مسیر باز می‌کند تا چند داشبورد Gateway بتوانند متصل بمانند و هم‌زمان استفاده شوند
• رابط کنترل ارائه‌شده توسط Gateway را با نشانی احراز هویت حل‌شدهٔ آن باز می‌کند
• پس از نصب اجرای نخست، رابط کنترل را در حالت راه‌اندازی اولیه باز می‌کند که پیشنهاد می‌دهد حافظه‌های شناسایی‌شدهٔ Claude Code، Codex یا Hermes را به فضای کاری عامل وارد کند (همین گزینهٔ واردکردن بعداً نیز در تنظیمات → واردکردن حافظه در دسترس می‌ماند)
• بوم هدایت‌شده توسط عامل و محتوای همراه A2UI را برای میزبان Node مربوط به CLI در همان دستگاه رندر می‌کند
• هنگام بسته‌شدن پنجره، در سینی سیستم در دسترس می‌ماند

انتشارهای پایدار ساخته‌شده از main، بسته‌های .deb و AppImage را به‌عنوان دارایی‌های برچسب مربوطه در انتشار GitHub ارائه می‌کنند که OpenClaw-<version>-amd64.deb و OpenClaw-<version>-amd64.AppImage نام دارند و یک فایل جمع مقابله‌ای SHA256SUMS.linux-app.txt نیز کنار آن‌ها قرار دارد. فایل .deb را بارگیری و با sudo apt install ./OpenClaw-<version>-amd64.deb نصب کنید، یا AppImage را اجرایی کنید و مستقیماً اجرا کنید. محیط اجرای AppImage به FUSE 2 نیاز دارد (sudo apt install libfuse2، یا libfuse2t64 در Ubuntu 24.04+)؛ بدون آن، AppImage را با APPIMAGE_EXTRACT_AND_RUN=1 اجرا کنید.

همچنین می‌توانید همین بسته‌ها را از یک نسخهٔ دریافت‌شدهٔ کد منبع بسازید:

cd apps/linux/src-tauripnpm dlx @tauri-apps/cli@2.11.4 build --bundles deb,appimage

گردش‌کار CI به نام Linux App، همین بسته‌ها را به‌عنوان آرتیفکت openclaw-linux-companion برای Pull requestهایی که برنامه را تغییر می‌دهند و نیز برای اجراهای دستی بارگذاری می‌کند. برای وابستگی‌های بیلد Linux و فرمان‌های توسعه، apps/linux/README.md را در مخزن ببینید.

گفت‌وگوی سریع

گفت‌وگوی سریع را با Ctrl+Shift+Space یا گزینهٔ گفت‌وگوی سریع در سینی باز کنید. تراشهٔ عامل آواتار، ایموجی یا تک‌نگارهٔ پیکربندی‌شده را نشان می‌دهد؛ برای تعویض عامل آن را انتخاب کنید. پیام‌ها از نشست اصلی عامل انتخاب‌شده استفاده می‌کنند و محدودهٔ سراسری نشست را رعایت می‌کنند. کلاینت بومی Rust مالک یک هویت پایدار دستگاه از نوع Ed25519 است. این کلاینت فقط برای راه‌اندازی اولیهٔ جفت‌سازی از توکن یا گذرواژهٔ مشترک تحویل‌داده‌شده توسط CLI استفاده می‌کند، سپس توکن دستگاه صادرشده توسط Gateway را ذخیره می‌کند و در اتصال‌های بعدی ترجیح می‌دهد. هویت و توکن دستگاه در پوشهٔ پیکربندی برنامه، در فایلی با حالت 0600 قرار دارند؛ WebView مربوط به گفت‌وگوی سریع نه اعتبارنامه‌ها را دریافت می‌کند و نه WebSocket را.

هنگامی که اتصال بومی در دسترس نیست، گفت‌وگوی سریع پیام Gateway در دسترس نیست — تلاش مجدد را نشان می‌دهد و ارسال را تا اتصال مجدد غیرفعال می‌کند. دستگاه راه‌دوری که به مرحلهٔ جفت‌سازی رسیده باشد، در عوض پیام این دستگاه را در داشبورد (Nodeها) تأیید کنید را همراه با شناسهٔ کوتاه دستگاه، در صورت ارائه‌شدن توسط Gateway، نشان می‌دهد. Gatewayی که به اعتبارنامهٔ مشترک مفقودشده نیاز دارد، پیام Gateway به اعتبارنامه نیاز دارد — داشبورد را روی میزبان Gateway باز کنید را نشان می‌دهد؛ در آن وضعیت هیچ درخواست جفت‌سازی‌ای در انتظار تأیید نیست. اگر راهنمای اصلاح ارائه‌شده توسط سرور مشخص‌تر باشد، جایگزین این اعلان‌های پیش‌فرض می‌شود. برای Gatewayهای TLS، ‏CLI اثرانگشت SHA-256 گواهی Gateway را به برنامه تحویل می‌دهد؛ کلاینت بومی آن گواهی را سنجاق می‌کند و خطای اعتماد TLS به Gateway ناموفق بود — اثرانگشت گواهی را بررسی کنید را جدا از قطعی گزارش می‌کند. Gatewayهایی که راز مشترکشان از طریق SecretRef پیکربندی شده است، آن را از تحویل CLI حذف می‌کنند. نصب‌های جفت‌شدهٔ موجود با استفاده از توکن دستگاه ذخیره‌شدهٔ خود به کار ادامه می‌دهند، اما یک نصب تازه تحت احراز هویت راز مشترک، بدون آن اعتبارنامهٔ راه‌اندازی اولیه نمی‌تواند درخواست جفت‌سازی در انتظار ایجاد کند. بازخرید کد راه‌اندازی و bootstrapToken به رابط محصول اختصاصی نیاز دارند و برای پیگیری بعدی باقی می‌مانند؛ گفت‌وگوی سریع هیچ‌یک از این جریان‌ها را امتحان نمی‌کند.

در X11، از چرخ‌دندهٔ گفت‌وگوی سریع برای ثبت یا بازنشانی میان‌بر سفارشی استفاده کنید. کلید تغییر وضعیت میان‌بر گفت‌وگوی سریع در سینی، آن را بدون غیرفعال‌کردن گزینهٔ معمول گفت‌وگوی سریع در سینی فعال یا غیرفعال می‌کند. میان‌برهای سراسری در Wayland در دسترس نیستند، بنابراین تنظیمات میان‌بر پنهان می‌شوند و گزینهٔ سینی نقطهٔ ورود باقی می‌ماند. پس از پذیرفته‌شدن ارسال، گفت‌وگوی سریع باز می‌ماند و پاسخ متن سادهٔ عامل انتخاب‌شده را زیر کادر نوشتن به‌صورت جریانی نمایش می‌دهد. برای بستن نوار و پاسخ آن، Esc را فشار دهید؛ Ctrl+Enter همچنان داشبورد را باز می‌کند.

بوم

بوم Linux از دو فرایند همکار استفاده می‌کند. openclaw node run تنها اتصال Node به Gateway باقی می‌ماند؛ Plugin همراه linux-canvas فراخوانی‌های canvas.* را از طریق یک سوکت Unix مخصوص کاربر به برنامهٔ دسکتاپ در حال اجرا هدایت می‌کند. برنامه مالک یک پنجرهٔ WebView درخواستی است که رندرکنندهٔ همراه A2UI و پل کنش به عامل را نیز در بر می‌گیرد.

Plugin به‌طور پیش‌فرض فعال است. این Plugin فقط زمانی بوم را اعلام می‌کند که سوکت دسکتاپ در $XDG_RUNTIME_DIR/openclaw-canvas.sock، یا در صورت در دسترس نبودن XDG_RUNTIME_DIR در /tmp/openclaw-canvas-$UID.sock، وجود داشته باشد. آن را با plugins.entries.linux-canvas.enabled: false غیرفعال کنید. در یک سرور Linux بدون رابط گرافیکی و فاقد برنامهٔ دسکتاپ، بوم اعلام نمی‌شود.

نسخهٔ v1 در Linux از یک پنجرهٔ بوم استفاده می‌کند. صفحه‌های HTTP و HTTPS قابل رندر هستند، اما کنش‌های A2UI فقط از رندرکنندهٔ همراه پذیرفته می‌شوند.

جایگزین CLI و SSH

CLI همچنان ساده‌ترین گزینه برای سرور بدون رابط گرافیکی، VPS یا Gateway راه‌دور است:

1. Node 24.15+ (توصیه‌شده)، Node 22.22.3+ (LTS) یا Node 25.9+ را نصب کنید.
2. npm i -g openclaw@latest
3. openclaw onboard --install-daemon
4. از لپ‌تاپ خود: ssh -N -L 18789:127.0.0.1:18789 <user>@<host>
5. http://127.0.0.1:18789/ را باز کنید و با راز مشترک پیکربندی‌شده احراز هویت کنید (به‌طور پیش‌فرض توکن؛ اگر gateway.auth.mode برابر "password" باشد، گذرواژه).

راهنمای کامل سرور: سرور Linux. نمونهٔ گام‌به‌گام VPS: exe.dev.

قابلیت‌های Node

Plugin همراه Node برای Linux، قابلیت‌های دستگاه سرویس openclaw node را بدون نیاز به برنامهٔ دسکتاپ در اختیار CLI قرار می‌دهد. فرمان‌ها فقط زمانی به Gateway اعلام می‌شوند که قابلیت آن‌ها فعال باشد و ابزار محلی موردنیاز وجود داشته باشد.

Plugin را در openclaw.json پیکربندی کنید:

{  plugins: {    entries: {      "linux-node": {        config: {          notify: { enabled: true },          camera: { enabled: true },          location: { enabled: true },        },      },    },  },}

پس از تغییر این تنظیمات، سرویس Node را راه‌اندازی مجدد کنید. دسترس‌پذیری در هر فرایند یک‌بار تعیین می‌شود و اعلان Node هنگام راه‌اندازی مجدد از نو ساخته می‌شود.

Gateway سطح فرمان‌ها و قابلیت‌های Node را جدا از جفت‌سازی دستگاه تأیید می‌کند. در نخستین راه‌اندازی، یا پس از فعال‌کردن قابلیت‌های بیشتر، سطح در انتظار را تأیید کنید:

openclaw nodes pendingopenclaw nodes approve <requestId>

ممکن است یک Node متصل و با دستگاه جفت شده باشد، درحالی‌که caps و commands مؤثر آن تا تکمیل این تأیید خالی بمانند.

دستگاه‌های دوربین باید برای کاربر سرویس قابل خواندن باشند که معمولاً از طریق گروه video انجام می‌شود. وقتی includeAudio برابر true باشد، کلیپ‌های دوربین از منبع پیش‌فرض PulseAudio یا PipeWire استفاده می‌کنند؛ صدای میکروفون فقط به‌عنوان ترک همان کلیپ وجود دارد، نه به‌صورت فرمانی مستقل. موقعیت مکانی مستلزم آن است که کاربر سرویس Node طبق خط‌مشی GeoClue میزبان مجاز باشد.

camera.snap و camera.clip همچنین به مسلح‌سازی صریح Gateway از طریق gateway.nodes.commands.allow نیاز دارند. برای بارهای داده، محدودیت‌ها و خطاها، ثبت تصویر دوربین و فرمان موقعیت مکانی را ببینید.

نصب

• شروع به کار
• نصب و به‌روزرسانی‌ها
• اختیاری: گردش‌کار بستهٔ Bun، Nix، Docker

سرویس Gateway ‏(systemd)

با یکی از موارد زیر نصب کنید:

openclaw onboard --install-daemonopenclaw gateway installopenclaw configure   # select "Gateway service" when prompted

یک نصب موجود را تعمیر یا مهاجرت دهید:

openclaw doctor

openclaw gateway install به‌طور پیش‌فرض یک واحد کاربری systemd تولید می‌کند. راهنمای کامل سرویس، از جمله گونهٔ واحد در سطح سیستم برای میزبان‌های اشتراکی یا همیشه‌روشن، در راهنمای عملیاتی Gateway قرار دارد.

فقط برای یک راه‌اندازی سفارشی، واحد را دستی بنویسید. نمونهٔ حداقلی واحد کاربری (~/.config/systemd/user/openclaw-gateway[-<profile>].service):

[Unit]Description=OpenClaw Gateway (profile: <profile>, v<version>)After=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

واحدهای دست‌نویس، اندازه‌گذاری تطبیقی heap را که openclaw gateway install برای سرویس‌های مدیریت‌شدهٔ Gateway می‌نویسد به ارث نمی‌برند. نصب‌کنندهٔ مدیریت‌شده را ترجیح دهید، یا پس از درنظرگرفتن فضای آزاد موردنیاز حافظهٔ بومی، در ناظر سفارشی محدودیت صریح heap تعیین کنید.

آن را فعال کنید:

systemctl --user enable --now openclaw-gateway[-<profile>].service

فشار حافظه و خاتمه‌های OOM

در Linux، هنگامی که حافظهٔ یک میزبان، ماشین مجازی یا cgroup کانتینر تمام می‌شود، هسته یک قربانی OOM انتخاب می‌کند. Gateway قربانی مناسبی نیست، زیرا مالک نشست‌های بلندمدت و اتصال‌های کانال است؛ بنابراین OpenClaw تا حد امکان فرایندهای فرزند موقتی را در اولویت خاتمه قرار می‌دهد.

برای ایجاد فرایندهای فرزند واجد شرایط در Linux، ‏OpenClaw فرمان را در یک shim کوتاه /bin/sh قرار می‌دهد که oom_score_adj خود فرزند را به 1000 افزایش می‌دهد، سپس فرمان واقعی را exec می‌کند. این کار به دسترسی ویژه نیاز ندارد: هر فرایندی همیشه می‌تواند امتیاز OOM خود را افزایش دهد.

سطوح فرایند فرزند تحت پوشش:

• فرایندهای فرزند فرمان که توسط ناظر مدیریت می‌شوند
• فرایندهای فرزند پوستهٔ PTY
• فرایندهای فرزند سرور stdio مربوط به MCP
• فرایندهای مرورگر/Chrome راه‌اندازی‌شده توسط OpenClaw (از طریق محیط اجرای فرایند در SDK مربوط به Plugin)

این پوشش فقط مخصوص Linux است و هنگامی که /bin/sh در دسترس نباشد، یا محیط فرزند OPENCLAW_CHILD_OOM_SCORE_ADJ را روی 0، false، no یا off تنظیم کند، نادیده گرفته می‌شود.

یک فرایند فرزند را بررسی کنید:

cat /proc/<child-pid>/oom_score_adj

مقدار مورد انتظار برای فرایندهای فرزند تحت پوشش 1000 است؛ خود فرایند Gateway امتیاز عادی خود را حفظ می‌کند (معمولاً 0).

مقدار OOMPolicy=continue در واحد systemd باعث می‌شود وقتی یک فرایند فرزند موقتی به‌جای کل سرویس توسط خاتمه‌دهندهٔ OOM انتخاب می‌شود، سرویس Gateway فعال بماند و کل واحد ناموفق علامت‌گذاری نشود و همهٔ کانال‌ها راه‌اندازی مجدد نشوند؛ فرایند فرزند یا نشست ناموفق خطای خود را گزارش می‌کند.

این رفتار جایگزین تنظیم عادی حافظه نیست. اگر یک VPS یا کانتینر به‌طور مکرر فرایندهای فرزند را خاتمه می‌دهد، محدودیت حافظه را افزایش دهید، هم‌زمانی را کاهش دهید یا کنترل‌های منابع قوی‌تری اضافه کنید (MemoryMax= در systemd، محدودیت‌های حافظهٔ کانتینر).

مرتبط

• نمای کلی نصب
• سرور لینوکس
• Raspberry Pi
• راهنمای عملیاتی Gateway
• پیکربندی Gateway