Synology Chat

وضعیت: کانال پیام مستقیم Plugin بسته‌بندی‌شده با استفاده از Webhookهای Synology Chat. این Plugin پیام‌های ورودی را از Webhookهای خروجی Synology Chat می‌پذیرد و پاسخ‌ها را از طریق یک Webhook ورودی Synology Chat ارسال می‌کند.

# Plugin بسته‌بندی‌شده

Synology Chat در نسخه‌های فعلی OpenClaw به‌صورت یک Plugin بسته‌بندی‌شده ارائه می‌شود، بنابراین بیلدهای بسته‌بندی‌شدهٔ معمولی به نصب جداگانه نیاز ندارند.

اگر روی یک بیلد قدیمی‌تر هستید یا نصب سفارشی‌ای دارید که Synology Chat را شامل نمی‌شود، آن را به‌صورت دستی نصب کنید:

نصب از یک checkout محلی:

openclaw plugins install ./path/to/local/synology-chat-plugin

جزئیات: Plugins

# راه‌اندازی سریع

1. مطمئن شوید Plugin مربوط به Synology Chat در دسترس است.
   • نسخه‌های بسته‌بندی‌شدهٔ فعلی OpenClaw از قبل آن را همراه دارند.
   • نصب‌های قدیمی‌تر/سفارشی می‌توانند آن را با دستور بالا، به‌صورت دستی از یک checkout منبع اضافه کنند.
   • openclaw onboard اکنون Synology Chat را در همان فهرست راه‌اندازی کانال نشان می‌دهد که openclaw channels add نشان می‌دهد.
   • راه‌اندازی غیرتعاملی: openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>
2. در یکپارچه‌سازی‌های Synology Chat:
   • یک Webhook ورودی بسازید و URL آن را کپی کنید.
   • یک Webhook خروجی با توکن محرمانهٔ خود بسازید.
3. URL مربوط به Webhook خروجی را به Gateway مربوط به OpenClaw هدایت کنید:
   • به‌طور پیش‌فرض https://gateway-host/webhook/synology.
   • یا channels.synology-chat.webhookPath سفارشی شما.
4. راه‌اندازی را در OpenClaw کامل کنید.
   • راهنمایی‌شده: openclaw onboard
   • مستقیم: openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>
5. Gateway را بازراه‌اندازی کنید و یک DM به ربات Synology Chat بفرستید.

جزئیات احراز هویت Webhook:

• OpenClaw توکن Webhook خروجی را ابتدا از body.token، سپس از ?token=...، و سپس از headerها می‌پذیرد.
• قالب‌های header پذیرفته‌شده:
  • x-synology-token
  • x-webhook-token
  • x-openclaw-token
  • Authorization: Bearer <token>
• توکن‌های خالی یا موجود نبودن توکن، به‌صورت fail-closed رد می‌شوند.

پیکربندی حداقلی:

{
  channels: {
    "synology-chat": {
      enabled: true,
      token: "synology-outgoing-token",
      incomingUrl: "https://nas.example.com/webapi/entry.cgi?api=SYNO.Chat.External&method=incoming&version=2&token=...",
      webhookPath: "/webhook/synology",
      dmPolicy: "allowlist",
      allowedUserIds: ["123456"],
      rateLimitPerMinute: 30,
      allowInsecureSsl: false,
    },
  },
}

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

برای حساب پیش‌فرض، می‌توانید از env varها استفاده کنید:

• SYNOLOGY_CHAT_TOKEN
• SYNOLOGY_CHAT_INCOMING_URL
• SYNOLOGY_NAS_HOST
• SYNOLOGY_ALLOWED_USER_IDS (جداشده با ویرگول)
• SYNOLOGY_RATE_LIMIT
• OPENCLAW_BOT_NAME

مقادیر پیکربندی بر env varها ارجحیت دارند.

SYNOLOGY_CHAT_INCOMING_URL را نمی‌توان از یک .env مربوط به workspace تنظیم کرد؛ فایل‌های .env مربوط به Workspace را ببینید.

# سیاست DM و کنترل دسترسی

• dmPolicy: "allowlist" پیش‌فرض پیشنهادی است.
• allowedUserIds فهرستی (یا رشته‌ای جداشده با ویرگول) از شناسه‌های کاربر Synology را می‌پذیرد.
• در حالت allowlist، فهرست خالی allowedUserIds به‌عنوان پیکربندی نادرست در نظر گرفته می‌شود و مسیر Webhook شروع نمی‌شود (برای اجازه‌دادن به همه، از dmPolicy: "open" همراه با allowedUserIds: ["*"] استفاده کنید).
• dmPolicy: "open" فقط وقتی allowedUserIds شامل "*" باشد DMهای عمومی را مجاز می‌کند؛ با ورودی‌های محدودکننده، فقط کاربران منطبق می‌توانند گفتگو کنند.
• dmPolicy: "disabled" DMها را مسدود می‌کند.
• اتصال گیرندهٔ پاسخ به‌طور پیش‌فرض روی user_id عددی پایدار باقی می‌ماند. channels.synology-chat.dangerouslyAllowNameMatching: true حالت سازگاری اضطراری است که جستجوی نام کاربری/نام مستعار قابل‌تغییر را برای تحویل پاسخ دوباره فعال می‌کند.
• تأییدهای pairing با موارد زیر کار می‌کنند:
  • openclaw pairing list synology-chat
  • openclaw pairing approve synology-chat <CODE>

# تحویل خروجی

از شناسه‌های عددی کاربران Synology Chat به‌عنوان هدف استفاده کنید.

نمونه‌ها:

openclaw message send --channel synology-chat --target 123456 --text "Hello from OpenClaw"
openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again"
openclaw message send --channel synology-chat --target synology:123456 --text "Short prefix"

ارسال رسانه از طریق تحویل فایل مبتنی بر URL پشتیبانی می‌شود. URLهای فایل خروجی باید از http یا https استفاده کنند، و اهداف شبکه‌ای خصوصی یا به‌نحوی مسدودشده پیش از آنکه OpenClaw URL را به Webhook مربوط به NAS ارسال کند رد می‌شوند.

# چندحسابی

چندین حساب Synology Chat زیر channels.synology-chat.accounts پشتیبانی می‌شوند. هر حساب می‌تواند token، URL ورودی، مسیر Webhook، سیاست DM و محدودیت‌ها را override کند. نشست‌های پیام مستقیم برای هر حساب و کاربر جدا هستند، بنابراین همان user_id عددی روی دو حساب متفاوت Synology وضعیت transcript مشترک ندارد. برای هر حساب فعال، یک webhookPath متمایز تعیین کنید. OpenClaw اکنون مسیرهای دقیق تکراری را رد می‌کند و از شروع حساب‌های نام‌گذاری‌شده‌ای که در راه‌اندازی‌های چندحسابی فقط یک مسیر Webhook مشترک را به ارث می‌برند خودداری می‌کند. اگر عمداً برای یک حساب نام‌گذاری‌شده به ارث‌بری legacy نیاز دارید، روی همان حساب یا در channels.synology-chat مقدار dangerouslyAllowInheritedWebhookPath: true را تنظیم کنید، اما مسیرهای دقیق تکراری همچنان به‌صورت fail-closed رد می‌شوند. مسیرهای صریح برای هر حساب را ترجیح دهید.

{
  channels: {
    "synology-chat": {
      enabled: true,
      accounts: {
        default: {
          token: "token-a",
          incomingUrl: "https://nas-a.example.com/...token=...",
        },
        alerts: {
          token: "token-b",
          incomingUrl: "https://nas-b.example.com/...token=...",
          webhookPath: "/webhook/synology-alerts",
          dmPolicy: "allowlist",
          allowedUserIds: ["987654"],
        },
      },
    },
  },
}

# نکات امنیتی

• token را محرمانه نگه دارید و در صورت افشا شدن آن را rotate کنید.
• allowInsecureSsl: false را حفظ کنید، مگر اینکه صراحتاً به یک گواهی محلی خودامضاشدهٔ NAS اعتماد داشته باشید.
• درخواست‌های Webhook ورودی از نظر توکن بررسی می‌شوند و برای هر فرستنده rate-limit می‌شوند.
• بررسی توکن نامعتبر از مقایسهٔ محرمانهٔ constant-time استفاده می‌کند و به‌صورت fail-closed رد می‌شود.
• برای محیط production، dmPolicy: "allowlist" را ترجیح دهید.
• dangerouslyAllowNameMatching را خاموش نگه دارید، مگر اینکه صراحتاً به تحویل پاسخ مبتنی بر نام کاربری legacy نیاز داشته باشید.
• dangerouslyAllowInheritedWebhookPath را خاموش نگه دارید، مگر اینکه صراحتاً ریسک مسیریابی مسیر مشترک را در یک راه‌اندازی چندحسابی بپذیرید.

# عیب‌یابی

• Missing required fields (token, user_id, text):
  • payload مربوط به Webhook خروجی یکی از فیلدهای الزامی را ندارد
  • اگر Synology توکن را در headerها می‌فرستد، مطمئن شوید Gateway/proxy آن headerها را حفظ می‌کند
• Invalid token:
  • راز Webhook خروجی با channels.synology-chat.token مطابقت ندارد
  • درخواست به حساب/مسیر Webhook اشتباه می‌رسد
  • یک reverse proxy پیش از رسیدن درخواست به OpenClaw، header توکن را حذف کرده است
• Rate limit exceeded:
  • تلاش‌های بیش از حد با توکن نامعتبر از یک منبع می‌تواند آن منبع را موقتاً قفل کند
  • فرستندگان احرازشده نیز یک محدودیت نرخ پیام جداگانه برای هر کاربر دارند
• Allowlist is empty. Configure allowedUserIds or use dmPolicy=open with allowedUserIds=["*"].:
  • dmPolicy="allowlist" فعال است اما هیچ کاربری پیکربندی نشده است
• User not authorized:
  • user_id عددی فرستنده در allowedUserIds نیست

# مرتبط

• مرور کلی کانال‌ها — همهٔ کانال‌های پشتیبانی‌شده
• Pairing — احراز هویت DM و جریان pairing
• گروه‌ها — رفتار گفتگوی گروهی و mention gating
• مسیریابی کانال — مسیریابی نشست برای پیام‌ها
• امنیت — مدل دسترسی و سخت‌سازی