Signal

​

المتطلبات الأساسية

• تثبيت OpenClaw على خادمك (تم اختبار مسار Linux أدناه على Ubuntu 24).
• واحد مما يلي:
  • توفر signal-cli على المضيف (الوضع الأصلي)، أو
  • حاوية Docker باسم bbernhard/signal-cli-rest-api (وضع الحاوية).
• رقم هاتف يمكنه تلقي رسالة SMS واحدة للتحقق (لمسار التسجيل عبر SMS).
• وصول عبر المتصفح لكابتشا Signal (signalcaptchas.org) أثناء التسجيل.

​

الإعداد السريع (للمبتدئين)

1. استخدم رقم Signal منفصلا للبوت (موصى به).
2. ثبّت Plugin الخاص بـ OpenClaw:

openclaw plugins install @openclaw/signal

3. ثبّت signal-cli (يتطلب Java إذا استخدمت بناء JVM).
4. اختر مسار إعداد واحدا:
   • المسار أ (ربط QR): signal-cli link -n "OpenClaw" ثم امسح الرمز باستخدام Signal.
   • المسار ب (تسجيل SMS): سجّل رقما مخصصا باستخدام كابتشا + تحقق SMS.
5. اضبط OpenClaw وأعد تشغيل Gateway.
6. أرسل رسالة خاصة أولى ووافق على الاقتران (openclaw pairing approve signal <CODE>).

{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      cliPath: "signal-cli",
      dmPolicy: "pairing",
      allowFrom: ["+15557654321"],
    },
  },
}

​

ما هو

• قناة Signal عبر signal-cli (وليس libsignal مضمن).
• توجيه حتمي: تعود الردود دائما إلى Signal.
• تشارك الرسائل الخاصة جلسة الوكيل الرئيسية؛ المجموعات معزولة (agent:<agentId>:signal:group:<groupId>).

​

عمليات كتابة الإعدادات

{
  channels: { signal: { configWrites: false } },
}

​

نموذج الرقم (مهم)

• يتصل Gateway بـ جهاز Signal (حساب signal-cli).
• إذا شغّلت البوت على حساب Signal الشخصي الخاص بك، فسيتجاهل رسائلك أنت (حماية من الحلقة).
• من أجل “أراسل البوت فيرد”، استخدم رقم بوت منفصلا.

​

مسار الإعداد أ: ربط حساب Signal موجود (QR)

1. ثبّت signal-cli (بناء JVM أو البناء الأصلي).
2. اربط حساب بوت:
   • signal-cli link -n "OpenClaw" ثم امسح رمز QR في Signal.
3. اضبط Signal وابدأ Gateway.

{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      cliPath: "signal-cli",
      dmPolicy: "pairing",
      allowFrom: ["+15557654321"],
    },
  },
}

​

مسار الإعداد ب: تسجيل رقم بوت مخصص (SMS، Linux)

1. احصل على رقم يمكنه تلقي SMS (أو تحقق صوتي للخطوط الأرضية).
   • استخدم رقم بوت مخصصا لتجنب تعارضات الحساب/الجلسة.
2. ثبّت signal-cli على مضيف Gateway:

VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//')
curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux-native.tar.gz"
sudo tar xf "signal-cli-${VERSION}-Linux-native.tar.gz" -C /opt
sudo ln -sf /opt/signal-cli /usr/local/bin/
signal-cli --version

3. سجّل الرقم وتحقق منه:

signal-cli -a +<BOT_PHONE_NUMBER> register

1. افتح https://signalcaptchas.org/registration/generate.html.
2. أكمل الكابتشا، وانسخ هدف الرابط signalcaptcha://... من “Open Signal”.
3. شغّل الأمر من عنوان IP الخارجي نفسه لجلسة المتصفح عندما يكون ذلك ممكنا.
4. شغّل التسجيل مرة أخرى فورا (تنتهي صلاحية رموز الكابتشا بسرعة):

signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>

4. اضبط OpenClaw، وأعد تشغيل Gateway، وتحقق من القناة:

# If you run the gateway as a user systemd service:
systemctl --user restart openclaw-gateway.service

# Then verify:
openclaw doctor
openclaw channels status --probe

5. اقرن مرسل الرسائل الخاصة لديك:
   • أرسل أي رسالة إلى رقم البوت.
   • وافق على الرمز على الخادم: openclaw pairing approve signal <PAIRING_CODE>.
   • احفظ رقم البوت كجهة اتصال على هاتفك لتجنب “Unknown contact”.

• README الخاص بـ signal-cli: https://github.com/AsamK/signal-cli
• تدفق الكابتشا: https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
• تدفق الربط: https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

​

وضع العفريت الخارجي (httpUrl)

{
  channels: {
    signal: {
      httpUrl: "http://127.0.0.1:8080",
      autoStart: false,
    },
  },
}

​

وضع الحاوية (bbernhard/signal-cli-rest-api)

• يجب تشغيل الحاوية باستخدام MODE=json-rpc لتلقي الرسائل في الوقت الفعلي.
• سجّل حساب Signal الخاص بك أو اربطه داخل الحاوية قبل توصيل OpenClaw.

signal-cli:
  image: bbernhard/signal-cli-rest-api:latest
  environment:
    MODE: json-rpc
  ports:
    - "8080:8080"
  volumes:
    - signal-cli-data:/home/.local/share/signal-cli

{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      httpUrl: "http://signal-cli:8080",
      autoStart: false,
      apiMode: "container", // or "auto" to detect automatically
    },
  },
}

• استخدم autoStart: false مع وضع الحاوية. يجب ألا يشغّل OpenClaw عفريتا أصليا عند اختيار apiMode: "container".
• استخدم MODE=json-rpc للتلقي. قد يجعل MODE=normal المسار /v1/about يبدو سليما، لكن /v1/receive/{account} لا يترقى إلى WebSocket، لذلك لن يختار OpenClaw بث تلقي الحاوية في وضع auto.
• اضبط apiMode: "container" عندما تعلم أن httpUrl يشير إلى REST API الخاص بـ bbernhard. اضبط apiMode: "native" عندما تعلم أنه يشير إلى JSON-RPC/SSE الأصلي لـ signal-cli. استخدم "auto" عندما قد يختلف النشر.
• تلتزم تنزيلات مرفقات الحاوية بحدود بايتات الوسائط نفسها في الوضع الأصلي. يتم رفض الاستجابات الأكبر من الحد قبل تخزينها مؤقتا بالكامل عندما يرسل الخادم Content-Length، وإلا أثناء البث.

​

التحكم في الوصول (الرسائل الخاصة + المجموعات)

• الافتراضي: channels.signal.dmPolicy = "pairing".
• يتلقى المرسلون غير المعروفين رمز اقتران؛ يتم تجاهل الرسائل حتى تتم الموافقة عليها (تنتهي صلاحية الرموز بعد ساعة واحدة).
• الموافقة عبر:
  • openclaw pairing list signal
  • openclaw pairing approve signal <CODE>
• الاقتران هو تبادل الرمز الافتراضي لرسائل Signal الخاصة. التفاصيل: الاقتران
• يتم تخزين المرسلين ذوي UUID فقط (من sourceUuid) كـ uuid:<id> في channels.signal.allowFrom.

• channels.signal.groupPolicy = open | allowlist | disabled.
• يتحكم channels.signal.groupAllowFrom في المجموعات أو المرسلين الذين يمكنهم تشغيل ردود المجموعات عند تعيين allowlist؛ يمكن أن تكون الإدخالات معرفات مجموعات Signal (خام، أو group:<id>، أو signal:group:<id>)، أو أرقام هواتف المرسلين، أو قيم uuid:<id>، أو *.
• يمكن لـ channels.signal.groups["<group-id>" | "*"] تجاوز سلوك المجموعة باستخدام requireMention وtools وtoolsBySender.
• استخدم channels.signal.accounts.<id>.groups لتجاوزات كل حساب في إعدادات الحسابات المتعددة.
• لا يؤدي السماح لمجموعة Signal عبر groupAllowFrom إلى تعطيل بوابة الإشارة إليها بحد ذاته. يعالج إدخال channels.signal.groups["<group-id>"] المكوّن تحديدا كل رسالة مجموعة ما لم يتم تعيين requireMention=true.
• ملاحظة وقت التشغيل: إذا كان channels.signal مفقودا بالكامل، يعود وقت التشغيل إلى groupPolicy="allowlist" لفحوصات المجموعة (حتى إذا تم تعيين channels.defaults.groupPolicy).

​

كيف يعمل (السلوك)

• الوضع الأصلي: يعمل signal-cli كعفريت؛ يقرأ Gateway الأحداث عبر SSE.
• وضع الحاوية: يرسل Gateway عبر REST API ويتلقى عبر WebSocket.
• يتم تطبيع الرسائل الواردة إلى غلاف القناة المشترك.
• تعود الردود دائما إلى الرقم أو المجموعة نفسها.

​

الوسائط + الحدود

• يتم تقسيم النص الصادر إلى channels.signal.textChunkLimit (الافتراضي 4000).
• تقسيم اختياري حسب الأسطر الجديدة: اضبط channels.signal.chunkMode="newline" للتقسيم عند الأسطر الفارغة (حدود الفقرات) قبل التقسيم حسب الطول.
• المرفقات مدعومة (يتم جلب base64 من signal-cli).
• تستخدم مرفقات الملاحظات الصوتية اسم ملف signal-cli كبديل MIME عند فقدان contentType، بحيث يظل بإمكان نسخ الصوت تصنيف مذكرات AAC الصوتية.
• حد الوسائط الافتراضي: channels.signal.mediaMaxMb (الافتراضي 8).
• استخدم channels.signal.ignoreAttachments لتخطي تنزيل الوسائط.
• يستخدم سياق سجل المجموعة channels.signal.historyLimit (أو channels.signal.accounts.*.historyLimit)، مع الرجوع إلى messages.groupChat.historyLimit. عيّن 0 للتعطيل (الافتراضي 50).

​

الكتابة + إيصالات القراءة

• مؤشرات الكتابة: يرسل OpenClaw إشارات الكتابة عبر signal-cli sendTyping ويحدّثها أثناء تشغيل الرد.
• إيصالات القراءة: عندما تكون channels.signal.sendReadReceipts مفعّلة، يمرّر OpenClaw إيصالات القراءة للرسائل المباشرة المسموح بها.
• لا يوفّر Signal-cli إيصالات قراءة للمجموعات.

​

تفاعلات حالة دورة الحياة

​

التفاعلات (أداة الرسائل)

• استخدم message action=react مع channel=signal.
• الأهداف: المرسل بصيغة E.164 أو UUID (استخدم uuid:<id> من مخرجات الاقتران؛ يعمل UUID العاري أيضا).
• messageId هو الطابع الزمني في Signal للرسالة التي تتفاعل معها.
• تتطلب تفاعلات المجموعات targetAuthor أو targetAuthorUuid.

message action=react channel=signal target=uuid:123e4567-e89b-12d3-a456-426614174000 messageId=1737630212345 emoji=🔥
message action=react channel=signal target=+15551234567 messageId=1737630212345 emoji=🔥 remove=true
message action=react channel=signal target=signal:group:<groupId> targetAuthor=uuid:<sender-uuid> messageId=1737630212345 emoji=✅

• channels.signal.actions.reactions: تفعيل/تعطيل إجراءات التفاعل (القيمة الافتراضية true).
• channels.signal.reactionLevel: off | ack | minimal | extensive.
  • يعطل off/ack تفاعلات الوكيل (ستفشل أداة الرسائل react بخطأ).
  • يفعّل minimal/extensive تفاعلات الوكيل ويضبط مستوى الإرشاد.
• تجاوزات لكل حساب: channels.signal.accounts.<id>.actions.reactions، channels.signal.accounts.<id>.reactionLevel.

​

تفاعلات الموافقة

• 👍 يوافق مرة واحدة.
• 👎 يرفض.
• استخدم /approve <id> allow-always عندما يقدّم الطلب موافقة دائمة.

​

أهداف التسليم (CLI/Cron)

• الرسائل المباشرة: signal:+15551234567 (أو E.164 عادي).
• رسائل UUID المباشرة: uuid:<id> (أو UUID عار).
• المجموعات: signal:group:<groupId>.
• أسماء المستخدمين: username:<name> (إذا كان حساب Signal لديك يدعم ذلك).

​

الأسماء المستعارة

{
  channels: {
    signal: {
      aliases: {
        me: "+15557654321",
        jane: "uuid:123e4567-e89b-12d3-a456-426614174000",
        ops: "group:<groupId>",
      },
      defaultTo: "signal:me",
    },
  },
}

openclaw message send --channel signal --target signal:ops --message "Deployment is complete"

{
  channels: {
    signal: {
      aliases: {
        me: "+15557654321",
      },
      accounts: {
        work: {
          aliases: {
            ops: "group:<workGroupId>",
          },
        },
      },
    },
  },
}

​

استكشاف الأخطاء وإصلاحها

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

openclaw pairing list signal

• يمكن الوصول إلى الخدمة الخفية لكن لا توجد ردود: تحقق من إعدادات الحساب/الخدمة الخفية (httpUrl، account) ووضع الاستلام.
• تم تجاهل الرسائل المباشرة: المرسل ينتظر موافقة الاقتران.
• تم تجاهل رسائل المجموعة: تمنع بوابات مرسل المجموعة/الإشارة التسليم.
• أخطاء التحقق من الإعدادات بعد التعديلات: شغّل openclaw doctor --fix.
• Signal غير موجود في التشخيصات: تأكد من channels.signal.enabled: true.

openclaw pairing list signal
pgrep -af signal-cli
grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20

​

ملاحظات الأمان

• يخزن signal-cli مفاتيح الحساب محليا (عادة في ~/.local/share/signal-cli/data/).
• انسخ حالة حساب Signal احتياطيا قبل ترحيل الخادم أو إعادة بنائه.
• أبق channels.signal.dmPolicy: "pairing" ما لم تكن تريد صراحة وصولا أوسع للرسائل المباشرة.
• لا يلزم التحقق عبر SMS إلا لتدفقات التسجيل أو الاسترداد، لكن فقدان التحكم في الرقم/الحساب قد يعقّد إعادة التسجيل.

​

مرجع الإعدادات (Signal)

• channels.signal.enabled: تفعيل/تعطيل بدء تشغيل القناة.
• channels.signal.apiMode: auto | native | container (الافتراضي: auto). راجع وضع الحاوية.
• channels.signal.account: E.164 لحساب الروبوت.
• channels.signal.cliPath: المسار إلى signal-cli.
• channels.signal.configPath: دليل signal-cli --config اختياري.
• channels.signal.httpUrl: عنوان URL كامل للخدمة الخفية (يتجاوز المضيف/المنفذ).
• channels.signal.httpHost، channels.signal.httpPort: ربط الخدمة الخفية (الافتراضي 127.0.0.1:8080).
• channels.signal.autoStart: تشغيل الخدمة الخفية تلقائيا (الافتراضي true إذا لم يتم ضبط httpUrl).
• channels.signal.startupTimeoutMs: مهلة انتظار بدء التشغيل بالمللي ثانية (الحد الأقصى 120000).
• channels.signal.receiveMode: on-start | manual.
• channels.signal.ignoreAttachments: تخطي تنزيلات المرفقات.
• channels.signal.ignoreStories: تجاهل القصص من الخدمة الخفية.
• channels.signal.sendReadReceipts: تمرير إيصالات القراءة.
• channels.signal.dmPolicy: pairing | allowlist | open | disabled (الافتراضي: pairing).
• channels.signal.allowFrom: قائمة سماح للرسائل المباشرة (E.164 أو uuid:<id>). يتطلب open القيمة "*". لا يملك Signal أسماء مستخدمين؛ استخدم معرّفات الهاتف/UUID.
• channels.signal.aliases: أسماء مستعارة من جهة OpenClaw لأهداف تسليم الرسائل المباشرة أو المجموعات.
• channels.signal.groupPolicy: open | allowlist | disabled (الافتراضي: allowlist).
• channels.signal.groupAllowFrom: قائمة سماح للمجموعات؛ تقبل معرّفات مجموعات Signal (خام، أو group:<id>، أو signal:group:<id>)، أو أرقام المرسل بصيغة E.164، أو قيم uuid:<id>.
• channels.signal.groups: تجاوزات لكل مجموعة مفهرسة بمعرّف مجموعة Signal (أو "*"). الحقول المدعومة: requireMention، tools، toolsBySender.
• channels.signal.accounts.<id>.groups: نسخة لكل حساب من channels.signal.groups لإعدادات متعددة الحسابات.
• channels.signal.accounts.<id>.aliases: أسماء مستعارة لكل حساب، مدمجة مع الأسماء المستعارة العليا.
• channels.signal.historyLimit: الحد الأقصى لرسائل المجموعة التي ستضمّن كسياق (0 يعطّلها).
• channels.signal.dmHistoryLimit: حد محفوظات الرسائل المباشرة بأدوار المستخدم. تجاوزات لكل مستخدم: channels.signal.dms["<phone_or_uuid>"].historyLimit.
• channels.signal.textChunkLimit: حجم الجزء الصادر (بالحروف).
• channels.signal.chunkMode: length (الافتراضي) أو newline للتقسيم عند الأسطر الفارغة (حدود الفقرات) قبل التقسيم حسب الطول.
• channels.signal.mediaMaxMb: حد الوسائط الواردة/الصادرة (MB).

• agents.list[].groupChat.mentionPatterns (لا يدعم Signal الإشارات الأصلية).
• messages.groupChat.mentionPatterns (بديل عام).
• messages.responsePrefix.

​

ذات صلة

• نظرة عامة على القنوات — كل القنوات المدعومة
• الاقتران — مصادقة الرسائل المباشرة وتدفق الاقتران
• المجموعات — سلوك محادثة المجموعة وبوابات الإشارة
• توجيه القنوات — توجيه الجلسات للرسائل
• الأمان — نموذج الوصول والتقوية