Signal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

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

​

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

1. استخدم رقم Signal منفصلا للبوت (موصى به).
2. ثبّت signal-cli (يتطلب Java إذا كنت تستخدم إصدار JVM).
3. اختر مسار إعداد واحدا:
   • المسار A (ربط QR): signal-cli link -n "OpenClaw" ثم امسح الرمز باستخدام Signal.
   • المسار B (تسجيل SMS): سجّل رقما مخصصا باستخدام captcha + تحقق SMS.
4. اضبط OpenClaw وأعد تشغيل Gateway.
5. أرسل رسالة مباشرة أولى ووافق على الاقتران (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 الشخصي لديك، فسيتجاهل رسائلك أنت (حماية من الحلقات).
• من أجل “أراسل البوت فيرد”، استخدم رقم بوت منفصلا.

​

مسار الإعداد A: ربط حساب 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"],
    },
  },
}

​

مسار الإعداد B: تسجيل رقم بوت مخصص (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. أكمل captcha، وانسخ هدف رابط signalcaptcha://... من “فتح Signal”.
3. شغّل من عنوان IP الخارجي نفسه لجلسة المتصفح عندما يكون ذلك ممكنا.
4. شغّل التسجيل مرة أخرى فورا (تنتهي صلاحية رموز captcha بسرعة):

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>.
   • احفظ رقم البوت كجهة اتصال على هاتفك لتجنب “جهة اتصال غير معروفة”.

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

​

وضع daemon الخارجي (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 daemon أصليا عند اختيار 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 كـ daemon؛ يقرأ 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.

​

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

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

​

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

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.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.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.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.

​

ذات صلة

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