> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# إدارة الجلسات

# إدارة الجلسات

يتعامل OpenClaw مع **جلسة دردشة مباشرة واحدة لكل وكيل** على أنها الأساسية. تُطوى الدردشات المباشرة إلى `agent:<agentId>:<mainKey>` (الافتراضي `main`)، بينما تحصل دردشات المجموعات/القنوات على مفاتيحها الخاصة. يتم احترام `session.mainKey`.

استخدم `session.dmScope` للتحكم في كيفية تجميع **الرسائل المباشرة**:

* `main` (الافتراضي): تشترك جميع الرسائل المباشرة في الجلسة الرئيسية من أجل الاستمرارية.
* `per-peer`: عزل حسب معرّف المُرسِل عبر القنوات.
* `per-channel-peer`: عزل حسب القناة + المُرسِل (موصى به لصناديق الوارد متعددة المستخدمين).
* `per-account-channel-peer`: عزل حسب الحساب + القناة + المُرسِل (موصى به لصناديق الوارد متعددة الحسابات).
  استخدم `session.identityLinks` لربط معرّفات الأقران المسبوقة بموفّر بهوية معيارية، بحيث يشترك الشخص نفسه في جلسة رسالة مباشرة واحدة عبر القنوات عند استخدام `per-peer` أو `per-channel-peer` أو `per-account-channel-peer`.

## وضع الرسائل المباشرة الآمن (موصى به للإعدادات متعددة المستخدمين)

> **تحذير أمني:** إذا كان وكيلك يمكنه تلقي رسائل مباشرة من **عدة أشخاص**، فيجب عليك بشدة تمكين وضع الرسائل المباشرة الآمن. بدونه، يشترك جميع المستخدمين في سياق محادثة واحد، ما قد يؤدي إلى تسريب معلومات خاصة بين المستخدمين.

**مثال على المشكلة مع الإعدادات الافتراضية:**

* أليس (`<SENDER_A>`) تراسل وكيلك حول موضوع خاص (على سبيل المثال، موعد طبي)
* بوب (`<SENDER_B>`) يراسل وكيلك ويسأل «عمّ كنا نتحدث؟»
* لأن الرسالتين المباشرتين تشتركان في الجلسة نفسها، قد يجيب النموذج بوب باستخدام سياق أليس السابق.

**الحل:** اضبط `dmScope` لعزل الجلسات لكل مستخدم:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
// ~/.openclaw/openclaw.json
{
  session: {
    // Secure DM mode: isolate DM context per channel + sender.
    dmScope: "per-channel-peer",
  },
}
```

**متى يجب تمكين هذا:**

* لديك موافقات إقران لأكثر من مُرسِل واحد
* أنت تستخدم قائمة سماح DM تحتوي على عدة إدخالات
* تضبط `dmPolicy: "open"`
* يمكن لأرقام هواتف أو حسابات متعددة مراسلة وكيلك

ملاحظات:

* الافتراضي هو `dmScope: "main"` للاستمرارية (تشارك جميع الرسائل المباشرة الجلسة الرئيسية). هذا مناسب لإعدادات المستخدم الواحد.
* لصناديق الوارد متعددة الحسابات على القناة نفسها، يُفضَّل `per-account-channel-peer`.
* إذا تواصل الشخص نفسه معك عبر قنوات متعددة، استخدم `session.identityLinks` لدمج جلسات الرسائل المباشرة في هوية معيارية واحدة.
* يمكنك التحقق من إعدادات الرسائل المباشرة لديك باستخدام `openclaw security audit` (انظر [الأمان](/cli/security)).

## الـ Gateway هو مصدر الحقيقة

تعود **ملكية** حالة الجلسة بالكامل إلى الـ Gateway (النسخة «الرئيسية» من OpenClaw). يجب على عملاء واجهة المستخدم (تطبيق macOS، WebChat، إلخ) الاستعلام من الـ Gateway عن قوائم الجلسات وعدّادات الرموز بدل قراءة الملفات المحلية.

* في **الوضع البعيد**، يوجد مخزن الجلسات الذي يهمك على مضيف Gateway البعيد، وليس على جهاز Mac لديك.
* تأتي عدّادات الرموز المعروضة في واجهات المستخدم من حقول مخزن الـ Gateway (`inputTokens` و`outputTokens` و`totalTokens` و`contextTokens`). لا تقوم العملاء بتحليل نصوص JSONL «لتصحيح» الإجماليات.

## أين تعيش الحالة

* على **مضيف Gateway**:
  * ملف المخزن: `~/.openclaw/agents/<agentId>/sessions/sessions.json` (لكل وكيل).
* النصوص: `~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl` (تستخدم جلسات مواضيع Telegram `.../<SessionId>-topic-<threadId>.jsonl`).
* المخزن عبارة عن خريطة `sessionKey -> { sessionId, updatedAt, ... }`. حذف الإدخالات آمن؛ إذ تُعاد إنشاؤها عند الطلب.
* قد تتضمن إدخالات المجموعات `displayName` و`channel` و`subject` و`room` و`space` لوضع تسميات للجلسات في واجهات المستخدم.
* تتضمن إدخالات الجلسة بيانات وصفية `origin` (تسمية + تلميحات توجيه) كي تتمكن واجهات المستخدم من شرح مصدر الجلسة.
* لا يقرأ OpenClaw **مجلدات جلسات Pi/Tau القديمة**.

## تقليم الجلسات

يقوم OpenClaw افتراضيًا بقص **نتائج الأدوات القديمة** من السياق الموجود في الذاكرة مباشرة قبل استدعاءات LLM.
لا يؤدي ذلك إلى إعادة كتابة سجل JSONL. انظر [/concepts/session-pruning](/concepts/session-pruning).

## تفريغ الذاكرة قبل الضغط

عندما تقترب الجلسة من الضغط التلقائي، يمكن لـ OpenClaw تنفيذ **تفريغ ذاكرة صامت**
يذكّر النموذج بكتابة ملاحظات دائمة على القرص. يعمل هذا فقط عندما تكون مساحة العمل قابلة للكتابة. انظر [الذاكرة](/concepts/memory) و[الضغط](/concepts/compaction).

## ربط وسائل النقل → مفاتيح الجلسات

* تتبع الدردشات المباشرة `session.dmScope` (الافتراضي `main`).
  * `main`: `agent:<agentId>:<mainKey>` (استمرارية عبر الأجهزة/القنوات).
    * يمكن لأرقام هواتف وقنوات متعددة أن تُربط بالمفتاح الرئيسي نفسه للوكيل؛ وتعمل كوسائط نقل إلى محادثة واحدة.
  * `per-peer`: `agent:<agentId>:dm:<peerId>`.
  * `per-channel-peer`: `agent:<agentId>:<channel>:dm:<peerId>`.
  * `per-account-channel-peer`: `agent:<agentId>:<channel>:<accountId>:dm:<peerId>` (يكون accountId افتراضيًا `default`).
  * إذا طابق `session.identityLinks` معرّف قرين مسبوقًا بموفّر (على سبيل المثال `telegram:123`)، فإن المفتاح المعياري يستبدل `<peerId>` بحيث يشترك الشخص نفسه في جلسة واحدة عبر القنوات.
* تعزل الدردشات الجماعية الحالة: `agent:<agentId>:<channel>:group:<id>` (تستخدم الغرف/القنوات `agent:<agentId>:<channel>:channel:<id>`).
  * تُلحِق مواضيع منتديات Telegram `:topic:<threadId>` بمعرّف المجموعة للعزل.
  * لا تزال مفاتيح `group:<id>` القديمة معترفًا بها لأغراض الترحيل.
* قد تستخدم السياقات الواردة `group:<id>`؛ تُستنتج القناة من `Provider` وتُطبَّع إلى الصيغة المعيارية `agent:<agentId>:<channel>:group:<id>`.
* مصادر أخرى:
  * مهام Cron: `cron:<job.id>`
  * Webhooks: `hook:<uuid>` (ما لم يُحدَّد صراحة بواسطة الخطاف)
  * تشغيل العُقد: `node-<nodeId>`

## دورة الحياة

* سياسة إعادة الضبط: تُعاد استخدام الجلسات حتى تنتهي صلاحيتها، ويُقيَّم الانتهاء عند الرسالة الواردة التالية.
* إعادة ضبط يومية: الافتراضي **الساعة 4:00 صباحًا بالتوقيت المحلي على مضيف Gateway**. تُعد الجلسة قديمة إذا كان آخر تحديث لها أقدم من أحدث وقت لإعادة الضبط اليومية.
* إعادة ضبط الخمول (اختياري): يضيف `idleMinutes` نافذة خمول منزلقة. عند تكوين كلٍ من إعادة الضبط اليومية والخمول، فإن **الأقرب انتهاءً** يفرض جلسة جديدة.
* الخمول فقط (قديم): إذا ضبطت `session.idleMinutes` دون أي تهيئة `session.reset`/`resetByType`، يبقى OpenClaw في وضع الخمول فقط للتوافق العكسي.
* تجاوزات حسب النوع (اختياري): يتيح `resetByType` تجاوز السياسة لأنواع الجلسات `direct` و`group` و`thread` (thread = سلاسل Slack/Discord، مواضيع Telegram، سلاسل Matrix عندما يوفّرها الموصل).
* تجاوزات حسب القناة (اختياري): يتجاوز `resetByChannel` سياسة إعادة الضبط لقناة ما (ينطبق على جميع أنواع الجلسات لتلك القناة ويتقدّم على `reset`/`resetByType`).
* محفزات إعادة الضبط: يؤدّي وجود `/new` أو `/reset` حرفيًا (بالإضافة إلى أي إضافات في `resetTriggers`) إلى بدء معرّف جلسة جديد وتمرير بقية الرسالة. يقبل `/new <model>` اسمًا مستعارًا للنموذج أو `provider/model` أو اسم الموفّر (مطابقة تقريبية) لتعيين نموذج الجلسة الجديدة. إذا أُرسِل `/new` أو `/reset` بمفرده، يُجري OpenClaw دورة تحية «مرحبًا» قصيرة لتأكيد إعادة الضبط.
* إعادة الضبط اليدوية: احذف مفاتيح محددة من المخزن أو أزل نص JSONL؛ تعيد الرسالة التالية إنشاءها.
* مهام Cron المعزولة تُنشئ دائمًا `sessionId` جديدًا لكل تشغيل (لا إعادة استخدام في الخمول).

## Send policy (اختياري)

حظر التسليم لأنواع جلسات محددة دون إدراج معرّفات فردية.

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  session: {
    sendPolicy: {
      rules: [
        { action: "deny", match: { channel: "discord", chatType: "group" } },
        { action: "deny", match: { keyPrefix: "cron:" } },
        // Match the raw session key (including the `agent:<id>:` prefix).
        { action: "deny", match: { rawKeyPrefix: "agent:main:discord:" } },
      ],
      default: "allow",
    },
  },
}
```

تجاوز وقت التشغيل (للمالك فقط):

* `/send on` → السماح لهذه الجلسة
* `/send off` → الرفض لهذه الجلسة
* `/send inherit` → مسح التجاوز واستخدام قواعد التهيئة
  أرسل هذه كرسائل مستقلة لكي تُسجَّل.

## التهيئة (مثال إعادة تسمية اختياري)

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
// ~/.openclaw/openclaw.json
{
  session: {
    scope: "per-sender", // keep group keys separate
    dmScope: "main", // DM continuity (set per-channel-peer/per-account-channel-peer for shared inboxes)
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      // Defaults: mode=daily, atHour=4 (gateway host local time).
      // If you also set idleMinutes, whichever expires first wins.
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    mainKey: "main",
  },
}
```

## الفحص

* `openclaw status` — يعرض مسار المخزن والجلسات الأخيرة.
* `openclaw sessions --json` — يفرغ كل إدخال (التصفية باستخدام `--active <minutes>`).
* `openclaw gateway call sessions.list --params '{}'` — يجلب الجلسات من Gateway العامل (استخدم `--url`/`--token` للوصول إلى Gateway بعيد).
* أرسل `/status` كرسالة مستقلة في الدردشة لمعرفة ما إذا كان الوكيل متاحًا، وكمية سياق الجلسة المستخدمة، ومفاتيح التفكير/الإسهاب الحالية، وموعد آخر تحديث لاعتمادات WhatsApp Web (يساعد على اكتشاف الحاجة لإعادة الربط).
* أرسل `/context list` أو `/context detail` لمعرفة ما الموجود في موجه النظام وملفات مساحة العمل المحقونة (وأكبر المساهمين في السياق).
* أرسل `/stop` كرسالة مستقلة لإيقاف التشغيل الحالي، ومسح المتابعات الموضوعة في الطابور لتلك الجلسة، وإيقاف أي تشغيلات لوكلاء فرعيين انبثقت منها (يتضمن الرد عدد الإيقافات).
* أرسل `/compact` (تعليمات اختيارية) كرسالة مستقلة لتلخيص السياق الأقدم وتحرير مساحة النافذة. انظر [/concepts/compaction](/concepts/compaction).
* يمكن فتح نصوص JSONL مباشرة لمراجعة الدورات كاملة.

## نصائح

* أبقِ المفتاح الرئيسي مخصصًا لحركة 1:1؛ ودَع المجموعات تحتفظ بمفاتيحها الخاصة.
* عند أتمتة التنظيف، احذف المفاتيح الفردية بدل المخزن كاملًا للحفاظ على السياق في أماكن أخرى.

## بيانات تعريف مصدر الجلسة

يسجّل كل إدخال جلسة مصدره (بأفضل جهد) في `origin`:

* `label`: تسمية بشرية (محلولة من تسمية المحادثة + موضوع المجموعة/القناة)
* `provider`: معرّف قناة مُطبَّع (بما في ذلك الامتدادات)
* `from`/`to`: معرّفات توجيه خام من الغلاف الوارد
* `accountId`: معرّف حساب الموفّر (عند تعدد الحسابات)
* `threadId`: معرّف السلسلة/الموضوع عندما تدعم القناة ذلك\
  تُملأ حقول المصدر للرسائل المباشرة والقنوات والمجموعات. إذا كان الموصل يحدّث توجيه التسليم فقط (على سبيل المثال، للحفاظ على حداثة الجلسة الرئيسية للرسائل المباشرة)، فيجب عليه مع ذلك توفير سياق وارد كي تحتفظ الجلسة ببياناتها التوضيحية. يمكن للامتدادات القيام بذلك بإرسال `ConversationLabel` و`GroupSubject` و`GroupChannel` و`GroupSpace` و`SenderName` في السياق الوارد واستدعاء `recordSessionMetaFromInbound` (أو تمرير السياق نفسه إلى `updateLastRoute`).