Configuration

جفت‌سازی

«جفت‌سازی» مرحلهٔ صریح OpenClaw برای تأیید دسترسی است. این مرحله در دو محل استفاده می‌شود:

جفت‌سازی پیام خصوصی (چه کسی اجازه دارد با ربات گفتگو کند)
جفت‌سازی Node (کدام دستگاه‌ها/Nodeها اجازه دارند به شبکهٔ Gateway بپیوندند)

زمینهٔ امنیتی: امنیت

1) جفت‌سازی پیام خصوصی (دسترسی به گفت‌وگوی ورودی)

وقتی کانالی با سیاست پیام خصوصی pairing پیکربندی شده باشد، فرستندگان ناشناس یک کد کوتاه دریافت می‌کنند و پیام آن‌ها تا زمان تأیید شما پردازش نمی‌شود.

سیاست‌های پیش‌فرض پیام خصوصی در این صفحه مستند شده‌اند: امنیت

dmPolicy: "open" تنها زمانی عمومی است که فهرست مجاز مؤثر پیام خصوصی شامل "*" باشد. راه‌اندازی و اعتبارسنجی برای پیکربندی‌های عمومی و باز به آن نویسهٔ عام نیاز دارند. اگر وضعیت موجود شامل open با ورودی‌های مشخص allowFrom باشد، زمان اجرا همچنان فقط همان فرستندگان را می‌پذیرد و تأییدهای ذخیره‌گاه جفت‌سازی، دسترسی open را گسترش نمی‌دهند.

کدهای جفت‌سازی:

۸ نویسه، با حروف بزرگ و بدون نویسه‌های مبهم (0O1I).
پس از ۱ ساعت منقضی می‌شوند. ربات تنها هنگام ایجاد یک درخواست جدید، پیام جفت‌سازی را می‌فرستد (تقریباً ساعتی یک‌بار برای هر فرستنده).
درخواست‌های در انتظار جفت‌سازی پیام خصوصی به ۳ درخواست برای هر حساب کانال محدود می‌شوند؛ درخواست‌های بیشتر تا زمان انقضا یا تأیید یکی از آن‌ها نادیده گرفته می‌شوند.

تأیید از Control UI

Settings → Channels → DM access requests را باز کنید. صف، درخواست‌های در انتظار همهٔ حساب‌های کانال پیکربندی‌شده‌ای را که سیاست پیام خصوصی آن‌ها pairing است ترکیب می‌کند. براساس کانال یا حساب فیلتر کنید، شناسه و فرادادهٔ فرستنده را بررسی کنید و سپس Approve را انتخاب کنید.

تأیید فقط دسترسی پیام مستقیم را اعطا می‌کند. این کار دسترسی گروهی نمی‌دهد. در صورت پشتیبانی، پنجرهٔ تأیید این گزینه‌های صریح را نیز ارائه می‌کند:

Notify the requester after approval
Also make this sender the first command owner، که تنها وقتی نمایش داده می‌شود که هیچ مالک فرمانی وجود نداشته باشد و نشست Control UI دارای operator.admin باشد

برای حذف یک درخواست در انتظار بدون تأیید آن، Dismiss را انتخاب کنید. ردکردن یک مسدودسازی دائمی نیست؛ فرستنده می‌تواند بعداً دوباره درخواست دسترسی کند.

تأیید از CLI

bash

openclaw pairing list telegramopenclaw pairing approve telegram &lt;CODE&gt;

برای اطلاع‌دادن به درخواست‌کننده در همان کانال، --notify را اضافه کنید. کانال‌های چندحسابی --account <id> را می‌پذیرند.

برخلاف کادر انتخاب صریح Control UI، هنگامی که هیچ مالک فرمانی پیکربندی نشده باشد، CLI به‌طور خودکار commands.ownerAllowFrom را با استفاده از ورودی‌ای مانند telegram:123456789 راه‌اندازی اولیه می‌کند. این کار برای راه‌اندازی‌های نخستین، مالکی صریح برای فرمان‌های دارای امتیاز و درخواست‌های تأیید اجرا فراهم می‌کند. پس از ایجاد یک مالک، تأییدهای جفت‌سازی بعدی فقط دسترسی پیام خصوصی را اعطا می‌کنند و مالک دیگری اضافه نمی‌کنند.

کانال‌های پشتیبانی‌شده (هر Plugin کانال نصب‌شده‌ای که جفت‌سازی را اعلام کند؛ Pluginهای خارجی مانند openclaw-weixin می‌توانند موارد بیشتری اضافه کنند): discord، feishu، googlechat، imessage، irc، line، matrix، mattermost، msteams، nextcloud-talk، nostr، signal، slack، sms، synology-chat، telegram، twitch، whatsapp، zalo، zalouser.

گروه‌های فرستندهٔ قابل‌استفادهٔ مجدد

وقتی یک مجموعهٔ یکسان از فرستندگان مورداعتماد باید برای چند کانال پیام یا برای فهرست‌های مجاز پیام خصوصی و گروهی اعمال شود، از accessGroups در سطح بالا استفاده کنید.

گروه‌های ایستا از type: "message.senders" استفاده می‌کنند و در فهرست‌های مجاز کانال با accessGroup:<name> به آن‌ها ارجاع داده می‌شود:

json5

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

گروه‌های دسترسی با جزئیات در اینجا مستند شده‌اند: گروه‌های دسترسی

محل نگهداری وضعیت

در پایگاه دادهٔ وضعیت SQLite مشترک در ~/.openclaw/state/openclaw.sqlite ذخیره می‌شود:

درخواست‌های در انتظار در channel_pairing_requests
فرستندگان تأییدشده در channel_pairing_allow_entries

رفتار محدوده‌بندی حساب:

کلید هر درخواست و فرستندهٔ تأییدشده براساس کانال و حساب تعیین می‌شود
زمان اجرا فقط ردیف‌های متعارف SQLite را می‌خواند و فایل‌های قدیمی را ادغام نمی‌کند

Gatewayهای قدیمی‌تر، <channel>-pairing.json و <channel>-<accountId>-allowFrom.json را در ~/.openclaw/credentials/ می‌نوشتند. مهاجرت هنگام راه‌اندازی و openclaw doctor --fix این فایل‌ها را به SQLite وارد می‌کنند و پس از ورود موفق، هر فایل مبدأ را حذف می‌کنند. پایگاه دادهٔ SQLite را حساس تلقی کنید، زیرا این ردیف‌ها دسترسی به دستیار شما را کنترل می‌کنند.

Note

ذخیره‌گاه فهرست مجاز جفت‌سازی برای دسترسی پیام خصوصی است. مجوزدهی گروهی جداگانه است. تأیید کد جفت‌سازی پیام خصوصی، به‌طور خودکار به آن فرستنده اجازه نمی‌دهد فرمان‌های گروهی را اجرا کند یا ربات را در گروه‌ها کنترل کند. راه‌اندازی اولیهٔ مالک نخست، وضعیت پیکربندی جداگانه‌ای در commands.ownerAllowFrom است و تحویل گفت‌وگوی گروهی همچنان از فهرست‌های مجاز گروهی کانال پیروی می‌کند (برای مثال groupAllowFrom، groups، یا بازنویسی‌های مختص هر گروه یا هر موضوع، بسته به کانال).

2) جفت‌سازی دستگاه Node (Nodeهای iOS/Android/macOS/بدون رابط)

Nodeها به‌عنوان دستگاه و با role: node به Gateway متصل می‌شوند. Gateway یک درخواست جفت‌سازی دستگاه ایجاد می‌کند که باید تأیید شود.

جفت‌سازی از Control UI (توصیه‌شده)

از یک نشست ازپیش‌متصل Control UI با دسترسی operator.admin استفاده کنید:

Control UI را باز کنید و به Settings → Devices بروید.
در صفحهٔ Devices، روی Pair mobile device کلیک کنید.
گزینهٔ Full access (recommended) را نگه دارید یا برای حذف کنترل‌های مدیریتی Gateway، Limited access را انتخاب کنید.
روی Create setup code کلیک کنید.
در تلفن خود، برنامهٔ OpenClaw را باز کنید ← Settings ← Gateway.
کد QR را اسکن کنید یا کد راه‌اندازی را جای‌گذاری کنید، سپس متصل شوید.

برنامه‌های رسمی iOS و Android متعلق به OpenClaw هنگامی که فرادادهٔ کد راه‌اندازی آن‌ها مطابقت داشته باشد، به‌طور خودکار تأیید می‌شوند. اگر Pending approval درخواستی را نمایش داد (برای مثال، برای یک کلاینت غیررسمی یا فرادادهٔ نامطابق)، پیش از تأیید، نقش و دامنه‌های آن را بررسی کنید.

وقتی نشست فعلی Control UI دسترسی مدیر نداشته باشد، دکمه غیرفعال است. در این حالت، از جریان تأیید CLI در ادامه و از میزبان Gateway استفاده کنید.

جفت‌سازی ازطریق Telegram

اگر از Plugin device-pair استفاده می‌کنید، می‌توانید نخستین جفت‌سازی دستگاه را کاملاً ازطریق Telegram انجام دهید:

در Telegram، این پیام را برای ربات خود بفرستید: /pair
ربات با دو پیام پاسخ می‌دهد: یک پیام راهنما و یک پیام جداگانهٔ کد راه‌اندازی (برای کپی/جای‌گذاری آسان در Telegram).
در تلفن خود، برنامهٔ OpenClaw برای iOS را باز کنید ← Settings ← Gateway.
کد QR را اسکن کنید (/pair qr) یا کد راه‌اندازی را جای‌گذاری و متصل شوید.
برنامهٔ رسمی موبایل به‌طور خودکار متصل می‌شود. اگر /pair pending درخواستی را نمایش داد، پیش از تأیید، نقش و دامنه‌های آن را بررسی کنید.

کد راه‌اندازی یک بار دادهٔ JSON با کدگذاری base64 است که شامل موارد زیر است:

url: نشانی WebSocket مربوط به Gateway (ws://... یا wss://...)
urls: در صورت وجود، مسیرهای مرتب‌شدهٔ LAN/Tailnet که برنامهٔ موبایل می‌تواند امتحان کند
bootstrapToken: یک توکن راه‌اندازی اولیهٔ یک‌بارمصرف برای دست‌دهی اولیهٔ جفت‌سازی؛ Gateway آن را پس از ۱۰ دقیقه منقضی می‌کند

پس از پایان جفت‌سازی، برای بی‌اعتبارکردن کدهای راه‌اندازی استفاده‌نشده، /pair cleanup را اجرا کنید.

آن توکن راه‌اندازی اولیه، نمایهٔ داخلی راه‌اندازی اولیهٔ جفت‌سازی را حمل می‌کند:

راه‌اندازی امن wss:// (یا loopback روی همان میزبان) به‌طور پیش‌فرض از node به‌همراه دسترسی کامل operator برای موبایل بومی استفاده می‌کند
توکن تحویل‌داده‌شدهٔ node همچنان scopes: [] باقی می‌ماند
توکن تحویل‌داده‌شدهٔ پیش‌فرض operator شامل operator.admin، operator.approvals، operator.read، operator.talk.secrets و operator.write است
گزینهٔ Limited access در Control UI و openclaw qr --limited ضمن حفظ سایر دامنه‌های اپراتور، operator.admin را حذف می‌کنند
راه‌اندازی متنی سادهٔ LAN با ws:// به‌طور خودکار از همان نمایهٔ محدود استفاده می‌کند؛ برای دسترسی کامل، wss:// یا Tailscale Serve را پیکربندی و کد جدیدی ایجاد کنید
چرخش/لغو بعدی توکن همچنان هم به قرارداد نقش تأییدشدهٔ دستگاه و هم به دامنه‌های اپراتور نشست فراخواننده محدود می‌ماند

تا زمانی که کد راه‌اندازی معتبر است، با آن مانند گذرواژه رفتار کنید.

صفحه‌های Settings → Gateway در iOS و Android، دسترسی Full یا Limited را نمایش می‌دهند. برای ارتقای یک تلفن با دسترسی محدود، ابتدا یک مسیر امن wss:// یا Tailscale Serve را پیکربندی کنید، سپس یک کد راه‌اندازی جدید با دسترسی کامل بسازید، آن را در همان صفحهٔ تنظیمات اسکن یا جای‌گذاری کنید و دوباره متصل شوید.

برای جفت‌سازی عمومی، راه دور یا ازطریق Tailscale با موبایل، از Tailscale Serve/Funnel یا نشانی Gateway دیگری با wss:// استفاده کنید. کدهای راه‌اندازی متن سادهٔ ws:// فقط برای loopback، نشانی‌های LAN خصوصی، میزبان‌های Bonjour با .local و میزبان شبیه‌ساز Android پذیرفته می‌شوند. مسیرهای متن سادهٔ غیر-loopback دسترسی محدود دریافت می‌کنند. نشانی‌های CGNAT در Tailnet، نام‌های .ts.net و میزبان‌های عمومی همچنان پیش از صدور QR/کد راه‌اندازی به‌صورت بسته رد می‌شوند.

برای نشانی‌های راه‌اندازی gateway.bind=lan، OpenClaw ریشه‌های HTTPS پایدار Tailscale Serve را که درگاه loopback مربوط به Gateway فعال را پروکسی می‌کنند شناسایی کرده و آن‌ها را در کنار مسیر LAN اعلام می‌کند. فرمان راه‌اندازی این مسیر جایگزین را فقط برای lan اضافه می‌کند؛ custom و tailnet مسیرهای صریحاً اعلام‌شدهٔ خود را حفظ می‌کنند. برنامهٔ iOS مسیرهای اعلام‌شده را به‌ترتیب بررسی و نخستین نقطهٔ پایانی دردسترس را ذخیره می‌کند.

تأیید یک دستگاه Node

bash

openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>

وقتی یک تأیید صریح به این دلیل رد شود که نشست دستگاه جفت‌شدهٔ تأییدکننده فقط با دامنهٔ جفت‌سازی باز شده است، CLI همان درخواست را با operator.admin دوباره امتحان می‌کند. این کار به یک دستگاه جفت‌شدهٔ موجود با قابلیت مدیریت اجازه می‌دهد جفت‌سازی جدید Control UI/مرورگر را بدون ویرایش دستی ذخیره‌گاه جفت‌سازی بازیابی کند. Gateway همچنان اتصال تکرارشده را اعتبارسنجی می‌کند؛ توکن‌هایی که نتوانند با operator.admin احراز هویت کنند، مسدود باقی می‌مانند.

اگر همان دستگاه با جزئیات احراز هویت متفاوت دوباره تلاش کند (برای مثال نقش/دامنه‌ها/کلید عمومی متفاوت)، درخواست در انتظار قبلی جایگزین و یک requestId جدید ایجاد می‌شود.

تأیید خودکار اختیاری Node برای CIDR مورداعتماد

جفت‌سازی دستگاه به‌طور پیش‌فرض دستی باقی می‌ماند. برای شبکه‌های Node با کنترل سخت‌گیرانه، می‌توانید تأیید خودکار نخستین Node را با CIDRها یا IPهای صریح فعال کنید:

json5

{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

این فقط برای درخواست‌های تازهٔ جفت‌سازی role: node بدون دامنهٔ درخواستی اعمال می‌شود. کلاینت‌های اپراتور، مرورگر، Control UI و WebChat همچنان به تأیید دستی نیاز دارند. تغییرات نقش، دامنه، فراداده و کلید عمومی نیز همچنان به تأیید دستی نیاز دارند.

ذخیره‌سازی وضعیت جفت‌سازی Node