الرسائل النصية القصيرة

​

قبل البدء

• تثبيت Plugin الرسمي لرسائل SMS باستخدام openclaw plugins install @openclaw/sms.
• حساب Twilio يتضمن رقم هاتف يدعم SMS، أو Twilio Messaging Service.
• معرّف حساب Twilio ‏(Account SID) ورمز المصادقة (Auth Token).
• عنوان URL عام يستخدم HTTPS ويصل إلى Gateway الخاص بـ OpenClaw.
• اختيار سياسة للمرسل: pairing (الافتراضية) للاستخدام الخاص، أو allowlist لأرقام الهواتف المعتمدة مسبقًا، أو open فقط لإتاحة SMS للعامة عن قصد.

​

الإعداد السريع

openclaw plugins install @openclaw/sms

{
  channels: {
    sms: {
      enabled: true,
      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      authToken: "twilio-auth-token",
      fromNumber: "+15551234567",
      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
      dmPolicy: "pairing",
    },
  },
}

openclaw config patch --file ./sms.patch.json5 --dry-run
openclaw config patch --file ./sms.patch.json5

https://gateway.example.com/webhooks/sms

tailscale funnel --bg --set-path /webhooks/sms http://127.0.0.1:<gateway-port>/webhooks/sms
tailscale funnel status

openclaw gateway

openclaw pairing list sms
openclaw pairing approve sms <CODE>

​

أمثلة الضبط

​

ملف الضبط

{
  channels: {
    sms: {
      enabled: true,
      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      authToken: "twilio-auth-token",
      fromNumber: "+15551234567",
      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
      dmPolicy: "pairing",
    },
  },
}

​

متغيرات البيئة

export TWILIO_ACCOUNT_SID="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export TWILIO_AUTH_TOKEN="<twilio-auth-token>"
export TWILIO_PHONE_NUMBER="+15551234567"
export SMS_PUBLIC_WEBHOOK_URL="https://gateway.example.com/webhooks/sms"

{
  channels: {
    sms: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}

​

رمز مصادقة SecretRef

{
  channels: {
    sms: {
      enabled: true,
      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      authToken: { source: "env", provider: "default", id: "TWILIO_AUTH_TOKEN" },
      fromNumber: "+15551234567",
      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
      dmPolicy: "pairing",
    },
  },
}

​

مرسل Messaging Service

{
  channels: {
    sms: {
      enabled: true,
      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      authToken: "twilio-auth-token",
      messagingServiceSid: "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
      dmPolicy: "pairing",
    },
  },
}

​

الهدف الافتراضي للإرسال الصادر

{
  channels: {
    sms: {
      enabled: true,
      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      authToken: "twilio-auth-token",
      fromNumber: "+15551234567",
      defaultTo: "+15557654321",
      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
    },
  },
}

​

التحكم في الوصول

• pairing (الافتراضية): يحصل المرسلون غير المعروفين على رمز اقتران؛ اعتمدهم باستخدام openclaw pairing approve sms <CODE>.
• allowlist: لا تُعالج إلا رسائل المرسلين المدرجين في allowFrom. ترفض قائمة allowFrom الفارغة كل مرسل (يسجّل Gateway تحذيرًا عند بدء التشغيل).
• open: يتطلب التحقق من صحة الضبط أن تتضمن allowFrom القيمة "*". بدون حرف البدل، لا يمكن إلا للأرقام المدرجة إجراء محادثة.
• disabled: تُسقط جميع الرسائل المباشرة الواردة.

{
  channels: {
    sms: {
      enabled: true,
      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      authToken: "twilio-auth-token",
      fromNumber: "+15551234567",
      publicWebhookUrl: "https://gateway.example.com/webhooks/sms",
      dmPolicy: "allowlist",
      allowFrom: ["+15557654321"],
    },
  },
}

​

إرسال رسائل SMS

openclaw message send --channel sms --target sms:+15551234567 --message "hello"

openclaw message send --target twilio-sms:+15551234567 --message "hello"

​

التحقق من الإعداد

1. تأكد من أن سجل Gateway يعرض مسار Webhook الخاص بـ SMS.
2. شغّل فحصًا من جانب Twilio (يتحقق من عنوان URL وطريقة Webhook المهيأين في Twilio ومن أخطاء الوارد الحديثة):

openclaw channels capabilities --channel sms
openclaw channels status --channel sms --probe --json

3. أرسل رسالة SMS إلى رقم Twilio من هاتفك.
4. شغّل openclaw pairing list sms.
5. وافق على رمز الاقتران باستخدام openclaw pairing approve sms <CODE>.
6. أرسل رسالة SMS أخرى وتأكد من أن الوكيل يرد.

openclaw message send --channel sms --target sms:+15557654321 --message "اختبار OpenClaw SMS"

​

اختبار شامل من macOS iMessage/SMS

imsg send --to "+15551234567" --service sms --text "OpenClaw SMS E2E $(date -u +%Y%m%dT%H%M%SZ)" --json
openclaw pairing list sms
openclaw pairing approve sms <CODE>
imsg send --to "+15551234567" --service sms --text "reply exactly SMS pong" --json

​

أمان Webhook

• POST فقط.
• ميزانية للطلبات الفاشلة قدرها 300 طلب في الدقيقة لكل حساب SMS ومسار Webhook وعنوان عميل محلول. تُحتسب جميع الطلبات ضمن هذه الميزانية، لكن لا يُطبّق HTTP 429 إلا بعد فشل طلب في تحليل النص الأساسي أو التحقق من Twilio أو مطابقة AccountSid.
• حد لمعدل الاستدعاءات القابلة للإرسال قدره 30 استدعاءً مقبولًا في الدقيقة لكل حساب SMS ومسار Webhook وعنوان عميل محلول بعد اجتياز تلك الفحوصات (يُرجع HTTP 429 عند تجاوز ذلك). إذا كان التحقق من التوقيع معطّلًا، فإن حد 30/دقيقة هذا هو سقف الإرسال غير المصادق عليه.
• تُحل عناوين العملاء من خلال قواعد الوكيل الموثوق المشتركة في Gateway. إذا كان gateway.trustedProxies يتضمن الوكيل العكسي الذي يعيد توجيه استدعاءات Twilio، يستخدم OpenClaw عنوان العميل المُمرَّر لتحديد مفاتيح هذه الحدود؛ وإلا فيعود إلى عنوان المقبس المباشر.
• يجب أن يطابق AccountSid في الحمولة قيمة accountSid المهيأة (وإلا يُرجع HTTP 403).
• تُزال ازدواجية قيم MessageSid المعاد تشغيلها لمدة 10 دقائق.
• تحتفظ ذاكرة التخزين المؤقت لإعادة التشغيل في كل حساب SMS بما يصل إلى 10,000 من معرّفات SID الحية للرسائل. عندما تكون جميع الخانات حية، تفشل Webhooks الجديدة لذلك الحساب بصورة مغلقة مع HTTP 429 وترويسة Retry-After حتى انتهاء صلاحية أقدم خانة.
• تُرفض النصوص الأساسية للطلبات التي تتجاوز 32 KB.

{
  channels: {
    sms: {
      dangerouslyDisableSignatureValidation: true,
    },
  },
}

​

تهيئة حسابات متعددة

{
  channels: {
    sms: {
      accounts: {
        support: {
          enabled: true,
          accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          authToken: "twilio-auth-token",
          fromNumber: "+15551234567",
          publicWebhookUrl: "https://gateway.example.com/webhooks/sms/support",
          webhookPath: "/webhooks/sms/support",
          dmPolicy: "allowlist",
          allowFrom: ["+15557654321"],
        },
      },
    },
  },
}

​

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

​

يُرجع Twilio الخطأ 403 أو يرفض OpenClaw الـ Webhook

​

لا يظهر طلب اقتران

• يشير Twilio Messaging > A message comes in إلى publicWebhookUrl.
• الطريقة هي POST.
• يكشف النفق أو الوكيل العكسي webhookPath الدقيق؛ بالنسبة إلى Tailscale Funnel، شغّل tailscale funnel status وتأكد من إدراج /webhooks/sms.
• يستخدم publicWebhookUrl المخطط والمضيف والمسار وسلسلة الاستعلام نفسها التي يرسلها Twilio، بحيث يمكن للتحقق من التوقيع إعادة إنتاج عنوان URL الموقّع.

​

تفشل عمليات الإرسال الصادرة

​

تصل الرسائل لكن الوكيل لا يجيب