کارگران ابری

کارگرهای ابری به یک نشست اجازه می‌دهند حلقه عامل خود را روی یک ماشین ابری یک‌بارمصرف اجرا کند، درحالی‌که همه‌چیز درباره نشست همان‌جایی می‌ماند که همیشه بوده است: در نوار کناری قابل‌مشاهده، به‌صورت زنده در حال پخش، و با رونوشت تحت مالکیت Gateway. Gateway یک ماشین اجاره می‌کند، یک نسخه پین‌شده از OpenClaw را روی آن نصب می‌کند، فضای کاری نشست را به آن همگام می‌کند و حلقه نوبت را به یک فرایند محدودشده openclaw worker می‌سپارد. فراخوانی‌های مدل از طریق Gateway به‌صورت پروکسی بازگردانده می‌شوند، بنابراین اطلاعات احراز هویت ارائه‌دهنده هرگز ماشین شما را ترک نمی‌کنند و کش‌کردن پرامپت همچنان کار می‌کند، زیرا ارائه‌دهنده یک جریان پیوسته واحد می‌بیند.

وقتی کار تمام شود (یا ماشین از کار بیفتد)، ماشین کنار گذاشته می‌شود. وضعیت ماندگار — رونوشت، کامیت‌های فضای کاری، رکوردهای جانمایی — نزد Gateway باقی می‌ماند.

چه چیزی کجا اجرا می‌شود

ماشین به‌جز sshd به هیچ درگاه ورودی نیاز ندارد: Gateway از طریق SSH پین‌شده اتصال خروجی برقرار می‌کند و یک تونل معکوس، WebSocket کارگر را بازمی‌گرداند. ارائه‌دهنده همراه Crabbox مسیر عمومی SSH را اجباری می‌کند و ثبت‌نام مدیریت‌شده Tailscale را غیرفعال می‌کند. دسترسی خروجی به اینترنت تابع سیاست ارائه‌دهنده است؛ پروفایل پیش‌فرض AWS می‌تواند به اینترنت دسترسی داشته باشد، مگر اینکه شبکه یا گروه امنیتی آن را محدود کنید.

الزامات

• یک Plugin ارائه‌دهنده کارگر. Plugin همراه crabbox، CLI مربوط به Crabbox را راه‌اندازی می‌کند که اجاره‌ها را میان زیرساخت‌های ابری (AWS، Hetzner و دیگران) واسطه‌گری می‌کند. باینری crabbox باید در PATH باشد (یا settings.binary را تنظیم کنید) و اطلاعات احراز هویت ارائه‌دهنده از قبل پیکربندی شده باشند. پذیرش AWS به Crabbox 0.38.1 یا جدیدتر نیاز دارد.
• برای کارگرهای Crabbox AWS، مقدار مؤثر aws.instanceProfile باید خالی باشد. ارائه‌دهنده پیش از تخصیص، crabbox config show --json را بررسی می‌کند، سپس الزام می‌کند که crabbox inspect --json مقدار providerMetadata.instanceProfileAttached: false را از DescribeInstances مربوط به EC2 گزارش کند. اجاره‌های دارای نقش نمونه یا فاقد فراداده معتبر متوقف و رد می‌شوند.
• Node.js روی ماشین اجاره‌شده. ایمیج‌های خام ابری معمولاً آن را ندارند — آن را در فرمان setup پروفایل نصب کنید.
• نشستی با worktree مدیریت‌شده متعلق به نشست (یکی با worktree: true ایجاد کنید). اعزام، محتوای آن worktree را جابه‌جا می‌کند؛ دایرکتوری‌های ساده به‌صورت آینه مانیفست همگام می‌شوند.

پیکربندی

یک پروفایل زیر cloudWorkers.profiles در openclaw.json اضافه کنید:

{  "cloudWorkers": {    "profiles": {      "aws": {        "provider": "crabbox",        "install": "bundle",        "settings": {          "provider": "aws",          "class": "standard",          "ttl": "8h",          "idleTimeout": "45m",          "setup": "test -x /usr/bin/node || (curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs)"        }      }    }  }}

فیلدهای پروفایل:

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

settings.setup پس از آماده‌شدن SSH ماشین اجاره‌شده و پیش از نصب OpenClaw روی آن اجرا می‌شود. این فرمان در هر تلاش تأمین اجرا می‌شود (ازجمله بازپخش‌ها پس از اعزام قطع‌شده)، بنابراین باید هم‌توان باشد — همانند مثال، نصب‌ها را با بررسی command -v/test -x محافظت کنید. اگر راه‌اندازی شکست بخورد، ارائه‌دهنده اجاره را متوقف می‌کند و اعزام به‌صورت بسته شکست می‌خورد؛ هیچ ماشین نیمه‌پیکربندی‌شده‌ای در حال اجرا باقی نمی‌ماند.

کانال‌های نصب

• bundle، dist مربوط به Gateway در حال اجرا، یک package.json هرس‌شده و هر بسته فضای کاری مورد ارجاع بیلد را بسته‌بندی می‌کند که همگی تحت پوشش یک هش محتوا هستند. ماشین، بسته دست‌نخورده را با آن هش تأیید می‌کند و سپس وابستگی‌های npm تولید را نصب می‌کند (اسکریپت‌ها غیرفعال‌اند). به این روش می‌توان یک بیلد توسعه را روی کارگر اجرا کرد.
• npm وجود انتشار در رجیستری عمومی را اثبات می‌کند، یکپارچگی SHA-512 آن را پین می‌کند و openclaw@<version> را دقیقاً مطابق Gateway نصب می‌کند.

اعزام یک نشست

در رابط کاربری Control، New Session را باز کنید، عاملی را انتخاب کنید که runtime پیکربندی‌شده آن OpenClaw باشد، یک مقصد پیکربندی‌شده Cloud · profile را از منوی Where انتخاب کنید و کار را آغاز کنید. انتخاب ابر، worktree مدیریت‌شده موردنیاز را به‌طور خودکار فعال می‌کند؛ Gateway نشست را ایجاد می‌کند، اعزام را به پایان می‌رساند و تنها پس از آن نوبت نخست را ارسال می‌کند. نشان سرور در نوار کناری نشست، وضعیت ماندگار جانمایی را نشان می‌دهد. مقصدهای ابری برای کاتالوگ نشست‌های CLI خارجی ارائه نمی‌شوند.

جریان RPC معادل چنین است:

نشستی با یک worktree مدیریت‌شده ایجاد و سپس آن را اعزام کنید (RPC به operator.admin نیاز دارد و فقط هنگامی وجود دارد که پروفایل‌ها پیکربندی شده باشند):

کارگرهای ابری runtime عامل OpenClaw را اجرا می‌کنند. یک openai/* یا مدل دیگری انتخاب کنید که به آن runtime منتهی شود؛ نشست‌های پیکربندی‌شده برای یک runtime خارجی CLI مانند claude-cli قابل اعزام نیستند.

openclaw gateway call sessions.create \  --params '{"key":"agent:main:big-refactor","worktree":true,"cwd":"/path/to/repo","worktreeName":"big-refactor"}' openclaw gateway call sessions.dispatch \  --timeout 1500000 \  --params '{"key":"agent:main:big-refactor","profileId":"aws"}'

sessions.dispatch پذیرش نوبت محلی را می‌بندد، کار فعال را تخلیه می‌کند، اجاره را تأمین می‌کند، راه‌اندازی را اجرا می‌کند، OpenClaw را بوت‌استرپ می‌کند، فضای کاری را همگام می‌کند و وقتی بازمی‌گردد که جانمایی به مالکیت کارگر active برسد. برای نخستین اعزام چند دقیقه در نظر بگیرید؛ هرجا ارائه‌دهنده پشتیبانی کند، اجاره‌ها و نصب‌ها کش می‌شوند. پس از آن، طبق معمول با نشست تعامل کنید — نوبت‌ها به‌طور خودکار به کارگر هدایت می‌شوند.

نوبت‌های تکمیل‌شده کارگر، پیش از آزادشدن ادعای نوبت، فایل‌های واجدشرایط و دارای اندازه محدود فضای کاری را به worktree مدیریت‌شده نشست بازتطبیق می‌دهند. رویداد پایانی کارگر پیش از تأییدشدن، یک حصار نتیجه معلق ماندگار ایجاد می‌کند. سپس Gateway پیش از اعمال نتیجه کامل ابری، آن را به‌عنوان یک ref از Git زیر refs/openclaw/worker-results/ stage می‌کند تا نسخه ابری حتی اگر Gateway هنگام اعمال متوقف شود، قابل‌بازیابی بماند. نتایج فضای کاری از معناشناسی فایل Git استفاده می‌کنند: فایل‌های عادی، بیت‌های اجرایی، پیوندهای نمادین، افزوده‌ها، تغییرها و حذف‌ها حفظ می‌شوند، اما دایرکتوری‌های خالی و دیگر حالت‌های دایرکتوری حفظ نمی‌شوند. تغییرهای فایل حاصل برای بازبینی و کامیت عادی در worktree مدیریت‌شده باقی می‌مانند.

اعمال از مانیفست زمان اعزام به‌عنوان پایه ادغام استفاده می‌کند. تغییرهای فقط ابری اعمال می‌شوند، تغییرهای فقط محلی سر جای خود می‌مانند و مسیرهایی که در هر دو سمت تغییر کرده‌اند از سیاست سه‌طرفه حفظ نسخه محلی استفاده می‌کنند. نوبت دارای تداخل نیز پایان می‌یابد: رونوشت، خلاصه محدود مسیرها و ref نتیجه stage‌شده را گزارش می‌کند، جانمایی همان تداخل را برای رابط کاربری Control آشکار می‌کند و تغییرهای ابری بدون تداخل همچنان اعمال‌شده باقی می‌مانند. اعلان شامل git show <ref>:<path> برای بررسی یک فایل ابری موجود و یک فرمان git checkout <ref> -- <path> با pathspec صریح در سطح بالا برای دریافت آن از هر دایرکتوری فضای کاری است. فرمان‌ها را در Bash یا zsh (Git Bash در Windows) اجرا کنید. اگر بررسی اعلام کند مسیر وجود ندارد، نتیجه ابری آن را حذف کرده است؛ بررسی کنید و مسیر محلی حفظ‌شده را دستی حذف کنید. اگر checkout از وجود مانع فایل/دایرکتوری گزارش داد، مسیر محلی مسدودکننده را جابه‌جا یا حذف و دوباره تلاش کنید. اگر خود ref stage‌شده از بین رفته است، اعلان را منقضی در نظر بگیرید و مسیر محلی را تغییر ندهید. refهای stage‌شده دارای تداخل پس از آزادشدن حصار عادی نوبت همچنان در دسترس می‌مانند؛ یک نتیجه پاک بعدی اعلان را پاک و ref قدیمی را بازنشسته می‌کند، درحالی‌که حذف صریح حصار، مرز نهایی پاک‌سازی است.

تا زمانی که یک نتیجه حصارگذاری‌شده همچنان در حال بازتطبیق است، نوبت جدید تا 15 ثانیه برای آزادشدن ادعای قبلی منتظر می‌ماند. اگر همچنان مشغول باشد، نوبت با پیام عملیاتی «نتیجه فضای کاری نوبت ابری قبلی همچنان در حال بازتطبیق است» شکست می‌خورد و می‌توان اندکی بعد دوباره تلاش کرد. هنگام راه‌اندازی مجدد، بازیابی پیش از پاک‌سازی ادعای منقضی، نتایج معلق و stage‌شده را پیدا می‌کند، اعمال محلی آن‌ها را تکمیل می‌کند یا دوباره می‌کوشد و محیط‌های ازکارافتاده را تنها پس از حفظ نتیجه بازپس می‌گیرد. ژورنال بازگردانی محدود SQLite، اعمال فایل‌سیستم قطع‌شده را بدون بازپخش جهش‌های از قبل پذیرفته‌شده قابل‌بازیابی می‌کند.

وقتی کار کامل شده و هیچ نوبتی در حال اجرا نیست، منوی نشست را باز و Stop cloud worker… را انتخاب کنید. Gateway پیش از نابودکردن محیط، یک بازتطبیق نهایی فضای کاری انجام می‌دهد. جانمایی‌ای که از قبل در draining یا reconciling است، در حال تکمیل برچیدن است؛ پیش از حذف نشست منتظر بمانید نشان آن به reclaimed تبدیل شود.

برای یک کارگر متصل خراب یا مهارنشدنی، اپراتور می‌تواند به‌عنوان آخرین راه‌حل، environments.destroy را با { "force": true } فراخوانی کند. برچیدن اجباری، جانمایی را به‌طور ماندگار شکست‌خورده علامت می‌زند و پیش از نابودکردن محیط، هر نتیجه راه‌دور بازتطبیق‌نشده را رها می‌کند.

RPC مدیریتی معادل چنین است:

openclaw gateway call sessions.reclaim \  --timeout 600000 \  --params '{"key":"agent:main:big-refactor"}'

جای‌گذاری از طریق یک ماشین حالت پایدار (local → requested → provisioning → syncing → starting → active) انجام می‌شود؛ بنابراین اگر Gateway در میانه ارسال مجدداً راه‌اندازی شود، به‌جای رها کردن ماشین‌ها، تطبیق انجام می‌شود. ناموفق بودن یک نوبت مدل، جای‌گذاری فعال را برای تلاش مجدد در دسترس نگه می‌دارد. در تعارض‌های مسیر فضای کاری، نسخه محلی حفظ می‌شود، بقیه نتیجه ابری اعمال می‌شود و ارجاع ابری مرحله‌بندی‌شده برای بررسی باقی می‌ماند؛ سایر خطاهای تطبیق یا چرخه‌عمر، حصار بازیابی پایدار و دنباله تشخیصی خود را حفظ می‌کنند تا بازیابی بتواند با ایمنی تلاش مجدد کند یا محیط را بازپس‌گیرد.

مدل امنیتی

• ورودی بسته کارگر. کارگرها از طریق سوکت تونل‌شده و با پروتکلی اختصاصی که فهرست مجاز بسته‌ای از متدها دارد ارتباط برقرار می‌کنند — کارگر نمی‌تواند RPCهای اپراتور را فراخوانی کند.
• اختیار ابزار تحت مالکیت Gateway. پیش از هر نوبت، Gateway سیاست فعلی پروفایل، ارائه‌دهنده، عامل، گروه، فرستنده، سندباکس، تفویض، ارث‌بری و سقف زمان اجرا را روی کاتالوگ ثابت ابزارهای کدنویسی کارگر اعمال می‌کند. پاکت راه‌اندازی فقط همان زیرمجموعه نهایی با واژگان بسته را حمل می‌کند. نوبت‌های زمان‌بندی‌شده‌ای که صراحتاً محدود شده‌اند، بدون ارسال آن هویت به جعبه یا اعمال مجدد پوشش فرستنده جدید، از زمینه مورداعتماد گروه مالک خود استفاده می‌کنند. ابزارهای خارج از کاتالوگ کارگر همچنان در دسترس نیستند؛ نتیجه خالی بدون ابزار اجرا می‌شود.
• اعتبارنامه‌های صادرشده، هش‌شده در حالت ذخیره. هر ارسال یک اعتبارنامه کارگر صادر می‌کند؛ Gateway فقط هش آن را ذخیره می‌کند. چرخش اعتبارنامه و حصارکشی دوره مالک تضمین می‌کنند که برای هر نشست حداکثر یک مالک زنده وجود داشته باشد — کارگر منقضی‌شده‌ای که دوباره متصل شود حصارکشی می‌شود و هرگز ادغام نمی‌شود.
• سنجاق‌کردن کلید میزبان. ارائه‌دهنده باید هنگام تأمین، کلید میزبان SSH جعبه را ارائه کند؛ راه‌انداز اولیه با سنجاق‌کردن سخت‌گیرانه متصل می‌شود و بدون آن به‌صورت بسته شکست می‌خورد.
• نبود اعتبارنامه دائمی مدل، فورج یا ابر روی جعبه. احراز هویت مدل روی Gateway باقی می‌ماند (استنتاج از طریق ارجاع {provider, model} منتقل می‌شود)، کامیت‌های git فضای کاری بدون اعتبارنامه فورج ایجاد می‌شوند و فراداده اجاره AWS در Crabbox پیش از راه‌اندازی، به‌طور معتبر برای وجود نقش نمونه بررسی می‌شود. فرمان‌های راه‌اندازی را نیز بدون اعتبارنامه نگه دارید.
• خروجی شبکه تحت مالکیت ارائه‌دهنده. تونل معکوس هرگونه نیاز OpenClaw به دسترسی مستقیم به مدل را برطرف می‌کند، اما OpenClaw دیوارهای آتش ارائه‌دهنده را بازنویسی نمی‌کند. هرگاه وظیفه ایجاب می‌کند، ترافیک خروجی را در ارائه‌دهنده کارگر محدود کنید.
• رونوشت‌های پایدار و دقیقاً یک‌بار. کارگر دسته‌های رونوشت را از طریق پروتکل مقایسه‌و‌تعویض در برابر برگ نشست کامیت می‌کند؛ پایه منقضی‌شده به‌جای تکثیر یا بازپایه‌گذاری خروجی پولی، اجرای عملیات را متوقف می‌کند.

عیب‌یابی

• sessions.dispatch متدی ناشناخته است — هیچ cloudWorkers.profiles پیکربندی نشده است یا فراخواننده operator.admin را ندارد.
• "نوبت‌های کارگر ابری به زمان اجرای OpenClaw نیاز دارند" — مدلی را انتخاب کنید که زمان اجرای پیکربندی‌شده آن OpenClaw باشد. زمان‌های اجرای CLI خارجی مانند claude-cli از استنتاج کارگر پشتیبانی نمی‌کنند.
• "راه‌اندازی اولیه کارگر به Node.js روی میزبان اجاره‌شده نیاز دارد" — نصب Node را به settings.setup اضافه کنید (بالا را ببینید).
• تصدیق نقش نمونه AWS ناموفق است — aws.instanceProfile را پاک کنید (و اگر تنظیم شده است، CRABBOX_AWS_INSTANCE_PROFILE را نیز پاک کنید). Crabbox نسخه 0.38.1 یا جدیدتر را نصب کنید؛ باینری‌های قدیمی‌تر قرارداد معتبر providerMetadata.instanceProfileAttached موردنیاز برای پذیرش AWS را ارائه نمی‌کنند.
• ارسال با خطای ارائه‌دهنده ناموفق می‌شود — رکورد جای‌گذاری و environments.list آخرین خطا، از جمله دنباله stderr راه‌اندازی/راه‌انداز اولیه را نگه می‌دارند. جعبه‌ها هنگام شکست نابود می‌شوند، بنابراین این دنباله منبع اصلی بررسی جرم‌شناختی است.
• مهلت کلاینت هنگام ارسال به پایان می‌رسد — مهلت پیش‌فرض openclaw gateway call برابر با 10s است؛ مقدار --timeout را سخاوتمندانه تعیین کنید (ارسال در هر صورت در سمت سرور ادامه می‌یابد و تلاش مجدد حین تأمین با session cannot dispatch from placement provisioning رد می‌شود).
• کارگر پس از ارتقا از نسخه بتای 2026.7.2 بازپس‌گرفته می‌شود — آن نسخه‌های بتا از قرارداد قدیمی‌تر راه‌اندازی کارگر استفاده می‌کردند. هنگام راه‌اندازی مجدد، OpenClaw یک کارگر بیکار ناسازگار را نابود می‌کند، نشست و فضای کاری را نگه می‌دارد، جای‌گذاری را بازپس‌گرفته‌شده علامت می‌زند و در ارسال یا نوبت بعدی یک کارگر فعلی تأمین می‌کند. کارگر بتایی که در حین آغاز به کار متوقف شود، پس از پاک‌سازی ناموفق علامت‌گذاری می‌شود؛ برای تأمین آن با قرارداد فعلی، ارسال را دوباره امتحان کنید.
• اعلان تعارض فضای کاری ابری — نوبت تکمیل شده و نسخه محلی هر مسیر فهرست‌شده را حفظ کرده است. برای بررسی یا دریافت نسخه ابری، از فرمان‌های ارجاع مرحله‌بندی‌شده در اعلان استفاده کنید؛ برای تغییرات بدون تعارض که از قبل اعمال شده‌اند، نیازی به تلاش مجدد نیست.
• «نتیجه فضای کاری نوبت ابری قبلی همچنان در حال تطبیق است» — Gateway مدت کوتاهی برای حصار پایدار نتیجه قبلی منتظر ماند و نتوانست ادعای نشست را به‌دست آورد. صبر کنید تا تطبیق تمام شود، سپس نوبت را دوباره امتحان کنید؛ راه‌اندازی مجدد Gateway ایمن است، زیرا بازیابی پیش از بازپس‌گیری کارگر ازکارافتاده، نتایج مرحله‌بندی‌شده را حفظ می‌کند.
• نگهداشت اجاره‌ها — crabbox list --provider <backend> اجاره‌های فعال را نشان می‌دهد؛ crabbox stop --provider <backend> --id <lease> یکی را به‌صورت دستی آزاد می‌کند. اجاره‌های بیکار بر اساس idleTimeout پروفایل منقضی می‌شوند.

مرتبط

• سندباکس‌سازی — کاهش دامنه آسیب برای اجرای ابزار محلی
• CLI نشست‌ها — بررسی نشست‌های ذخیره‌شده
• مرجع پیکربندی