Matrix

Matrix یک Plugin کانال قابل دانلود (@openclaw/matrix) است که بر پایهٔ matrix-js-sdk رسمی ساخته شده است. از پیام‌های خصوصی، اتاق‌ها، رشته‌ها، رسانه، واکنش‌ها، نظرسنجی‌ها، موقعیت مکانی و E2EE پشتیبانی می‌کند.

نصب

openclaw plugins install @openclaw/matrix

مشخصات سادهٔ Plugin ابتدا ClawHub و سپس npm را به‌عنوان مسیر جایگزین امتحان می‌کنند. با openclaw plugins install clawhub:@openclaw/matrix یا npm:@openclaw/matrix یک منبع را اجباری کنید. از یک checkout محلی: openclaw plugins install ./path/to/local/matrix-plugin.

plugins install Plugin را ثبت و فعال می‌کند؛ نیازی به مرحلهٔ جداگانهٔ enable نیست. بااین‌حال، کانال تا زمانی که طبق بخش زیر پیکربندی نشود کاری انجام نمی‌دهد. برای قواعد کلی نصب، Pluginها را ببینید.

راه‌اندازی

1. یک حساب Matrix روی homeserver خود ایجاد کنید.
2. channels.matrix را با homeserver + accessToken، یا homeserver + userId + password پیکربندی کنید.
3. Gateway را راه‌اندازی مجدد کنید.
4. یک پیام خصوصی با ربات آغاز کنید یا آن را به اتاقی دعوت کنید. دعوت‌های جدید فقط زمانی پذیرفته می‌شوند که autoJoin اجازه دهد.

راه‌اندازی تعاملی

openclaw channels addopenclaw configure --section channels

ویزارد نشانی URL مربوط به homeserver، روش احراز هویت (توکن یا گذرواژه)، شناسهٔ کاربر (فقط برای احراز هویت با گذرواژه)، نام اختیاری دستگاه، فعال‌سازی یا عدم فعال‌سازی E2EE و دسترسی/پیوستن خودکار به اتاق را می‌پرسد. اگر متغیرهای محیطی منطبق با MATRIX_* از قبل وجود داشته باشند و حساب هیچ احراز هویت ذخیره‌شده‌ای نداشته باشد، ویزارد میان‌بری با متغیر محیطی ارائه می‌کند. پیش از ذخیره‌کردن فهرست مجاز، نام اتاق‌ها را با openclaw channels resolve --channel matrix "Project Room" resolve کنید. فعال‌کردن E2EE در ویزارد همان bootstrap بخش openclaw matrix encryption setup را اجرا می‌کند.

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

مبتنی بر توکن:

{  channels: {    matrix: {      enabled: true,      homeserver: "https://matrix.example.org",      accessToken: "syt_xxx",      dm: { policy: "pairing" },    },  },}

مبتنی بر گذرواژه (توکن پس از نخستین ورود cache می‌شود):

{  channels: {    matrix: {      enabled: true,      homeserver: "https://matrix.example.org",      userId: "@bot:example.org",      password: "replace-me", // پراگما: راز فهرست مجاز      deviceName: "OpenClaw Gateway",    },  },}

پیوستن خودکار

مقدار پیش‌فرض channels.matrix.autoJoin برابر "off" است: ربات تا زمانی که به‌صورت دستی نپیوندید، در اتاق‌ها یا پیام‌های خصوصی جدیدِ حاصل از دعوت‌های تازه ظاهر نمی‌شود. OpenClaw هنگام دعوت نمی‌تواند تشخیص دهد که دعوت مربوط به پیام خصوصی است یا گروه؛ بنابراین هر دعوت ابتدا از autoJoin عبور می‌کند و dm.policy تنها بعداً، پس از پیوستن ربات و طبقه‌بندی اتاق، اعمال می‌شود.

{  channels: {    matrix: {      autoJoin: "allowlist",      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],      groups: {        "!ops:example.org": { requireMention: true },      },    },  },}

قالب‌های مقصد فهرست مجاز

• پیام‌های خصوصی (dm.allowFrom، groupAllowFrom، groups.<room>.users): از @user:server استفاده کنید. نام‌های نمایشی به‌طور پیش‌فرض نادیده گرفته می‌شوند (قابل تغییرند)؛ dangerouslyAllowNameMatching: true را فقط برای سازگاری صریح با نام نمایشی تنظیم کنید.
• کلیدهای فهرست مجاز اتاق (groups، alias قدیمی rooms): از !room:server یا #alias:server استفاده کنید. نام‌های ساده نادیده گرفته می‌شوند، مگر اینکه dangerouslyAllowNameMatching: true باشد.
• فهرست‌های مجاز دعوت (autoJoinAllowlist): از !room:server، #alias:server یا * استفاده کنید. نام‌های ساده همیشه رد می‌شوند.

نرمال‌سازی شناسهٔ حساب

ویزارد یک نام دوستانه را به شناسهٔ حساب نرمال‌شده تبدیل می‌کند (Ops Bot -> ops-bot). علائم نگارشی در نام متغیرهای محیطی scoped به‌صورت هگز escape می‌شوند تا حساب‌ها با یکدیگر تداخل نداشته باشند: - (0x2D) به _X2D_ تبدیل می‌شود؛ بنابراین ops-prod به پیشوند محیطی MATRIX_OPS_X2D_PROD_ نگاشت می‌شود.

اعتبارنامه‌های cacheشده

Matrix اعتبارنامه‌های حساب را در state مشترک Plugin یعنی state/openclaw.sqlite cache می‌کند. هنگامی که اعتبارنامه‌های cacheشده وجود داشته باشند، OpenClaw حتی بدون وجود accessToken در فایل پیکربندی، Matrix را پیکربندی‌شده تلقی می‌کند؛ این وضعیت راه‌اندازی، openclaw doctor و probeهای وضعیت کانال را پوشش می‌دهد. ارتقاها فایل‌های بازنشسته‌شدهٔ ~/.openclaw/credentials/matrix/credentials*.json را از طریق openclaw doctor --fix وارد می‌کنند، ردیف‌های SQLite را تأیید می‌کنند و سپس فایل‌ها را بایگانی می‌کنند.

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

متغیرهای محیطی مبتنی بر کلید پیکربندی زمانی استفاده می‌شوند که کلید پیکربندی معادل تنظیم نشده باشد. حساب پیش‌فرض از نام‌های بدون پیشوند استفاده می‌کند؛ حساب‌های نام‌گذاری‌شده توکن حساب را پیش از پسوند درج می‌کنند (نرمال‌سازی را ببینید).

برای حساب ops، نام‌ها به MATRIX_OPS_HOMESERVER، MATRIX_OPS_ACCESS_TOKEN و به همین ترتیب تبدیل می‌شوند. MATRIX_HOMESERVER (و هر نوع scoped از *_HOMESERVER) را نمی‌توان از یک .env در workspace تنظیم کرد؛ فایل‌های .env در workspace را ببینید.

نمونهٔ پیکربندی

یک مبنای عملی با جفت‌سازی پیام خصوصی، فهرست مجاز اتاق و E2EE:

{  channels: {    matrix: {      enabled: true,      homeserver: "https://matrix.example.org",      accessToken: "syt_xxx",      encryption: true,       dm: {        policy: "pairing",        sessionScope: "per-room",        threadReplies: "off",      },       groupPolicy: "allowlist",      groupAllowFrom: ["@admin:example.org"],      groups: {        "!roomid:example.org": { requireMention: true },      },       autoJoin: "allowlist",      autoJoinAllowlist: ["!roomid:example.org"],      threadReplies: "inbound",      replyToMode: "off",      streaming: { mode: "partial" },    },  },}

پیش‌نمایش‌های streaming

streaming پاسخ Matrix اختیاری است. streaming.mode نحوهٔ تحویل پاسخ در حال تولید دستیار توسط OpenClaw را کنترل می‌کند؛ streaming.block.enabled تعیین می‌کند که آیا هر بلوک تکمیل‌شده به‌عنوان پیام جداگانهٔ Matrix نگه داشته شود یا نه.

{  channels: {    matrix: {      streaming: { mode: "partial" },    },  },}

برای حفظ پیش‌نمایش زندهٔ پاسخ و پنهان‌کردن خطوط موقت ابزار/پیشرفت:

{  channels: {    matrix: {      streaming: {        mode: "partial",        preview: {          toolProgress: false,        },      },    },  },}

پیکربندی کامل { mode, chunkMode, block, preview, progress } را می‌پذیرد:

{  channels: {    matrix: {      streaming: {        mode: "progress",        progress: {          label: "auto", // انتخاب از برچسب‌های پیکربندی‌شده یا داخلی (برای پنهان‌کردن false)          labels: ["Thinking", "Writing", "Searching"], // گزینه‌های label: "auto"          maxLines: 8, // حداکثر خطوط پیشرفت چرخشی (پیش‌فرض: 8)          maxLineChars: 120, // حداکثر نویسه در هر خط پیش از کوتاه‌سازی (پیش‌فرض: 120)          toolProgress: true, // نمایش فعالیت ابزار/پیشرفت (پیش‌فرض: true)        },      },    },  },}

• progress.label: برچسب سفارشی، "auto"/تنظیم‌نشده برای انتخاب یک برچسب پیکربندی‌شده یا داخلی، یا false برای پنهان‌کردن آن.
• progress.labels: گزینه‌هایی که فقط زمانی استفاده می‌شوند که label برابر "auto" یا تنظیم‌نشده باشد.
• progress.maxLines: حداکثر تعداد خطوط پیشرفت چرخشی که در پیش‌نویس نگه داشته می‌شوند؛ خطوط قدیمی‌تر پس از عبور از این مقدار حذف می‌شوند.
• progress.maxLineChars: حداکثر تعداد نویسه در هر خط فشردهٔ پیشرفت پیش از کوتاه‌سازی.
• progress.toolProgress: وقتی true باشد (پیش‌فرض)، فعالیت زندهٔ ابزار/پیشرفت در پیش‌نویس ظاهر می‌شود.

streaming.block.enabled (پیش‌فرض false) مستقل از streaming.mode است:

نکته‌ها:

• اگر اندازهٔ پیش‌نمایش از محدودیت اندازهٔ هر رویداد Matrix عبور کند، OpenClaw streaming پیش‌نمایش را متوقف می‌کند و به تحویل فقط نسخهٔ نهایی بازمی‌گردد.
• پاسخ‌های رسانه‌ای همیشه پیوست‌ها را به‌شکل عادی ارسال می‌کنند؛ اگر نتوان از پیش‌نمایش قدیمی با اطمینان دوباره استفاده کرد، OpenClaw پیش از ارسال پاسخ رسانه‌ای نهایی آن را redacts می‌کند.
• هنگامی که streaming پیش‌نمایش فعال است، به‌روزرسانی‌های پیش‌نمایش پیشرفت ابزار به‌طور پیش‌فرض فعال‌اند. streaming.preview.toolProgress: false را تنظیم کنید تا ویرایش پیش‌نمایش برای متن پاسخ حفظ شود، اما پیشرفت ابزار در مسیر تحویل عادی باقی بماند.
• ویرایش پیش‌نمایش به فراخوانی‌های اضافی API مربوط به Matrix نیاز دارد. برای محافظه‌کارانه‌ترین پروفایل محدودیت نرخ، streaming.mode: "off" را حفظ کنید.
• مقادیر scalar/boolean قدیمی streaming و کلیدهای flat یعنی blockStreaming / chunkMode توسط openclaw doctor --fix به این ساختار تو‌در‌تو بازنویسی می‌شوند.

پیام‌های صوتی

یادداشت‌های صوتی ورودی Matrix پیش از دروازهٔ اشاره به اتاق رونویسی می‌شوند؛ بنابراین یک یادداشت صوتی که نام ربات را بیان کند می‌تواند عامل را در اتاق requireMention: true فعال کند و عامل به‌جای دریافت صرفاً یک جای‌نگهدار پیوست صوتی، متن رونویسی‌شده را دریافت می‌کند.

Matrix از ارائه‌دهندهٔ مشترک رسانهٔ صوتی در tools.media.audio، مانند gpt-4o-mini-transcribe مربوط به OpenAI، استفاده می‌کند. برای راه‌اندازی ارائه‌دهنده و محدودیت‌ها، مروری بر ابزارهای رسانه‌ای را ببینید.

• رویدادهای m.audio و رویدادهای m.file با نوع MIME برابر با audio/* واجد شرایط هستند.
• در اتاق‌های رمزگذاری‌شده، OpenClaw پیش از رونویسی، پیوست را از طریق مسیر رسانه‌ای موجود Matrix رمزگشایی می‌کند.
• رونویسی در اعلان عامل به‌عنوان محتوای تولیدشده توسط ماشین و غیرقابل‌اعتماد علامت‌گذاری می‌شود.
• پیوست به‌عنوان قبلاً رونویسی‌شده علامت‌گذاری می‌شود تا ابزارهای رسانه‌ای پایین‌دستی دوباره آن را رونویسی نکنند.
• برای غیرفعال‌کردن سراسری رونویسی صوتی، tools.media.audio.enabled: false را تنظیم کنید.

فراداده تأیید

اعلان‌های تأیید بومی Matrix، رویدادهای عادی m.room.message با محتوای ویژه OpenClaw زیر کلید com.openclaw.approval هستند. کلاینت‌های استاندارد همچنان بدنه متنی را نمایش می‌دهند؛ کلاینت‌های سازگار با OpenClaw می‌توانند شناسه، نوع، وضعیت، تصمیم‌ها و جزئیات اجرا/Plugin تأیید را بخوانند.

وقتی یک اعلان برای یک رویداد Matrix بیش از حد طولانی باشد، OpenClaw متن قابل‌مشاهده را به بخش‌هایی تقسیم می‌کند و com.openclaw.approval را فقط به بخش نخست پیوست می‌کند. واکنش‌های اجازه/رد به همان رویداد نخست متصل می‌شوند؛ بنابراین اعلان‌های طولانی همان هدف تأیید اعلان‌های تک‌رویدادی را حفظ می‌کنند.

قواعد ارسال میزبانی‌شده شخصی برای پیش‌نمایش‌های نهایی بی‌صدا

streaming.mode: "quiet" تنها پس از نهایی‌شدن یک بلوک یا نوبت، به گیرندگان اعلان می‌دهد؛ یک قاعده ارسال برای هر کاربر باید با نشانگر پیش‌نمایش نهایی مطابقت داشته باشد. برای دستورالعمل کامل، به قواعد ارسال Matrix برای پیش‌نمایش‌های بی‌صدا مراجعه کنید.

اتاق‌های بات‌به‌بات

به‌طور پیش‌فرض، پیام‌های Matrix از سایر حساب‌های پیکربندی‌شده Matrix در OpenClaw نادیده گرفته می‌شوند. برای اجازه‌دادن عمدی به ترافیک میان عامل‌ها از allowBots استفاده کنید:

{  channels: {    matrix: {      allowBots: "mentions", // true | "mentions"      groups: {        "!roomid:example.org": {          requireMention: true,        },      },    },  },}

• allowBots: true پیام‌های سایر حساب‌های بات پیکربندی‌شده Matrix را در اتاق‌ها و پیام‌های مستقیم مجاز می‌پذیرد.
• allowBots: "mentions" این پیام‌ها را در اتاق‌ها فقط زمانی می‌پذیرد که به‌طور آشکار به این بات اشاره کنند؛ پیام‌های مستقیم همچنان بدون توجه به این شرط مجاز هستند.
• groups.<room>.allowBots تنظیم سطح حساب را برای یک اتاق بازنویسی می‌کند.
• پیام‌های پذیرفته‌شده از بات‌های پیکربندی‌شده از محافظت مشترک در برابر حلقه بات استفاده می‌کنند. channels.defaults.botLoopProtection را پیکربندی کنید، سپس آن را برای هر حساب با channels.matrix.botLoopProtection یا برای هر اتاق با channels.matrix.groups.<room>.botLoopProtection بازنویسی کنید.
• OpenClaw همچنان پیام‌های همان شناسه کاربر Matrix را نادیده می‌گیرد تا از حلقه‌های پاسخ به خود جلوگیری کند.
• Matrix پرچم بومی بات ندارد؛ OpenClaw «نوشته‌شده توسط بات» را به‌معنای «ارسال‌شده توسط حساب پیکربندی‌شده دیگری از Matrix روی این Gateway متعلق به OpenClaw» در نظر می‌گیرد.

هنگام فعال‌کردن ترافیک بات‌به‌بات در اتاق‌های مشترک، از فهرست‌های مجاز سخت‌گیرانه اتاق‌ها و الزامات اشاره استفاده کنید.

رمزگذاری و راستی‌آزمایی

در اتاق‌های رمزگذاری‌شده (E2EE)، رویدادهای تصویر خروجی از thumbnail_file استفاده می‌کنند تا پیش‌نمایش‌های تصویر همراه با پیوست کامل رمزگذاری شوند؛ اتاق‌های رمزگذاری‌نشده از thumbnail_url ساده استفاده می‌کنند. نیازی به پیکربندی نیست؛ Plugin وضعیت E2EE را به‌طور خودکار تشخیص می‌دهد.

همه فرمان‌های openclaw matrix گزینه‌های --verbose (عیب‌یابی کامل)، --json (خروجی قابل‌خواندن توسط ماشین) و --account <id> (راه‌اندازی‌های چندحسابی) را می‌پذیرند. خروجی به‌طور پیش‌فرض مختصر است.

فعال‌کردن رمزگذاری

openclaw matrix encryption setupprintf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix encryption setup --recovery-key-stdin

ذخیره‌سازی محرمانه و امضای متقابل را راه‌اندازی می‌کند، در صورت نیاز یک نسخه پشتیبان از کلید اتاق می‌سازد و سپس وضعیت و مراحل بعدی را نمایش می‌دهد. پرچم‌های مفید:

• --recovery-key-stdin یک کلید بازیابی را بدون افشای آن در آرگومان‌های فرایند از ورودی استاندارد می‌خواند؛ --recovery-key <key> برای سازگاری همچنان در دسترس است
• --force-reset-cross-signing هویت فعلی امضای متقابل را کنار می‌گذارد و هویت جدیدی ایجاد می‌کند (فقط برای استفاده عمدی)

برای یک حساب جدید، E2EE را هنگام ایجاد فعال کنید:

openclaw matrix account add \  --homeserver https://matrix.example.org \  --access-token syt_xxx \  --enable-e2ee

--encryption نام مستعار --enable-e2ee است. پیکربندی دستی معادل:

{  channels: {    matrix: {      enabled: true,      homeserver: "https://matrix.example.org",      accessToken: "syt_xxx",      encryption: true,      dm: { policy: "pairing" },    },  },}

وضعیت و نشانه‌های اعتماد

openclaw matrix verify statusopenclaw matrix verify status --include-recovery-key --json

verify status سه نشانه مستقل اعتماد را گزارش می‌کند (--verbose همه آن‌ها را نمایش می‌دهد):

• Locally trusted: فقط مورد اعتماد این کلاینت
• Cross-signing verified: SDK راستی‌آزمایی از طریق امضای متقابل را گزارش می‌کند
• Signed by owner: با کلید خودامضاکننده خودتان امضا شده است (فقط برای عیب‌یابی)

Verified by owner فقط زمانی yes است که Cross-signing verified برابر با yes باشد؛ اعتماد محلی یا امضای مالک به‌تنهایی کافی نیست.

--allow-degraded-local-state بدون آماده‌سازی اولیه حساب Matrix، عیب‌یابی را بر مبنای بهترین تلاش برمی‌گرداند؛ برای بررسی‌های آفلاین یا پیکربندی‌های ناقص مفید است.

راستی‌آزمایی این دستگاه با کلید بازیابی

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

printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin

این فرمان سه وضعیت را گزارش می‌کند:

• Recovery key accepted: Matrix کلید را برای ذخیره‌سازی محرمانه یا اعتماد دستگاه پذیرفته است.
• Backup usable: نسخه پشتیبان کلید اتاق را می‌توان با داده بازیابی مورد اعتماد بارگذاری کرد.
• Device verified by owner: این دستگاه از اعتماد کامل هویت امضای متقابل Matrix برخوردار است.

اگر اعتماد کامل هویت ناقص باشد، فرمان با کد غیرصفر خارج می‌شود؛ حتی اگر کلید بازیابی داده نسخه پشتیبان را باز کرده باشد. در این حالت، خودراستی‌آزمایی را از کلاینت دیگری از Matrix تکمیل کنید:

openclaw matrix verify self

verify self پیش از خروج موفقیت‌آمیز منتظر Cross-signing verified: yes می‌ماند. برای تنظیم زمان انتظار از --timeout-ms <ms> استفاده کنید.

شکل کلید صریح openclaw matrix verify device "<recovery-key>" نیز کار می‌کند، اما کلید در تاریخچه پوسته ثبت می‌شود.

راه‌اندازی یا تعمیر امضای متقابل

openclaw matrix verify bootstrap

فرمان تعمیر/راه‌اندازی برای حساب‌های رمزگذاری‌شده. این فرمان به‌ترتیب:

• ذخیره‌سازی محرمانه را راه‌اندازی می‌کند و در صورت امکان کلید بازیابی موجود را دوباره به‌کار می‌گیرد
• امضای متقابل را راه‌اندازی و کلیدهای عمومی مفقود را بارگذاری می‌کند
• دستگاه فعلی را علامت‌گذاری و به‌صورت متقابل امضا می‌کند
• اگر نسخه پشتیبان سمت سرور از کلید اتاق از قبل وجود نداشته باشد، آن را ایجاد می‌کند

اگر homeserver برای بارگذاری کلیدهای امضای متقابل به UIA نیاز داشته باشد، OpenClaw ابتدا بدون احراز هویت، سپس m.login.dummy و بعد m.login.password را امتحان می‌کند (به channels.matrix.password نیاز دارد).

پرچم‌های مفید:

• --recovery-key-stdin (همراه با printf '%s\n' "$MATRIX_RECOVERY_KEY" | ...) یا --recovery-key <key>
• --force-reset-cross-signing برای کنارگذاشتن هویت فعلی امضای متقابل (فقط به‌صورت عمدی؛ مستلزم ذخیره‌بودن کلید بازیابی فعال یا ارائه آن با --recovery-key-stdin)

نسخه پشتیبان کلید اتاق

openclaw matrix verify backup statusprintf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin

backup status نشان می‌دهد آیا نسخه پشتیبان سمت سرور وجود دارد و آیا این دستگاه می‌تواند آن را رمزگشایی کند. backup restore کلیدهای اتاق پشتیبان‌گیری‌شده را به مخزن رمزنگاری محلی وارد می‌کند؛ اگر کلید بازیابی از قبل روی دیسک است، --recovery-key-stdin را حذف کنید.

برای جایگزینی نسخه پشتیبان خراب با یک خط مبنای تازه (با پذیرش ازدست‌رفتن تاریخچه قدیمی بازیابی‌ناپذیر؛ همچنین می‌تواند در صورت بارگذاری‌نشدن داده محرمانه نسخه پشتیبان فعلی، ذخیره‌سازی محرمانه را دوباره ایجاد کند):

openclaw matrix verify backup reset --yes

فقط زمانی --rotate-recovery-key را اضافه کنید که کلید بازیابی قبلی عمداً نباید دیگر بتواند خط مبنای تازه نسخه پشتیبان را باز کند.

فهرست‌کردن، درخواست‌کردن و پاسخ‌دادن به راستی‌آزمایی‌ها

openclaw matrix verify list

درخواست‌های در انتظار راستی‌آزمایی برای حساب انتخاب‌شده را فهرست می‌کند.

openclaw matrix verify request --own-useropenclaw matrix verify request --user-id @ops:example.org --device-id ABCDEF

از این حساب یک درخواست راستی‌آزمایی ارسال می‌کند. --own-user خودراستی‌آزمایی را درخواست می‌کند (اعلان را در کلاینت دیگری از Matrix متعلق به همان کاربر بپذیرید)؛ --user-id/--device-id/--room-id شخص دیگری را هدف قرار می‌دهند. --own-user را نمی‌توان با سایر پرچم‌های هدف‌گیری ترکیب کرد.

برای مدیریت سطح پایین‌تر چرخه عمر ــ معمولاً هنگام دنبال‌کردن درخواست‌های ورودی از کلاینتی دیگر ــ این فرمان‌ها روی <id> مربوط به یک درخواست مشخص عمل می‌کنند (که توسط verify list و verify request نمایش داده می‌شود):

accept، start، sas، confirm-sas، mismatch-sas و cancel همگی --user-id و --room-id را به‌عنوان راهنمای پیگیری پیام مستقیم می‌پذیرند، وقتی راستی‌آزمایی به یک اتاق پیام مستقیم مشخص متصل است.

نکات چندحسابی

بدون --account <id>، فرمان‌های CLI مربوط به Matrix از حساب پیش‌فرض ضمنی استفاده می‌کنند. در صورت وجود چند حساب نام‌گذاری‌شده و نبود channels.matrix.defaultAccount، فرمان‌ها از حدس‌زدن خودداری می‌کنند و از شما می‌خواهند یکی را انتخاب کنید. وقتی E2EE برای یک حساب نام‌گذاری‌شده غیرفعال یا دردسترس‌نباشد، خطاها به کلید پیکربندی همان حساب اشاره می‌کنند؛ برای مثال channels.matrix.accounts.assistant.encryption.

openclaw matrix account add \--account assistant \--homeserver https://matrix.example.org \--user-id '@assistant:example.org' \--password '<password>' \--device-name OpenClaw-Gateway

openclaw matrix account add \--account assistant \--homeserver https://matrix.example.org \--access-token '<token>'

openclaw matrix devices listopenclaw matrix devices prune-stale

مدیریت نمایه

openclaw matrix profile set --name "OpenClaw Assistant"openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png

هر دو گزینه را در یک فراخوانی ارسال کنید. Matrix نشانی‌های آواتار mxc:// را مستقیماً می‌پذیرد؛ ارسال http:///https:// ابتدا فایل را بارگذاری می‌کند و نشانی حل‌شدهٔ mxc:// را در channels.matrix.avatarUrl (یا مقدار جایگزین مختص حساب) ذخیره می‌کند.

رشته‌ها

Matrix هم برای پاسخ‌های خودکار و هم برای ارسال‌های ابزار پیام از رشته‌های بومی پشتیبانی می‌کند. دو تنظیم مستقل رفتار را کنترل می‌کنند:

مسیریابی نشست (sessionScope)

‏dm.sessionScope تعیین می‌کند اتاق‌های پیام مستقیم Matrix چگونه به نشست‌های OpenClaw نگاشت شوند:

• "per-user" (پیش‌فرض): همهٔ اتاق‌های پیام مستقیم با همتای مسیریابی‌شدهٔ یکسان، یک نشست را به‌اشتراک می‌گذارند.
• "per-room": هر اتاق پیام مستقیم Matrix، حتی برای یک همتای یکسان، کلید نشست مخصوص خود را دریافت می‌کند.

اتصال‌های صریح مکالمه همیشه بر sessionScope اولویت دارند؛ اتاق‌ها و رشته‌های متصل، نشست مقصد انتخاب‌شدهٔ خود را حفظ می‌کنند.

رشته‌بندی پاسخ (threadReplies)

‏threadReplies تعیین می‌کند ربات پاسخ خود را کجا ارسال کند:

• "off": پاسخ‌ها در سطح اصلی هستند. پیام‌های ورودی رشته‌بندی‌شده در نشست والد باقی می‌مانند.
• "inbound": فقط زمانی درون یک رشته پاسخ داده می‌شود که پیام ورودی از قبل در همان رشته بوده باشد.
• "always": پاسخ درون رشته‌ای ارسال می‌شود که ریشهٔ آن پیام آغازگر است؛ آن مکالمه از نخستین آغازگر به بعد از طریق نشست منطبق و محدود به رشته مسیریابی می‌شود.

‏dm.threadReplies این رفتار را فقط برای پیام‌های مستقیم بازنویسی می‌کند؛ برای نمونه، رشته‌های اتاق را مجزا نگه می‌دارد، درحالی‌که پیام‌های مستقیم بدون رشته باقی می‌مانند.

وراثت رشته و فرمان‌های اسلش

• پیام‌های ورودی رشته‌بندی‌شده، پیام ریشهٔ رشته را به‌عنوان زمینهٔ اضافی عامل دربر می‌گیرند.
• ارسال‌های ابزار پیام هنگام هدف‌گیری همان اتاق (یا همان کاربر مقصد پیام مستقیم)، رشتهٔ کنونی Matrix را به‌طور خودکار به ارث می‌برند، مگر اینکه threadId صریحی ارائه شود.
• استفادهٔ مجدد از مقصد کاربر پیام مستقیم فقط زمانی فعال می‌شود که فرادادهٔ نشست کنونی، همان همتای پیام مستقیم را در همان حساب Matrix اثبات کند؛ در غیر این صورت OpenClaw به مسیریابی عادی محدود به کاربر بازمی‌گردد.
• /focus، /unfocus، /agents، /session idle، /session max-age و /acp spawn متصل به رشته، همگی در اتاق‌ها و پیام‌های مستقیم Matrix کار می‌کنند.
• /focus در سطح اصلی، هنگامی که threadBindings.spawnSessions فعال باشد، رشتهٔ جدیدی در Matrix ایجاد و آن را به نشست مقصد متصل می‌کند.
• اجرای /focus یا /acp spawn --thread here درون یک رشتهٔ موجود Matrix، همان رشته را در جای خود متصل می‌کند.

وقتی OpenClaw تشخیص دهد یک اتاق پیام مستقیم Matrix با اتاق پیام مستقیم دیگری در همان نشست مشترک تداخل دارد، یک‌بار m.notice را ارسال می‌کند که به راه گریز /focus اشاره دارد و تغییر dm.sessionScope را پیشنهاد می‌دهد. این اعلان فقط هنگامی ظاهر می‌شود که اتصال رشته‌ها فعال باشد.

اتصال‌های مکالمهٔ ACP

اتاق‌ها، پیام‌های مستقیم و رشته‌های موجود Matrix می‌توانند بدون تغییر سطح گفت‌وگو به فضاهای کاری ماندگار ACP تبدیل شوند.

روند سریع اپراتور:

• برای ادامهٔ استفاده، /acp spawn codex --bind here را در پیام مستقیم، اتاق یا رشتهٔ موجود Matrix اجرا کنید.
• در یک پیام مستقیم یا اتاق سطح اصلی، همان پیام مستقیم/اتاق به‌عنوان سطح گفت‌وگو باقی می‌ماند و پیام‌های آینده به نشست ACP ایجادشده مسیریابی می‌شوند.
• درون یک رشتهٔ موجود، --bind here همان رشتهٔ کنونی را در جای خود متصل می‌کند.
• /new و /reset همان نشست ACP متصل را در جای خود بازنشانی می‌کنند.
• /acp close نشست ACP را می‌بندد و اتصال را حذف می‌کند.

‏--bind here رشتهٔ فرزند Matrix ایجاد نمی‌کند. threadBindings.spawnSessions دسترسی به /acp spawn --thread auto|here را کنترل می‌کند؛ جایی که OpenClaw باید یک رشتهٔ فرزند ایجاد یا متصل کند.

پیکربندی اتصال رشته

Matrix پیش‌فرض‌های سراسری را از session.threadBindings به ارث می‌برد و از بازنویسی‌های مختص کانال پشتیبانی می‌کند:

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSessions: ایجاد رشته برای زیرفعامل و ACP را کنترل می‌کند.
• کلیدهای منسوخ threadBindings.spawnSubagentSessions / threadBindings.spawnAcpSessions توسط openclaw doctor --fix به spawnSessions مهاجرت داده می‌شوند.
• threadBindings.defaultSpawnContext

ایجاد نشست متصل به رشتهٔ Matrix به‌طور پیش‌فرض فعال است. برای جلوگیری از ایجاد/اتصال رشته‌های Matrix توسط /focus و /acp spawn --thread auto|here در سطح اصلی، threadBindings.spawnSessions: false را تنظیم کنید. اگر ایجاد رشتهٔ بومی زیرفعامل نباید رونوشت والد را منشعب کند، threadBindings.defaultSpawnContext: "isolated" را تنظیم کنید.

واکنش‌ها

Matrix از واکنش‌های خروجی، اعلان‌های واکنش ورودی و واکنش‌های تأیید پشتیبانی می‌کند.

ابزار واکنش خروجی توسط channels.matrix.actions.reactions کنترل می‌شود:

• react واکنشی به یک رویداد Matrix اضافه می‌کند.
• reactions خلاصهٔ کنونی واکنش‌ها را برای یک رویداد Matrix فهرست می‌کند.
• emoji="" واکنش‌های خود ربات را از آن رویداد حذف می‌کند.
• remove: true فقط واکنش ایموجی مشخص‌شده را از ربات حذف می‌کند.

ترتیب حل‌وفصل (نخستین مقدار تعریف‌شده برنده است):

‏reactionNotifications: "own" رویدادهای افزوده‌شدهٔ m.reaction را هنگامی که پیام‌های Matrix نوشته‌شده توسط ربات را هدف می‌گیرند، هدایت می‌کند؛ "off" رویدادهای سیستمی واکنش را غیرفعال می‌کند. حذف واکنش‌ها به رویدادهای سیستمی تبدیل نمی‌شود؛ Matrix آن‌ها را به‌صورت حذف محتوا نمایش می‌دهد، نه حذف‌های مستقل m.reaction.

زمینهٔ تاریخچه

• channels.matrix.historyLimit کنترل می‌کند هنگامی که یک پیام اتاق عامل را فعال می‌کند، چند پیام اخیر اتاق به‌عنوان InboundHistory گنجانده شوند. مقدار جایگزین آن messages.groupChat.historyLimit است؛ اگر هیچ‌یک تنظیم نشده باشند، پیش‌فرض مؤثر 0 است (غیرفعال).
• تاریخچهٔ اتاق Matrix فقط به همان اتاق محدود است؛ پیام‌های مستقیم همچنان از تاریخچهٔ عادی نشست استفاده می‌کنند.
• تاریخچهٔ اتاق فقط شامل موارد در انتظار است: OpenClaw پیام‌های اتاقی را که هنوز پاسخی را فعال نکرده‌اند در بافر نگه می‌دارد، سپس هنگام رسیدن یک اشاره یا آغازگر دیگر، از آن بازه تصویر لحظه‌ای می‌گیرد.
• پیام آغازگر کنونی در InboundHistory گنجانده نمی‌شود؛ برای آن نوبت در بدنهٔ اصلی ورودی باقی می‌ماند.
• تلاش‌های مجدد برای همان رویداد Matrix به‌جای حرکت روبه‌جلو به‌سوی پیام‌های جدیدتر اتاق، از تصویر لحظه‌ای اولیهٔ تاریخچه دوباره استفاده می‌کنند.

مشاهده‌پذیری زمینه

Matrix از کنترل مشترک contextVisibility برای زمینهٔ تکمیلی اتاق، مانند متن پاسخ واکشی‌شده، ریشه‌های رشته و تاریخچهٔ در انتظار، پشتیبانی می‌کند.

• contextVisibility: "all" پیش‌فرض است. زمینهٔ تکمیلی همان‌گونه که دریافت شده حفظ می‌شود.
• contextVisibility: "allowlist" زمینهٔ تکمیلی را به فرستندگانی محدود می‌کند که بررسی‌های فعال فهرست مجاز اتاق/کاربر به آن‌ها اجازه می‌دهد.
• contextVisibility: "allowlist_quote" مانند allowlist رفتار می‌کند، اما همچنان یک پاسخ نقل‌قول‌شدهٔ صریح را حفظ می‌کند.

این فقط بر مشاهده‌پذیری زمینهٔ تکمیلی اثر می‌گذارد، نه بر اینکه آیا خود پیام ورودی می‌تواند پاسخی را فعال کند. مجوز فعال‌سازی همچنان از groupPolicy، groups، groupAllowFrom و تنظیمات سیاست پیام مستقیم می‌آید.

سیاست پیام مستقیم و اتاق

{  channels: {    matrix: {      dm: {        policy: "allowlist",        allowFrom: ["@admin:example.org"],        threadReplies: "off",      },      groupPolicy: "allowlist",      groupAllowFrom: ["@admin:example.org"],      groups: {        "!roomid:example.org": { requireMention: true },      },    },  },}

برای بی‌صداکردن کامل پیام‌های مستقیم درحالی‌که اتاق‌ها همچنان کار می‌کنند، dm.enabled: false را تنظیم کنید:

{  channels: {    matrix: {      dm: { enabled: false },      groupPolicy: "allowlist",      groupAllowFrom: ["@admin:example.org"],    },  },}

برای رفتار محدودسازی بر اساس اشاره و فهرست مجاز، به گروه‌ها مراجعه کنید.

نمونهٔ جفت‌سازی برای پیام‌های مستقیم Matrix:

openclaw pairing list matrixopenclaw pairing approve matrix <CODE>

اگر کاربر تأییدنشدهٔ Matrix پیش از تأیید به ارسال پیام ادامه دهد، OpenClaw از همان کد جفت‌سازی در انتظار دوباره استفاده می‌کند و ممکن است پس از یک دورهٔ انتظار کوتاه، به‌جای ایجاد کد جدید یک پاسخ یادآوری ارسال کند.

برای جریان مشترک جفت‌سازی پیام مستقیم و چیدمان ذخیره‌سازی، به جفت‌سازی مراجعه کنید.

تعمیر اتاق مستقیم

اگر وضعیت پیام مستقیم منحرف شود، ممکن است OpenClaw با نگاشت‌های منسوخ m.direct مواجه شود که به‌جای پیام مستقیم فعال، به اتاق‌های انفرادی قدیمی اشاره می‌کنند. نگاشت کنونی یک همتا را بررسی کنید:

openclaw matrix direct inspect --user-id @alice:example.org

آن را تعمیر کنید:

openclaw matrix direct repair --user-id @alice:example.org

هر دو فرمان برای راه‌اندازی‌های چندحسابی، --account <id> را می‌پذیرند. روند تعمیر:

• یک پیام مستقیم سخت‌گیرانهٔ 1:1 را که از قبل در m.direct نگاشت شده ترجیح می‌دهد
• در صورت نبود آن، از هر پیام مستقیم سخت‌گیرانهٔ 1:1 که اکنون با آن کاربر به آن پیوسته شده استفاده می‌کند
• اگر پیام مستقیم سالمی وجود نداشته باشد، یک اتاق مستقیم تازه ایجاد و m.direct را بازنویسی می‌کند

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

تأییدهای اجرا

Matrix می‌تواند به‌عنوان کارخواه بومی تأیید عمل کند. آن را زیر channels.matrix.execApprovals (یا channels.matrix.accounts.<account>.execApprovals برای بازنویسی مختص حساب) پیکربندی کنید:

• enabled: تأییدها را از طریق درخواست‌های بومی Matrix تحویل می‌دهد. تنظیم‌نشده یا "auto"، پس از حل‌شدن دست‌کم یک تأییدکننده، به‌طور خودکار فعال می‌شود؛ برای غیرفعال‌سازی صریح، false را تنظیم کنید.
• approvers: شناسه‌های کاربر Matrix ‏(@owner:example.org) که مجازند درخواست‌های اجرا را تأیید کنند. مقدار جایگزین آن channels.matrix.dm.allowFrom است.
• target: مقصد درخواست‌ها. "dm" (پیش‌فرض) آن‌ها را به پیام‌های مستقیم تأییدکنندگان می‌فرستد؛ "channel" آن‌ها را به اتاق یا پیام مستقیم مبدأ می‌فرستد؛ "both" آن‌ها را به هر دو می‌فرستد.
• agentFilter / sessionFilter: فهرست‌های مجاز اختیاری برای تعیین عامل‌ها/نشست‌هایی که تحویل از طریق Matrix را فعال می‌کنند.

مجوزدهی میان انواع تأیید اندکی متفاوت است:

• تأییدهای اجرا از execApprovals.approvers استفاده می‌کنند و در صورت عدم دسترسی به dm.allowFrom بازمی‌گردند.
• تأییدهای Plugin فقط از طریق dm.allowFrom مجوز می‌دهند.

هر دو نوع، میان‌برهای واکنش Matrix و به‌روزرسانی پیام را به‌اشتراک می‌گذارند. تأییدکنندگان میان‌برهای واکنش زیر را روی پیام اصلی تأیید می‌بینند:

• ✅ یک‌بار اجازه بده
• ❌ رد کن
• ♾️ همیشه اجازه بده (وقتی خط‌مشی مؤثر اجرا آن را مجاز می‌داند)

دستورهای اسلش جایگزین: /approve <id> allow-once، /approve <id> allow-always، /approve <id> deny.

فقط تأییدکنندگان شناسایی‌شده می‌توانند تأیید یا رد کنند. تحویل کانالی برای تأییدهای اجرا شامل متن دستور است؛ channel یا both را فقط در اتاق‌های مورداعتماد فعال کنید.

مرتبط: تأییدهای اجرا.

دستورهای اسلش

دستورهای اسلش (/new، /reset، /model، /focus، /unfocus، /agents، /session، /acp، /approve و غیره) مستقیماً در پیام‌های خصوصی کار می‌کنند. در اتاق‌ها، OpenClaw دستورهایی را که با منشن Matrix خود ربات آغاز می‌شوند نیز تشخیص می‌دهد؛ بنابراین @bot:server /new بدون نیاز به regex سفارشی منشن، مسیر دستور را فعال می‌کند. این کار باعث می‌شود ربات به پست‌های اتاقی @mention /command که Element و کلاینت‌های مشابه هنگام تکمیل خودکار نام ربات با کلید Tab و پیش از تایپ دستور ارسال می‌کنند، پاسخ‌گو بماند.

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

چندحسابی

{  channels: {    matrix: {      enabled: true,      defaultAccount: "assistant",      dm: { policy: "pairing" },      accounts: {        assistant: {          homeserver: "https://matrix.example.org",          accessToken: "syt_assistant_xxx",          encryption: true,        },        alerts: {          homeserver: "https://matrix.example.org",          accessToken: "syt_alerts_xxx",          dm: {            policy: "allowlist",            allowFrom: ["@ops:example.org"],            threadReplies: "off",          },        },      },    },  },}

وراثت:

• مقادیر سطح بالای channels.matrix برای حساب‌های نام‌گذاری‌شده به‌عنوان پیش‌فرض عمل می‌کنند، مگر اینکه حساب آن‌ها را بازنویسی کند.
• با groups.<room>.account محدوده یک ورودی اتاق ارث‌بری‌شده را به حسابی مشخص محدود کنید. ورودی‌های بدون account بین حساب‌ها مشترک‌اند؛ وقتی حساب پیش‌فرض در سطح بالا پیکربندی شده باشد، account: "default" همچنان کار می‌کند.

انتخاب حساب پیش‌فرض:

• برای انتخاب حساب نام‌گذاری‌شده‌ای که مسیریابی ضمنی، کاوش و دستورهای CLI ترجیح می‌دهند، defaultAccount را تنظیم کنید.
• اگر چند حساب دارید و نام یکی از آن‌ها دقیقاً default است، OpenClaw حتی وقتی defaultAccount تنظیم نشده باشد، به‌طور ضمنی از آن استفاده می‌کند.
• در صورت وجود چند حساب نام‌گذاری‌شده و انتخاب‌نشدن حساب پیش‌فرض، دستورهای CLI از حدس‌زدن خودداری می‌کنند؛ defaultAccount را تنظیم کنید یا --account <id> را ارسال کنید.
• بلوک سطح بالای channels.matrix.* فقط زمانی حساب ضمنی default تلقی می‌شود که احراز هویت آن کامل باشد (homeserver + accessToken، یا homeserver + userId + password). وقتی اعتبارنامه‌های ذخیره‌شده احراز هویت را پوشش دهند، حساب‌های نام‌گذاری‌شده همچنان از طریق homeserver + userId قابل کشف‌اند.

ارتقا:

• وقتی OpenClaw هنگام تعمیر یا راه‌اندازی، پیکربندی تک‌حسابی را به چندحسابی ارتقا می‌دهد، اگر حساب نام‌گذاری‌شده‌ای وجود داشته باشد یا defaultAccount از قبل به یکی اشاره کند، همان حساب موجود را حفظ می‌کند. فقط کلیدهای احراز هویت/راه‌اندازی اولیه Matrix به حساب ارتقایافته منتقل می‌شوند؛ کلیدهای خط‌مشی تحویل مشترک در سطح بالا باقی می‌مانند.

برای الگوی مشترک چندحسابی به مرجع پیکربندی مراجعه کنید.

هوم‌سرورهای خصوصی/LAN

OpenClaw به‌طور پیش‌فرض برای محافظت در برابر SSRF، هوم‌سرورهای خصوصی/داخلی Matrix را مسدود می‌کند، مگر اینکه برای هر حساب صراحتاً اجازه دهید.

اگر هوم‌سرور شما روی localhost، یک IP متعلق به LAN/Tailscale یا یک نام میزبان داخلی اجرا می‌شود، network.dangerouslyAllowPrivateNetwork را برای آن حساب فعال کنید:

{  channels: {    matrix: {      homeserver: "http://matrix-synapse:8008",      network: {        dangerouslyAllowPrivateNetwork: true,      },      accessToken: "syt_internal_xxx",    },  },}

نمونه راه‌اندازی CLI:

openclaw matrix account add \  --account ops \  --homeserver http://matrix-synapse:8008 \  --allow-private-network \  --access-token syt_ops_xxx

این اجازه صریح فقط مقصدهای خصوصی/داخلی مورداعتماد را مجاز می‌کند. هوم‌سرورهای عمومی بدون رمزنگاری مانند http://matrix.example.org:8008 همچنان مسدود می‌مانند. هر زمان ممکن است https:// را ترجیح دهید.

پراکسی‌کردن ترافیک Matrix

اگر استقرار Matrix شما به پراکسی صریح HTTP(S) خروجی نیاز دارد، channels.matrix.proxy را تنظیم کنید:

{  channels: {    matrix: {      homeserver: "https://matrix.example.org",      accessToken: "syt_bot_xxx",      proxy: "http://127.0.0.1:7890",    },  },}

حساب‌های نام‌گذاری‌شده می‌توانند پیش‌فرض سطح بالا را با channels.matrix.accounts.<id>.proxy بازنویسی کنند. OpenClaw برای ترافیک زمان اجرای Matrix و کاوش‌های وضعیت حساب از همان تنظیم پراکسی استفاده می‌کند.

تفکیک مقصد

Matrix هرجا که OpenClaw مقصد اتاق یا کاربر درخواست کند، این قالب‌های مقصد را می‌پذیرد:

• کاربران: @user:server، user:@user:server یا matrix:user:@user:server
• اتاق‌ها: !room:server، room:!room:server یا matrix:room:!room:server
• نام‌های مستعار: #alias:server، channel:#alias:server یا matrix:channel:#alias:server

شناسه‌های اتاق Matrix به بزرگی و کوچکی حروف حساس‌اند. هنگام پیکربندی مقصدهای صریح تحویل، کارهای Cron، اتصال‌ها یا فهرست‌های مجاز، دقیقاً از همان بزرگی و کوچکی حروف شناسه اتاق در Matrix استفاده کنید. OpenClaw کلیدهای نشست داخلی را برای ذخیره‌سازی به‌شکل متعارف نگه می‌دارد؛ بنابراین آن کلیدهای حروف‌کوچک منبع قابل‌اعتمادی برای شناسه‌های تحویل Matrix نیستند.

جست‌وجوی زنده دایرکتوری از حساب Matrix واردشده استفاده می‌کند:

• جست‌وجوهای کاربر، دایرکتوری کاربران Matrix را روی همان هوم‌سرور جست‌وجو می‌کنند.
• جست‌وجوهای اتاق، شناسه‌ها و نام‌های مستعار صریح اتاق را مستقیماً می‌پذیرند. جست‌وجو بر اساس نام اتاق‌های پیوسته‌شده به‌صورت بهترین تلاش انجام می‌شود و فقط زمانی برای فهرست‌های مجاز اتاق در زمان اجرا اعمال می‌شود که dangerouslyAllowNameMatching: true تنظیم شده باشد.
• اگر نام اتاق به شناسه یا نام مستعار تفکیک نشود، هنگام تفکیک فهرست مجاز در زمان اجرا نادیده گرفته می‌شود.

مرجع پیکربندی

فیلدهای کاربری از نوع فهرست مجاز (groupAllowFrom، dm.allowFrom، groups.<room>.users) شناسه‌های کامل کاربر Matrix را می‌پذیرند که ایمن‌ترین گزینه‌اند. ورودی‌های غیرشناسه به‌طور پیش‌فرض نادیده گرفته می‌شوند. اگر dangerouslyAllowNameMatching: true تنظیم شده باشد، تطابق‌های دقیق نام نمایشی در دایرکتوری Matrix هنگام راه‌اندازی و هر بار تغییر فهرست مجاز در حین اجرای پایشگر تفکیک می‌شوند؛ ورودی‌های تفکیک‌ناپذیر در زمان اجرا نادیده گرفته می‌شوند.

کلیدهای فهرست مجاز اتاق (groups، rooms قدیمی) باید شناسه یا نام مستعار اتاق باشند. کلیدهای نام ساده اتاق به‌طور پیش‌فرض نادیده گرفته می‌شوند؛ dangerouslyAllowNameMatching: true جست‌وجوی بهترین‌تلاش در میان نام اتاق‌های پیوسته‌شده را بازیابی می‌کند.

حساب و اتصال

• enabled: کانال را فعال یا غیرفعال می‌کند.
• name: برچسب نمایشی اختیاری برای حساب.
• defaultAccount: شناسه حساب ترجیحی هنگامی که چند حساب Matrix پیکربندی شده‌اند.
• accounts: بازنویسی‌های نام‌گذاری‌شده برای هر حساب. مقادیر سطح بالای channels.matrix به‌عنوان پیش‌فرض به ارث می‌رسند.
• homeserver: نشانی URL هوم‌سرور، برای مثال https://matrix.example.org.
• network.dangerouslyAllowPrivateNetwork: به این حساب اجازه اتصال به localhost، IPهای LAN/Tailscale یا نام‌های میزبان داخلی را می‌دهد.
• proxy: نشانی URL اختیاری پراکسی HTTP(S) برای ترافیک Matrix. بازنویسی برای هر حساب پشتیبانی می‌شود.
• userId: شناسه کامل کاربر Matrix (@bot:example.org).
• accessToken: توکن دسترسی برای احراز هویت مبتنی بر توکن. مقادیر متن ساده و SecretRef در ارائه‌دهندگان env/file/exec پشتیبانی می‌شوند (مدیریت اسرار).
• password: گذرواژه برای ورود مبتنی بر گذرواژه. مقادیر متن ساده و SecretRef پشتیبانی می‌شوند.
• deviceId: شناسه صریح دستگاه Matrix.
• deviceName: نام نمایشی دستگاه که هنگام ورود با گذرواژه استفاده می‌شود.
• avatarUrl: نشانی URL ذخیره‌شده آواتار خود برای همگام‌سازی پروفایل و به‌روزرسانی‌های profile set.
• initialSyncLimit: حداکثر تعداد رویدادهایی که هنگام همگام‌سازی راه‌اندازی دریافت می‌شوند.

رمزنگاری

• encryption: رمزنگاری سرتاسری را فعال می‌کند. پیش‌فرض: false.
• startupVerification: "if-unverified" (پیش‌فرض هنگام فعال‌بودن رمزنگاری سرتاسری) یا "off". اگر این دستگاه تأیید نشده باشد، هنگام راه‌اندازی به‌طور خودکار درخواست خودتأییدی می‌دهد.
• startupVerificationCooldownHours: زمان انتظار پیش از درخواست خودکار بعدی هنگام راه‌اندازی. پیش‌فرض: 24.

دسترسی و خط‌مشی

• groupPolicy: "open"، "allowlist" یا "disabled". پیش‌فرض: "allowlist".
• groupAllowFrom: فهرست مجاز شناسه‌های کاربر برای ترافیک اتاق.
• mentionPatterns: الگوهای regex محدوده‌بندی‌شده برای منشن‌های اتاق. شیئی دارای { mode: "allow"|"deny", allowIn: [roomId, ...], denyIn: [roomId, ...] }. تعیین می‌کند که آیا agents.entries.*.groupChat.mentionPatterns پیکربندی‌شده برای هر اتاق اعمال شوند یا خیر.
• dm.enabled: وقتی false باشد، همه پیام‌های خصوصی را نادیده می‌گیرد. پیش‌فرض: true.
• dm.policy: "pairing" (پیش‌فرض)، "allowlist"، "open" یا "disabled". پس از پیوستن ربات و طبقه‌بندی اتاق به‌عنوان پیام خصوصی اعمال می‌شود؛ بر مدیریت دعوت تأثیری ندارد.
• dm.allowFrom: فهرست مجاز شناسه‌های کاربر برای ترافیک پیام خصوصی.
• dm.sessionScope: "per-user" (پیش‌فرض) یا "per-room".
• dm.threadReplies: بازنویسی مخصوص پیام خصوصی برای رشته‌بندی پاسخ‌ها ("off"، "inbound"، "always").
• allowBots: پیام‌های سایر حساب‌های پیکربندی‌شده ربات Matrix را می‌پذیرد (true یا "mentions").
• allowlistOnly: وقتی true باشد، همه خط‌مشی‌های فعال پیام خصوصی (به‌جز "disabled") و خط‌مشی‌های گروهی "open" را به‌اجبار روی "allowlist" قرار می‌دهد. خط‌مشی‌های "disabled" را تغییر نمی‌دهد.
• dangerouslyAllowNameMatching: وقتی true باشد، جست‌وجوی دایرکتوری بر اساس نام نمایشی Matrix را برای ورودی‌های فهرست مجاز کاربر و جست‌وجوی نام اتاق‌های پیوسته‌شده را برای کلیدهای فهرست مجاز اتاق فعال می‌کند. شناسه‌های کامل @user:server و شناسه‌ها یا نام‌های مستعار اتاق را ترجیح دهید.
• autoJoin: "always"، "allowlist" یا "off". پیش‌فرض: "off". برای هر دعوت Matrix، از جمله دعوت‌های شبیه پیام خصوصی، اعمال می‌شود.
• autoJoinAllowlist: اتاق‌ها/نام‌های مستعاری که وقتی autoJoin برابر با "allowlist" است مجازند. ورودی‌های نام مستعار در برابر هوم‌سرور تفکیک می‌شوند، نه در برابر وضعیتی که اتاق دعوت‌کننده ادعا کرده است.
• contextVisibility: قابلیت مشاهده زمینه تکمیلی ("all" پیش‌فرض، "allowlist"، "allowlist_quote").

رفتار پاسخ

• replyToMode: "off" (پیش‌فرض)، "first"، "all" یا "batched".
• threadReplies: "off" (پیش‌فرض سطح بالا، مگر آنکه صریحاً تنظیم شود، به "inbound" تبدیل می‌شود)، "inbound" یا "always".
• threadBindings: بازنویسی‌های مختص هر کانال برای مسیریابی و چرخهٔ عمر نشست‌های مقید به رشته.
• streaming: شیء تودرتوی { mode, chunkMode, block: { enabled, coalesce }, preview: { toolProgress }, progress: { label, labels, maxLines, maxLineChars, toolProgress } }. مقدار mode برابر است با "off" (پیش‌فرض)، "partial"، "quiet" یا "progress". نگارش‌های اسکالر/بولی قدیمی از طریق openclaw doctor --fix مهاجرت می‌کنند.
• streaming.block.enabled: وقتی true باشد، بلوک‌های تکمیل‌شدهٔ دستیار به‌صورت پیام‌های پیشرفت جداگانه نگه داشته می‌شوند. پیش‌فرض: false.
• markdown: پیکربندی اختیاری رندر Markdown برای متن خروجی.
• responsePrefix: رشتهٔ اختیاری که به ابتدای پاسخ‌های خروجی افزوده می‌شود.
• textChunkLimit: اندازهٔ قطعهٔ خروجی برحسب نویسه هنگام streaming.chunkMode: "length". پیش‌فرض: 4000.
• streaming.chunkMode: "length" (پیش‌فرض، جداسازی براساس تعداد نویسه‌ها) یا "newline" (جداسازی در مرز خطوط).
• historyLimit: تعداد پیام‌های اخیر اتاق که وقتی پیامی در اتاق عامل را فعال می‌کند، به‌عنوان InboundHistory گنجانده می‌شوند. در صورت نبود مقدار، از messages.groupChat.historyLimit استفاده می‌شود؛ پیش‌فرض مؤثر 0 (غیرفعال) است.
• mediaMaxMb: سقف اندازهٔ رسانه برحسب MB برای ارسال‌های خروجی و پردازش ورودی. پیش‌فرض: 20.

تنظیمات واکنش

• ackReaction: بازنویسی واکنش تأیید دریافت برای این کانال/حساب.
• ackReactionScope: بازنویسی دامنه ("group-mentions" پیش‌فرض، "group-all"، "direct"، "all"، "none"، "off").
• reactionNotifications: حالت اعلان واکنش ورودی ("own" پیش‌فرض، "off").

ابزارها و بازنویسی‌های مختص هر اتاق

• actions: کنترل دسترسی ابزار برای هر کنش (messages، reactions، pins، profile، memberInfo، channelInfo، verification).
• groups: نگاشت خط‌مشی مختص هر اتاق. هویت نشست پس از تفکیک، از شناسهٔ پایدار اتاق استفاده می‌کند. (rooms یک نام مستعار قدیمی است.)
  • groups.<room>.account: محدودکردن یک ورودی اتاق ارث‌بری‌شده به حسابی مشخص.
  • groups.<room>.enabled: کلید روشن/خاموش مختص هر اتاق. وقتی false باشد، اتاق چنان نادیده گرفته می‌شود که گویی در نگاشت وجود ندارد.
  • groups.<room>.requireMention: بازنویسی الزام اشاره در سطح کانال برای هر اتاق.
  • groups.<room>.allowBots: بازنویسی تنظیم سطح کانال برای هر اتاق (true یا "mentions").
  • groups.<room>.botLoopProtection: بازنویسی بودجهٔ محافظت از حلقهٔ بات‌به‌بات برای هر اتاق.
  • groups.<room>.users: فهرست مجاز فرستندگان برای هر اتاق.
  • groups.<room>.tools: بازنویسی‌های مجاز/غیرمجاز ابزار برای هر اتاق.
  • groups.<room>.autoReply: بازنویسی کنترل اشاره برای هر اتاق. true الزامات اشاره را برای آن اتاق غیرفعال می‌کند؛ false آن‌ها را دوباره اجباری می‌کند.
  • groups.<room>.skills: فیلتر Skills برای هر اتاق.
  • groups.<room>.systemPrompt: قطعهٔ اعلان سیستمی برای هر اتاق.

تنظیمات تأیید Exec

• execApprovals.enabled: ارائهٔ تأییدهای Exec از طریق اعلان‌های بومی Matrix.
• execApprovals.approvers: شناسه‌های کاربری Matrix که اجازهٔ تأیید دارند. در صورت نبود مقدار، از dm.allowFrom استفاده می‌شود.
• execApprovals.target: "dm" (پیش‌فرض)، "channel" یا "both".
• execApprovals.agentFilter / execApprovals.sessionFilter: فهرست‌های مجاز اختیاری عامل/نشست برای تحویل.

مرتبط

• نمای کلی کانال‌ها - همهٔ کانال‌های پشتیبانی‌شده
• جفت‌سازی - احراز هویت پیام مستقیم و جریان جفت‌سازی
• گروه‌ها - رفتار گفت‌وگوی گروهی و کنترل اشاره
• مسیریابی کانال - مسیریابی نشست برای پیام‌ها
• امنیت - مدل دسترسی و مقاوم‌سازی