---
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: 'توجيه الجلسات إلى أجهزة سحابية مؤقتة: التزويد، وبيئة تشغيل العامل، والاستدلال عبر الوكيل، وبثّ النتائج المتدفقة'
title: العاملون السحابيون
x-i18n:
    generated_at: "2026-07-16T14:15:36Z"
    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>
العُقد العاملة السحابية اختيارية ولا تظهر حتى تهيئ ملفًا شخصيًا. لا ترى عمليات التثبيت غير المهيأة أي RPCs أو إعدادات أو واجهة مستخدم جديدة.
</Note>

## ما الذي يعمل وأين

| الجانب                                                 | الموقع                                                                         |
| ------------------------------------------------------- | -------------------------------------------------------------------------------- |
| حلقة الوكيل + الأدوات (`exec`، `read`، `write`، `edit`، …) | جهاز العقدة العاملة السحابية                                                                 |
| استدلال النموذج وبيانات اعتماد المزوّد                | Gateway (يُمرَّر بالوكالة بواسطة مرجع `{provider, model}`)                               |
| النص المنسوخ (دائم، مخزن الجلسة)                     | Gateway                                                                          |
| التدفق المباشر إلى الشريط الجانبي                         | توزيع Gateway، تغذّيه سلسلة أحداث العقدة العاملة القابلة لإعادة التشغيل                      |
| سجل Git لمساحة العمل                                   | يُنشأ على الجهاز بلا بيانات اعتماد؛ يتبنّى Gateway الالتزامات ويمتلك الدفع/طلب السحب |

لا يحتاج الجهاز إلى منافذ واردة باستثناء `sshd`: يتصل Gateway إلى الخارج عبر SSH مثبّت المفتاح، ويحمل نفق عكسي WebSocket الخاص بالعقدة العاملة عائدًا. يفرض مزوّد Crabbox المضمّن مسار SSH العام ويعطّل التسجيل المُدار في Tailscale. الوصول الصادر إلى الإنترنت من سياسة المزوّد؛ يمكن لملف AWS الافتراضي الوصول إلى الإنترنت ما لم تقيّد شبكته أو مجموعة الأمان الخاصة به.

## المتطلبات

- Plugin لمزوّد عُقد عاملة. يقود Plugin ‏`crabbox` المضمّن [CLI الخاص بـ Crabbox](https://github.com/openclaw/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: true`). ينقل الإرسال محتويات شجرة العمل تلك؛ وتُزامن الأدلة العادية كمرآة بيان.

## التهيئة

أضف ملفًا شخصيًا ضمن `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 تمامًا.

## إرسال جلسة

في واجهة التحكم، افتح **جلسة جديدة**، واختر وكيلًا يكون وقت التشغيل المهيأ له هو OpenClaw، وحدد هدف **السحابة · الملف الشخصي** المهيأ من قائمة **المكان**، وابدأ المهمة. يفعّل تحديد السحابة شجرة العمل المُدارة المطلوبة تلقائيًا؛ وينشئ Gateway الجلسة، ويكمل الإرسال، وعندئذ فقط يرسل الدور الأول. تعرض شارة الخادم في الشريط الجانبي للجلسة حالة الموضع الدائمة. لا تُعرض الأهداف السحابية لكتالوجات جلسات CLI الخارجية.

تدفق RPC المكافئ هو:

أنشئ جلسة ذات شجرة عمل مُدارة، ثم أرسلها (يتطلب RPC ‏`operator.admin` ولا يكون موجودًا إلا عند تهيئة الملفات الشخصية):

تشغّل العُقد العاملة السحابية وقت تشغيل وكيل OpenClaw. اختر `openai/*` أو نموذجًا آخر يُحل إلى وقت التشغيل ذلك؛ لا يمكن إرسال الجلسات المهيأة لوقت تشغيل 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`. خصّص عدة دقائق للإرسال الأول؛ تُخزّن عمليات الاستئجار والتثبيت مؤقتًا حيث يدعم المزوّد ذلك. بعد ذلك، تفاعل مع الجلسة كالمعتاد — تُوجّه الأدوار إلى العقدة العاملة تلقائيًا.

تعيد أدوار العقدة العاملة المكتملة تسوية ملفات مساحة العمل المؤهلة والمحدودة الحجم إلى شجرة العمل المُدارة للجلسة قبل تحرير المطالبة بالدور. ينشئ حدث العقدة العاملة النهائي حاجز نتيجة معلّقة دائمًا قبل الإقرار به، لذلك تستعيد عملية التعافي من إعادة تشغيل Gateway مساحة العمل البعيدة قبل أن يتمكن تنظيف الدور القديم من تدمير مالكها. تصادق التسوية على بيان العقدة العاملة وتتوقف عند وجود تباعد محلي بدلًا من الكتابة فوق أي من الجانبين. قبل تغيير الملفات، يخزّن Gateway سجل تراجع محدودًا في قاعدة بيانات حالة SQLite الخاصة به؛ وتستعيد إعادة المحاولة ذلك السجل بعد انقطاع عملية Gateway. تستخدم نتائج مساحة العمل دلالات ملفات Git: تُحتفظ بالملفات العادية، وبتات التنفيذ، والروابط الرمزية، والإضافات، والتغييرات، والحذف، بينما لا تُحتفظ بالأدلة الفارغة وأنماط الأدلة الأخرى. لا يُحتفظ بكائنات الالتزام البعيدة؛ وتبقى تغييرات الملفات الناتجة في شجرة العمل المُدارة للمراجعة والالتزام المعتادين.

عند اكتمال العمل وعدم وجود دور قيد التشغيل، افتح قائمة الجلسة واختر **إيقاف العقدة العاملة السحابية…**. يجري 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 في منتصف الإرسال التسوية بدلًا من تسريب الأجهزة. يُبقي دور النموذج الفاشل الموضع النشط متاحًا لإعادة المحاولة. إذا فشلت تسوية مساحة العمل الواردة، تظل العقدة العاملة نشطة أيضًا حتى يتمكن المشغّل من حل التعارض المحلي وإعادة المحاولة دون فقدان النتيجة البعيدة؛ أما إخفاقات دورة الحياة فتنقل الموضع إلى حالة خطأ أو استرداد وتحافظ على ذيل التشخيص الخاص بها.

## نموذج الأمان

- **وصول وارد مغلق للعقدة العاملة.** تتواصل العُقد العاملة ببروتوكول مخصص على المقبس النفقي مع قائمة سماح مغلقة للطرائق — لا يمكن للعقدة العاملة استدعاء RPCs الخاصة بالمشغّل.
- **بيانات اعتماد مُنشأة، ومجزأة عند التخزين.** ينشئ كل إرسال بيانات اعتماد للعقدة العاملة؛ ولا يخزّن Gateway سوى تجزئتها. يضمن تدوير بيانات الاعتماد وتسييج حقبة المالك وجود مالك حي واحد على الأكثر لكل جلسة — وتُسيَّج العقدة العاملة القديمة التي تعيد الاتصال، ولا تُدمج أبدًا.
- **تثبيت مفتاح المضيف.** يجب أن يعرض المزوّد مفتاح مضيف SSH الخاص بالجهاز عند وقت التوفير؛ ويتصل التمهيد بتثبيت صارم ويفشل بصورة مغلقة بدونه.
- **لا توجد بيانات اعتماد دائمة للنموذج أو مستودع الاستضافة أو السحابة على الجهاز.** تبقى مصادقة النموذج على Gateway (ينتقل الاستدلال بواسطة مرجع `{provider, model}`)، وتُنشأ التزامات Git لمساحة العمل دون بيانات اعتماد مستودع الاستضافة، ويُتحقق بصورة موثوقة من بيانات وصف استئجار 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` في ملف التعريف.

## ذو صلة

- [العزل ضمن بيئة محمية](/ar/gateway/sandboxing) — تقليل نطاق التأثير عند تنفيذ الأدوات محليًا
- [CLI للجلسات](/ar/cli/sessions) — فحص الجلسات المخزّنة
- [مرجع الإعدادات](/ar/gateway/configuration-reference)