SMS

OpenClaw می‌تواند از طریق یک شماره تلفن Twilio یا Messaging Service، SMS دریافت و ارسال کند. Gateway یک مسیر Webhook ورودی ثبت می‌کند، به‌صورت پیش‌فرض امضاهای درخواست Twilio را اعتبارسنجی می‌کند، و پاسخ‌ها را از طریق Messages API مربوط به Twilio برمی‌گرداند.

پیش از شروع

نیاز دارید به:

• Plugin رسمی SMS که با openclaw plugins install @openclaw/sms نصب شده باشد.
• یک حساب Twilio با شماره تلفنی که قابلیت SMS دارد، یا یک Twilio Messaging Service.
• Twilio Account SID و Auth Token.
• یک URL عمومی HTTPS که به OpenClaw Gateway شما برسد.
• انتخاب سیاست فرستنده: pairing برای استفاده خصوصی، allowlist برای شماره تلفن‌های از پیش تأییدشده، یا open فقط برای دسترسی SMS عمداً عمومی.

اگر شماره هر دو قابلیت SMS و تماس صوتی را دارد، از یک شماره Twilio برای هر دو استفاده کنید. Webhook مربوط به SMS و Webhook مربوط به تماس صوتی را جداگانه در Twilio پیکربندی کنید؛ این صفحه فقط Webhook مربوط به 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-runopenclaw 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/smstailscale funnel status

openclaw gateway

openclaw pairing list smsopenclaw pairing approve sms <CODE>

نمونه‌های پیکربندی

فایل پیکربندی

وقتی می‌خواهید تعریف کانال همراه پیکربندی Gateway منتقل شود، از راه‌اندازی با فایل پیکربندی استفاده کنید:

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

متغیرهای محیطی

برای استقرارهای تک‌حسابی که secretها از محیط میزبان می‌آیند، از راه‌اندازی با env استفاده کنید:

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",    },  },}

TWILIO_SMS_FROM به‌عنوان نام مستعار برای TWILIO_PHONE_NUMBER پذیرفته می‌شود. وقتی Twilio باید فرستنده را از یک Messaging Service انتخاب کند، به‌جای فرستنده شماره تلفنی از TWILIO_MESSAGING_SERVICE_SID استفاده کنید.

توکن احراز هویت SecretRef

authToken می‌تواند یک SecretRef باشد. وقتی Gateway باید Twilio Auth Token را به‌جای ذخیره کردن پیکربندی متن ساده، از runtime مربوط به secretهای OpenClaw resolve کند، از این روش استفاده کنید:

{  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",    },  },}

متغیر محیطی ارجاع‌شده یا ارائه‌دهنده secret باید برای Gateway runtime قابل مشاهده باشد. پس از تغییر متغیرهای محیطی میزبان، فرایندهای Gateway مدیریت‌شده را راه‌اندازی مجدد کنید.

شماره خصوصی فقط با allowlist

وقتی فقط شماره تلفن‌های شناخته‌شده باید بتوانند با agent صحبت کنند، از allowlist استفاده کنید:

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

فرستنده Messaging Service

وقتی Twilio باید فرستنده را از طریق یک Messaging Service انتخاب کند، به‌جای fromNumber از messagingServiceSid استفاده کنید:

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

اگر پس از resolve شدن پیکربندی و env هر دو fromNumber و messagingServiceSid وجود داشته باشند، از fromNumber استفاده می‌شود.

مقصد خروجی پیش‌فرض

وقتی automation یا ارسال آغازشده توسط agent باید در صورتی که جریان ارسال هدف صریحی را حذف کند، مقصد پیش‌فرض داشته باشد، defaultTo را تنظیم کنید:

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

کنترل دسترسی

channels.sms.dmPolicy دسترسی مستقیم SMS را کنترل می‌کند:

• pairing (پیش‌فرض)
• allowlist (به حداقل یک فرستنده در allowFrom نیاز دارد)
• open (نیاز دارد allowFrom شامل "*" باشد)
• disabled

ورودی‌های allowFrom باید شماره تلفن‌های E.164 مانند +15551234567 باشند. پیشوندهای sms: پذیرفته و normalize می‌شوند. برای یک دستیار خصوصی، dmPolicy: "allowlist" را با شماره تلفن‌های صریح ترجیح دهید.

ارسال SMS

هدف‌های SMS خروجی از پیشوند سرویس sms: همراه با انتخاب کانال SMS استفاده می‌کنند:

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

وقتی انتخاب کانال ضمنی باشد، twilio-sms:+15551234567 این کانال را بدون در اختیار گرفتن پیشوند سرویس sms: که مالک آن کانال موجود و مورد استفاده iMessage است، انتخاب می‌کند.

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

CLI به یک --target صریح نیاز دارد. defaultTo برای مسیرهای automation و ارسال آغازشده توسط agent است، جایی که هدف می‌تواند از پیکربندی کانال resolve شود.

پاسخ‌های agent از گفتگوهای SMS ورودی به‌صورت خودکار از طریق فرستنده Twilio پیکربندی‌شده به فرستنده برمی‌گردند.

خروجی SMS متن ساده است. OpenClaw markdown را حذف می‌کند، بلوک‌های کد fence‌شده را تخت می‌کند، لینک‌های خوانا را حفظ می‌کند، و پاسخ‌های طولانی را پیش از ارسال از طریق Twilio به قطعه‌های کوچک تقسیم می‌کند.

تأیید راه‌اندازی

پس از شروع Gateway:

1. تأیید کنید log مربوط به Gateway مسیر Webhook پیامکی را نشان می‌دهد.
2. یک probe سمت Twilio اجرا کنید:

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

3. از تلفن خود یک SMS به شماره Twilio بفرستید.
4. openclaw pairing list sms را اجرا کنید.
5. کد pairing را با openclaw pairing approve sms <CODE> تأیید کنید.
6. یک SMS دیگر بفرستید و تأیید کنید agent پاسخ می‌دهد.

برای آزمایش فقط خروجی، از این استفاده کنید:

openclaw message send --channel sms --target sms:+15557654321 --message "OpenClaw SMS test"

آزمایش انتهابه‌انتها از macOS iMessage/SMS

روی Mac که می‌تواند از طریق Messages، SMS اپراتوری ارسال کند، می‌توانید از imsg برای هدایت سمت فرستنده بدون دست زدن به تلفن خود استفاده کنید:

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

پیام اول باید یک درخواست pairing ایجاد کند. پیام دوم باید پاسخ agent را از طریق Twilio دریافت کند.

امنیت Webhook

به‌صورت پیش‌فرض، OpenClaw با استفاده از publicWebhookUrl و authToken، X-Twilio-Signature را اعتبارسنجی می‌کند. publicWebhookUrl را از نظر بایت‌به‌بایت با URL پیکربندی‌شده در Twilio، شامل scheme، host، path و query string، هم‌راستا نگه دارید.

فقط برای آزمایش تونل محلی، می‌توانید این را تنظیم کنید:

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

از اعتبارسنجی امضای غیرفعال‌شده روی Gateway عمومی استفاده نکنید.

پیکربندی چندحسابی

وقتی بیش از یک شماره Twilio را اداره می‌کنید، از accounts استفاده کنید:

{  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"],        },      },    },  },}

هر حساب باید از یک webhookPath متمایز استفاده کند.

عیب‌یابی

Twilio مقدار 403 برمی‌گرداند یا OpenClaw، Webhook را رد می‌کند

بررسی کنید publicWebhookUrl دقیقاً با URL پیکربندی‌شده در Twilio، شامل scheme، host، path و query string، مطابقت داشته باشد. Twilio رشته URL عمومی را امضا می‌کند، بنابراین بازنویسی‌های proxy و hostnameهای جایگزین می‌توانند اعتبارسنجی امضا را خراب کنند.

هیچ درخواست pairing ظاهر نمی‌شود

URL و روش Webhook مربوط به Messaging برای شماره Twilio را بررسی کنید. باید به URL Webhook پیامکی اشاره کند و از POST استفاده کند. همچنین تأیید کنید Gateway از اینترنت عمومی یا از طریق تونل شما قابل دسترسی است.

اگر log پیام Twilio خطای 11200 را نشان می‌دهد، Twilio پیام SMS ورودی را پذیرفته اما نتوانسته به Webhook شما برسد. بررسی کنید:

• Messaging > A message comes in در Twilio به publicWebhookUrl اشاره کند.
• روش POST باشد.
• تونل یا reverse proxy همان webhookPath دقیق را در معرض دسترس قرار دهد؛ برای Tailscale Funnel، tailscale funnel status را اجرا کنید و تأیید کنید /webhooks/sms فهرست شده است.
• publicWebhookUrl از همان scheme، host، path و query string استفاده کند که Twilio ارسال می‌کند، تا اعتبارسنجی امضا بتواند URL امضاشده را بازتولید کند.

ارسال‌های خروجی ناموفق‌اند

تأیید کنید accountSid، authToken، و یکی از fromNumber یا messagingServiceSid resolve شده‌اند. اگر از حساب آزمایشی Twilio استفاده می‌کنید، ممکن است شماره مقصد پیش از ارسال SMS خروجی نیاز به تأیید در Twilio داشته باشد.

پیام‌ها می‌رسند اما agent پاسخ نمی‌دهد

dmPolicy و allowFrom را بررسی کنید. با سیاست پیش‌فرض pairing، فرستنده باید پیش از پردازش نوبت‌های عادی عامل تأیید شده باشد.