---
read_when: You want agent sessions to run on ephemeral cloud machines instead of the Gateway host, or you are configuring cloudWorkers profiles.
sidebarTitle: Cloud Workers
status: active
summary: 'نشست‌ها را به ماشین‌های ابری یک‌بارمصرف واگذار کنید: تأمین، زمان‌اجرای worker، استنتاج پروکسی‌شده و نتایج جریانی'
title: کارگران ابری
x-i18n:
    generated_at: "2026-07-16T16:49:44Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: c20b3b4f1408ed3ef0beb155a207f99476323cf67eba7b44931eec32c79e52be
    source_path: gateway/cloud-workers.md
    workflow: 16
---

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

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

<Note>
عامل‌های ابری اختیاری‌اند و تا زمانی که یک پروفایل پیکربندی نکنید، نامرئی می‌مانند. نصب‌های پیکربندی‌نشده هیچ RPC، پیکربندی یا رابط کاربری جدیدی نمی‌بینند.
</Note>

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

| موضوع                                                 | مکان                                                                         |
| ------------------------------------------------------- | -------------------------------------------------------------------------------- |
| حلقه عامل + ابزارها (`exec`، `read`، `write`، `edit`، …) | ماشین عامل ابری                                                                 |
| استنتاج مدل و اعتبارنامه‌های ارائه‌دهنده                | Gateway (پروکسی‌شده با ارجاع `{provider, model}`)                               |
| رونوشت (پایدار، مخزن نشست)                     | Gateway                                                                          |
| پخش زنده در نوار کناری                         | توزیع Gateway، تغذیه‌شده با جریان رویداد قابل‌بازپخش عامل                      |
| تاریخچه git فضای کاری                                   | بدون اعتبارنامه روی ماشین ایجاد می‌شود؛ Gateway کامیت‌ها را می‌پذیرد و مالک push/PR است |

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

## الزامات

- یک Plugin ارائه‌دهنده عامل. Plugin همراه `crabbox`، [Crabbox](https://github.com/openclaw/crabbox) CLI را هدایت می‌کند که اجاره‌ها را میان بک‌اندهای ابری (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` را از EC2 `DescribeInstances` گزارش کند. اجاره‌های دارای نقش نمونه یا فاقد فراداده معتبر متوقف و رد می‌شوند.
- Node.js روی ماشین اجاره‌شده. ایمیج‌های خام ابری معمولاً آن را ندارند — آن را در فرمان `setup` پروفایل نصب کنید.
- یک نشست با worktree مدیریت‌شده متعلق به نشست (یکی با `worktree: true` ایجاد کنید). ارسال، محتوای آن worktree را منتقل می‌کند؛ دایرکتوری‌های معمولی به‌صورت آینه مانیفست همگام می‌شوند.

## پیکربندی

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

```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)"
        }
      }
    }
  }
}
```

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

| کلید        | معنا                                                                                                                                                                                                                                        |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | شناسه ارائه‌دهنده عامل که توسط یک Plugin ثبت شده است (`crabbox` برای Plugin همراه).                                                                                                                                                                  |
| `install`  | `bundle` (پیش‌فرض) بیلد Gateway درحال‌اجرا را ارسال می‌کند؛ `npm` نسخه دقیق منتشرشده Gateway را با یکپارچگی پین‌شده نصب می‌کند. `npm` مستلزم آن است که Gateway از یک انتشار بسته‌بندی‌شده اجرا شود.                                                      |
| `settings` | JSON متعلق به ارائه‌دهنده. برای crabbox: `provider` (بک‌اند)، `class` (کلاس ماشین)، `ttl`، `idleTimeout` (مدت‌زمان‌های Go)، و در صورت نیاز `setup` و مسیر مطلق `binary`. OpenClaw برای این اجاره‌ها SSH عمومی را اجباری و Tailscale مدیریت‌شده را غیرفعال می‌کند. |
| `lifetime` | سیاست ذخیره‌شده اختیاری (`idleTimeoutMinutes`، `maxLifetimeMinutes`).                                                                                                                                                                           |

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

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

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

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

## ارسال یک نشست

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

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

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

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

```bash
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، فضای کاری راه‌دور را پیش از آن بازگرداند که پاک‌سازی نوبت منقضی بتواند مالک آن را نابود کند. تطبیق، مانیفست عامل را احراز اصالت می‌کند و در صورت واگرایی محلی، به‌جای بازنویسی هر یک از طرفین متوقف می‌شود. پیش از تغییر فایل‌ها، Gateway یک ژورنال بازگردانی محدود را در پایگاه داده وضعیت SQLite خود ذخیره می‌کند؛ تلاش مجدد پس از قطع فرایند Gateway آن ژورنال را بازیابی می‌کند. نتایج فضای کاری از معناشناسی فایل Git استفاده می‌کنند: فایل‌های معمولی، بیت‌های اجرایی، پیوندهای نمادین، افزوده‌ها، تغییرات و حذف‌ها حفظ می‌شوند، اما دایرکتوری‌های خالی و دیگر حالت‌های دایرکتوری حفظ نمی‌شوند. اشیای کامیت راه‌دور حفظ نمی‌شوند؛ تغییرات فایل حاصل برای بازبینی و کامیت عادی در worktree مدیریت‌شده باقی می‌مانند.

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

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

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

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

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

## مدل امنیتی

- **ورودی بسته عامل.** عامل‌ها روی سوکت تونل‌شده با یک پروتکل اختصاصی و فهرست مجاز بسته‌ای از متدها ارتباط برقرار می‌کنند — یک عامل نمی‌تواند RPCهای اپراتور را فراخوانی کند.
- **اعتبارنامه‌های صادرشده، هش‌شده در حالت سکون.** هر ارسال یک اعتبارنامه عامل صادر می‌کند؛ Gateway فقط هش آن را ذخیره می‌کند. چرخش اعتبارنامه و حصارگذاری دوره مالک تضمین می‌کنند که در هر نشست حداکثر یک مالک زنده وجود داشته باشد — عامل منقضی که دوباره متصل شود حصارگذاری می‌شود و هرگز ادغام نمی‌شود.
- **پین‌کردن کلید میزبان.** ارائه‌دهنده باید هنگام تأمین، کلید میزبان SSH ماشین را ارائه کند؛ بوت‌استرپ با پین‌کردن سخت‌گیرانه متصل می‌شود و بدون آن به‌صورت بسته شکست می‌خورد.
- **نبود اعتبارنامه‌های دائمی مدل، forge یا ابر روی ماشین.** احراز هویت مدل روی Gateway باقی می‌ماند (استنتاج با ارجاع `{provider, model}` منتقل می‌شود)، کامیت‌های git فضای کاری بدون اعتبارنامه‌های forge ایجاد می‌شوند و فراداده اجاره Crabbox AWS پیش از راه‌اندازی به‌طور معتبر برای وجود نقش نمونه بررسی می‌شود. فرمان‌های راه‌اندازی را نیز بدون اعتبارنامه نگه دارید.
- **خروجی متعلق به ارائه‌دهنده.** تونل معکوس هرگونه نیاز 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` رد می‌شود).
- **نگهداشت اجاره‌ها** — `crabbox list --provider <backend>` اجاره‌های فعال را نشان می‌دهد؛ `crabbox stop --provider <backend> --id <lease>` یکی را به‌صورت دستی آزاد می‌کند. اجاره‌های بی‌کار بر اساس `idleTimeout` نمایه منقضی می‌شوند.

## مرتبط

- [ایزوله‌سازی](/fa/gateway/sandboxing) — کاهش دامنهٔ آسیب برای اجرای محلی ابزار
- [CLI نشست‌ها](/fa/cli/sessions) — بررسی نشست‌های ذخیره‌شده
- [مرجع پیکربندی](/fa/gateway/configuration-reference)