Configuration
جفتسازی
«Pairing» مرحلهٔ تأیید دسترسی صریح در OpenClaw است. در دو جا استفاده میشود:
- Pairing پیام مستقیم (چه کسی مجاز است با ربات صحبت کند)
- Pairing Node (کدام دستگاهها/Nodeها مجازند به شبکهٔ Gateway بپیوندند)
زمینهٔ امنیتی: امنیت
1) Pairing پیام مستقیم (دسترسی چت ورودی)
وقتی یک کانال با سیاست پیام مستقیم pairing پیکربندی شده باشد، فرستندههای ناشناس یک کد کوتاه دریافت میکنند و پیام آنها تا زمانی که شما تأیید کنید پردازش نمیشود.
سیاستهای پیشفرض پیام مستقیم در اینجا مستند شدهاند: امنیت
dmPolicy: "open" فقط وقتی عمومی است که فهرست مجاز پیام مستقیم مؤثر شامل "*" باشد.
راهاندازی و اعتبارسنجی برای پیکربندیهای عمومی-باز به این wildcard نیاز دارند. اگر وضعیت موجود شامل open با ورودیهای مشخص allowFrom باشد، runtime همچنان فقط همان فرستندهها را میپذیرد، و تأییدهای مخزن Pairing دسترسی open را گستردهتر نمیکنند.
کدهای Pairing:
- ۸ نویسه، حروف بزرگ، بدون نویسههای مبهم (
0O1I). - پس از ۱ ساعت منقضی میشوند. ربات فقط وقتی پیام Pairing را میفرستد که یک درخواست جدید ایجاد شود (تقریباً هر ساعت یکبار برای هر فرستنده).
- درخواستهای در انتظار Pairing پیام مستقیم بهطور پیشفرض به ۳ مورد در هر کانال محدودند؛ درخواستهای اضافی تا زمانی که یکی منقضی یا تأیید شود نادیده گرفته میشوند.
تأیید یک فرستنده
openclaw pairing list telegramopenclaw pairing approve telegram <CODE>اگر هنوز مالک فرمانی پیکربندی نشده باشد، تأیید یک کد Pairing پیام مستقیم همچنین commands.ownerAllowFrom را با فرستندهٔ تأییدشده bootstrap میکند، مانند telegram:123456789.
این کار برای راهاندازیهای نخستین، یک مالک صریح برای فرمانهای دارای امتیاز و اعلانهای تأیید exec فراهم میکند. پس از اینکه یک مالک وجود داشته باشد، تأییدهای بعدی Pairing فقط دسترسی پیام مستقیم را اعطا میکنند؛ آنها مالکهای بیشتری اضافه نمیکنند.
کانالهای پشتیبانیشده: discord, feishu, googlechat, imessage, irc, line, matrix, mattermost, msteams, nextcloud-talk, nostr, openclaw-weixin, signal, slack, synology-chat, telegram, twitch, whatsapp, zalo, zalouser.
گروههای فرستندهٔ قابل استفادهٔ مجدد
وقتی قرار است همان مجموعهٔ فرستندههای مورد اعتماد روی چند کانال پیام یا هم فهرستهای مجاز پیام مستقیم و هم گروه اعمال شود، از 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) Pairing دستگاه Node (Nodeهای iOS/Android/macOS/headless)
Nodeها بهعنوان دستگاهها با role: node به Gateway وصل میشوند. Gateway یک درخواست Pairing دستگاه ایجاد میکند که باید تأیید شود.
Pairing از Control UI (توصیهشده)
از یک نشست Control UI که از قبل متصل است و دسترسی operator.admin دارد استفاده کنید:
- Control UI را باز کنید و Nodes را انتخاب کنید.
- در Devices، روی Pair mobile device کلیک کنید.
- روی تلفن خود، برنامهٔ OpenClaw را باز کنید ← Settings ← Gateway.
- کد QR را اسکن کنید یا کد راهاندازی را جایگذاری کنید، سپس وصل شوید.
برنامههای رسمی iOS و Android OpenClaw وقتی metadata کد راهاندازی آنها مطابقت داشته باشد بهطور خودکار تأیید میشوند. اگر Devices یک درخواست در انتظار نشان دهد (برای مثال، برای یک کلاینت غیررسمی یا metadata نامطابق)، پیش از تأیید، نقش و scopes آن را بررسی کنید.
وقتی نشست فعلی Control UI دسترسی مدیر نداشته باشد، دکمه غیرفعال است. در این حالت از جریان تأیید CLI زیر از میزبان Gateway استفاده کنید.
Pairing از طریق Telegram
اگر از Plugin device-pair استفاده میکنید، میتوانید Pairing نخستین دستگاه را کاملاً از Telegram انجام دهید:
- در Telegram، به ربات خود پیام بدهید:
/pair - ربات با دو پیام پاسخ میدهد: یک پیام دستورالعمل و یک پیام جداگانهٔ کد راهاندازی (برای کپی/جایگذاری در Telegram آسان است).
- روی تلفن خود، برنامهٔ iOS OpenClaw را باز کنید ← Settings ← Gateway.
- کد QR را اسکن کنید یا کد راهاندازی را جایگذاری کنید و وصل شوید.
- برنامهٔ موبایل رسمی بهطور خودکار وصل میشود. اگر
/pair pendingیک درخواست نشان میدهد، پیش از تأیید، نقش و scopes آن را بررسی کنید.
کد راهاندازی یک payload JSON کدگذاریشده با base64 است که شامل این موارد است:
url: نشانی WebSocket مربوط به Gateway (ws://...یاwss://...)bootstrapToken: یک توکن bootstrap کوتاهعمر و تکدستگاهی که برای handshake اولیهٔ Pairing استفاده میشود
آن توکن bootstrap پروفایل bootstrap داخلی Pairing را حمل میکند:
- پروفایل راهاندازی داخلی فقط baseline تازهٔ QR/کد راهاندازی را مجاز میکند:
nodeبهعلاوهٔ یک واگذاری محدودoperator - توکن
nodeواگذارشده بهصورتscopes: []باقی میماند - توکن
operatorواگذارشده بهoperator.approvals،operator.read،operator.talk.secrets، وoperator.writeمحدود است operator.adminاز طریق bootstrap کد QR/راهاندازی اعطا نمیشود؛ به یک جریان Pairing یا توکن operator جداگانه و تأییدشده نیاز دارد- چرخش/لغو بعدی توکن همچنان هم با قرارداد نقش تأییدشدهٔ دستگاه و هم scopes operator نشست فراخواننده محدود میماند
تا زمانی که کد راهاندازی معتبر است، با آن مثل گذرواژه رفتار کنید.
برای Tailscale، عمومی، یا Pairing موبایل راهدور دیگر، از Tailscale Serve/Funnel یا یک URL دیگر wss:// برای Gateway استفاده کنید. کدهای راهاندازی متن سادهٔ ws:// فقط برای loopback، آدرسهای LAN خصوصی، میزبانهای Bonjour با .local، و میزبان شبیهساز Android پذیرفته میشوند. آدرسهای CGNAT مربوط به Tailnet، نامهای .ts.net، و میزبانهای عمومی همچنان پیش از صدور QR/کد راهاندازی fail closed میشوند.
تأیید یک دستگاه Node
openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>وقتی یک تأیید صریح رد شود چون نشست دستگاه Pairingشدهٔ تأییدکننده با دامنهٔ فقط-Pairing باز شده بود، CLI همان درخواست را با operator.admin دوباره تلاش میکند. این امکان میدهد یک دستگاه Pairingشده با قابلیت مدیر، Pairing جدید Control UI/مرورگر را بدون ویرایش دستی devices/paired.json بازیابی کند. Gateway همچنان اتصال دوبارهتلاششده را اعتبارسنجی میکند؛ توکنهایی که نتوانند با operator.admin احراز هویت کنند مسدود میمانند.
اگر همان دستگاه با جزئیات احراز هویت متفاوت دوباره تلاش کند (برای مثال نقش/scopes/کلید عمومی متفاوت)، درخواست در انتظار قبلی جایگزین میشود و یک requestId جدید ایجاد میشود.
تأیید خودکار اختیاری Node با CIDR مورد اعتماد
Pairing دستگاه بهطور پیشفرض دستی باقی میماند. برای شبکههای Node کاملاً کنترلشده، میتوانید با CIDRهای صریح یا IPهای دقیق، تأیید خودکار نخستین Node را فعال کنید:
{ gateway: { nodes: { pairing: { autoApproveCidrs: ["192.168.1.0/24"], }, }, },}این فقط برای درخواستهای Pairing تازه با role: node و بدون scopes درخواستشده اعمال میشود. کلاینتهای Operator، مرورگر، Control UI، و WebChat همچنان به تأیید دستی نیاز دارند. تغییرات نقش، scope، metadata، و کلید عمومی همچنان به تأیید دستی نیاز دارند.
ذخیرهسازی وضعیت Pairing مربوط به Node
زیر ~/.openclaw/devices/ ذخیره میشود:
pending.json(کوتاهعمر؛ درخواستهای در انتظار منقضی میشوند)paired.json(دستگاههای Pairingشده + توکنها)
یادداشتها
- API قدیمی
node.pair.*(CLI:openclaw nodes pending|approve|reject|remove|rename) یک مخزن Pairing جداگانه با مالکیت Gateway است. Nodeهای WS همچنان به Pairing دستگاه نیاز دارند. - رکورد Pairing منبع پایدار حقیقت برای نقشهای تأییدشده است. توکنهای فعال دستگاه به همان مجموعهٔ نقش تأییدشده محدود میمانند؛ یک ورودی توکن پراکنده بیرون از نقشهای تأییدشده دسترسی جدید ایجاد نمیکند.
