Configuration
جفتسازی
«جفتسازی» مرحلهٔ تأیید دسترسی صریح OpenClaw است. در دو جا استفاده میشود:
- جفتسازی DM (چه کسی مجاز است با ربات صحبت کند)
- جفتسازی Node (کدام دستگاهها/نودها مجازند به شبکهٔ Gateway بپیوندند)
زمینهٔ امنیتی: امنیت
1) جفتسازی DM (دسترسی گفتوگوی ورودی)
وقتی یک کانال با سیاست DM بهصورت pairing پیکربندی شده باشد، فرستندگان ناشناس یک کد کوتاه دریافت میکنند و پیام آنها تا زمانی که شما تأیید نکنید پردازش نمیشود.
سیاستهای پیشفرض DM در اینجا مستند شدهاند: امنیت
dmPolicy: "open" فقط زمانی عمومی است که فهرست مجاز مؤثر DM شامل "*" باشد.
راهاندازی و اعتبارسنجی برای پیکربندیهای عمومی-باز به آن wildcard نیاز دارند. اگر وضعیت موجود
شامل open با ورودیهای مشخص allowFrom باشد، runtime همچنان فقط همان
فرستندگان را میپذیرد، و تأییدهای pairing-store دسترسی open را گسترش نمیدهند.
کدهای جفتسازی:
- 8 کاراکتر، حروف بزرگ، بدون کاراکترهای مبهم (
0O1I). - پس از 1 ساعت منقضی میشوند. ربات فقط وقتی پیام جفتسازی را میفرستد که یک درخواست جدید ایجاد شود (تقریباً هر ساعت یکبار برای هر فرستنده).
- درخواستهای در انتظار جفتسازی DM بهطور پیشفرض به 3 مورد برای هر کانال محدود میشوند؛ درخواستهای بیشتر تا وقتی یکی منقضی یا تأیید شود نادیده گرفته میشوند.
تأیید یک فرستنده
openclaw pairing list telegramopenclaw pairing approve telegram <CODE>اگر هنوز مالک فرمانی پیکربندی نشده باشد، تأیید یک کد جفتسازی DM همچنین
commands.ownerAllowFrom را با فرستندهٔ تأییدشده راهاندازی اولیه میکند، مانند telegram:123456789.
این کار برای راهاندازیهای بار اول یک مالک صریح برای فرمانهای دارای امتیاز و درخواستهای تأیید exec
فراهم میکند. پس از وجود داشتن یک مالک، تأییدهای بعدی جفتسازی فقط دسترسی DM
میدهند؛ مالکهای بیشتری اضافه نمیکنند.
کانالهای پشتیبانیشده: discord, feishu, googlechat, imessage, irc, line, matrix, mattermost, msteams, nextcloud-talk, nostr, openclaw-weixin, signal, slack, synology-chat, telegram, twitch, whatsapp, zalo, zalouser.
گروههای فرستندهٔ قابل استفادهٔ مجدد
وقتی مجموعهٔ یکسانی از فرستندگان مورد اعتماد باید برای چندین کانال پیام یا هم برای فهرستهای مجاز DM و هم گروه اعمال شود، از accessGroups سطح بالا استفاده کنید.
گروههای ایستا از type: "message.senders" استفاده میکنند و از فهرستهای مجاز کانال با
accessGroup:<name> ارجاع داده میشوند:
{ accessGroups: { operators: { type: "message.senders", members: { discord: ["discord:123456789012345678"], telegram: ["987654321"], whatsapp: ["+15551234567"], }, }, }, channels: { telegram: { dmPolicy: "allowlist", allowFrom: ["accessGroup:operators"] }, whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["accessGroup:operators"] }, },}گروههای دسترسی بهتفصیل اینجا مستند شدهاند: گروههای دسترسی
وضعیت کجا نگهداری میشود
زیر ~/.openclaw/credentials/ ذخیره میشود:
- درخواستهای در انتظار:
<channel>-pairing.json - مخزن فهرست مجاز تأییدشده:
- حساب پیشفرض:
<channel>-allowFrom.json - حساب غیرپیشفرض:
<channel>-<accountId>-allowFrom.json
- حساب پیشفرض:
رفتار محدودهبندی حساب:
- حسابهای غیرپیشفرض فقط فایل فهرست مجاز محدودهبندیشدهٔ خود را میخوانند/مینویسند.
- حساب پیشفرض از فایل فهرست مجاز بدون محدودهٔ وابسته به کانال استفاده میکند.
با اینها بهعنوان دادههای حساس برخورد کنید (دسترسی به دستیار شما را کنترل میکنند).
2) جفتسازی دستگاه Node (نودهای iOS/Android/macOS/headless)
نودها بهعنوان دستگاهها با role: node به Gateway وصل میشوند. Gateway
یک درخواست جفتسازی دستگاه ایجاد میکند که باید تأیید شود.
جفتسازی از طریق Telegram (توصیهشده برای iOS)
اگر از Plugin device-pair استفاده میکنید، میتوانید جفتسازی دستگاه برای بار اول را کاملاً از Telegram انجام دهید:
- در Telegram، به ربات خود پیام دهید:
/pair - ربات با دو پیام پاسخ میدهد: یک پیام راهنما و یک پیام جداگانهٔ کد راهاندازی (برای کپی/پیست در Telegram آسان است).
- روی تلفن خود، برنامهٔ OpenClaw iOS را باز کنید → Settings → Gateway.
- کد QR را اسکن کنید یا کد راهاندازی را جایگذاری کنید و وصل شوید.
- دوباره در Telegram:
/pair pending(شناسههای درخواست، نقش، و scopeها را بررسی کنید)، سپس تأیید کنید.
کد راهاندازی یک payload JSON کدگذاریشده با base64 است که شامل موارد زیر است:
url: نشانی WebSocket مربوط به Gateway (ws://...یاwss://...)bootstrapToken: یک توکن راهاندازی اولیهٔ کوتاهعمر و تکدستگاهی که برای handshake اولیهٔ جفتسازی استفاده میشود
آن توکن راهاندازی اولیه پروفایل راهاندازی داخلی جفتسازی را حمل میکند:
- توکن تحویلدادهشدهٔ اصلی
nodeبهصورتscopes: []باقی میماند - هر توکن تحویلدادهشدهٔ
operatorدر محدودهٔ فهرست مجاز راهاندازی اولیه باقی میماند:operator.approvals,operator.read,operator.talk.secrets,operator.write - بررسیهای scope راهاندازی اولیه با پیشوند نقش انجام میشوند، نه بهصورت یک مخزن scope تخت: ورودیهای scope مربوط به operator فقط درخواستهای operator را برآورده میکنند، و نقشهای غیر-operator همچنان باید scopeها را زیر پیشوند نقش خودشان درخواست کنند
- چرخش/ابطال بعدی توکن همچنان هم به قرارداد نقش تأییدشدهٔ دستگاه و هم به scopeهای operator نشست فراخواننده محدود میماند
تا زمانی که کد راهاندازی معتبر است، با آن مانند یک گذرواژه رفتار کنید.
برای Tailscale، عمومی، یا دیگر جفتسازیهای موبایل از راه دور، از Tailscale Serve/Funnel
یا یک URL دیگر Gateway با wss:// استفاده کنید. کدهای راهاندازی ws:// متن ساده فقط
برای loopback، نشانیهای LAN خصوصی، میزبانهای Bonjour با .local، و میزبان شبیهساز Android
پذیرفته میشوند. نشانیهای CGNAT مربوط به tailnet، نامهای .ts.net، و میزبانهای عمومی همچنان
پیش از صدور QR/کد راهاندازی بهصورت بسته رد میشوند.
تأیید یک دستگاه Node
openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>وقتی یک تأیید صریح رد میشود چون نشست دستگاه جفتشدهٔ تأییدکننده
با scope فقط-جفتسازی باز شده بود، CLI همان درخواست را با
operator.admin دوباره تلاش میکند. این به یک دستگاه جفتشدهٔ موجود با قابلیت admin اجازه میدهد یک
جفتسازی جدید رابط کاربری کنترل/مرورگر را بدون ویرایش دستی devices/paired.json بازیابی کند. Gateway
همچنان اتصال دوبارهتلاششده را اعتبارسنجی میکند؛ توکنهایی که نمیتوانند با
operator.admin احراز هویت شوند مسدود میمانند.
اگر همان دستگاه با جزئیات احراز هویت متفاوت دوباره تلاش کند (برای مثال
نقش/scopeها/کلید عمومی متفاوت)، درخواست در انتظار قبلی جایگزین میشود و یک
requestId جدید ایجاد میشود.
تأیید خودکار اختیاری Node با CIDR مورد اعتماد
جفتسازی دستگاه بهطور پیشفرض دستی باقی میماند. برای شبکههای Node کاملاً کنترلشده، میتوانید با CIDRهای صریح یا IPهای دقیق، تأیید خودکار Node برای بار اول را فعال کنید:
{ gateway: { nodes: { pairing: { autoApproveCidrs: ["192.168.1.0/24"], }, }, },}این فقط برای درخواستهای جفتسازی تازه با role: node و بدون scopeهای درخواستشده اعمال میشود.
کلاینتهای operator، مرورگر، رابط کاربری کنترل، و WebChat همچنان به تأیید دستی
نیاز دارند. تغییرات نقش، scope، فراداده، و کلید عمومی همچنان به تأیید دستی
نیاز دارند.
ذخیرهسازی وضعیت جفتسازی Node
زیر ~/.openclaw/devices/ ذخیره میشود:
pending.json(کوتاهعمر؛ درخواستهای در انتظار منقضی میشوند)paired.json(دستگاههای جفتشده + توکنها)
یادداشتها
- API قدیمی
node.pair.*(CLI:openclaw nodes pending|approve|reject|remove|rename) یک مخزن جفتسازی جداگانه و متعلق به Gateway است. نودهای WS همچنان به جفتسازی دستگاه نیاز دارند. - رکورد جفتسازی منبع حقیقت پایدار برای نقشهای تأییدشده است. توکنهای فعال دستگاه در محدودهٔ همان مجموعه نقشهای تأییدشده باقی میمانند؛ یک ورودی توکن سرگردان خارج از نقشهای تأییدشده دسترسی جدید ایجاد نمیکند.