ماتریس

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

نصب

openclaw plugins install @openclaw/matrix

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

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

راه‌اندازی

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

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

openclaw channels addopenclaw configure --section channels

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

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

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

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

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

{  channels: {    matrix: {      enabled: true,      homeserver: "https://matrix.example.org",      userId: "@bot:example.org",      password: "replace-me", // pragma: allowlist secret      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، نام مستعار قدیمی rooms): از !room:server یا #alias:server استفاده کنید. نام‌های ساده نادیده گرفته می‌شوند، مگر اینکه dangerouslyAllowNameMatching: true باشد.
• فهرست‌های مجاز دعوت (autoJoinAllowlist): از !room:server، #alias:server یا * استفاده کنید. نام‌های ساده همیشه رد می‌شوند.

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

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

اطلاعات احراز هویت ذخیره‌شده در حافظهٔ نهان

Matrix اطلاعات احراز هویت را در ~/.openclaw/credentials/matrix/ ذخیره می‌کند: credentials.json برای حساب پیش‌فرض و credentials-<account>.json برای حساب‌های نام‌گذاری‌شده. وقتی اطلاعات احراز هویت ذخیره‌شده وجود داشته باشد، OpenClaw حتی بدون وجود accessToken در فایل پیکربندی، Matrix را پیکربندی‌شده در نظر می‌گیرد؛ این وضعیت راه‌اندازی، openclaw doctor و بررسی‌های وضعیت کانال را پوشش می‌دهد.

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

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

برای حساب ops، نام‌ها به MATRIX_OPS_HOMESERVER، MATRIX_OPS_ACCESS_TOKEN و مانند آن تبدیل می‌شوند. MATRIX_HOMESERVER و هر گونهٔ محدودشدهٔ *_HOMESERVER را نمی‌توان از فایل .env فضای کاری تنظیم کرد؛ به فایل‌های .env فضای کاری مراجعه کنید.

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

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

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

پیش‌نمایش‌های جریانی

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

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

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

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

قالب کامل شیء، { mode, preview, progress } را می‌پذیرد:

{  channels: {    matrix: {      streaming: {        mode: "progress",        progress: {          label: "auto", // pick from configured or built-in labels (false to hide)          labels: ["Thinking", "Writing", "Searching"], // candidates for label: "auto"          maxLines: 8, // max rolling progress lines (default: 8)          maxLineChars: 120, // max chars per line before truncation (default: 120)          toolProgress: true, // show tool/progress activity (default: true)        },      },    },  },}

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

blockStreaming (با مقدار پیش‌فرض false) مستقل از streaming است:

نکات:

• اگر اندازهٔ پیش‌نمایش از محدودیت اندازهٔ هر رویداد Matrix عبور کند، OpenClaw جریان پیش‌نمایش را متوقف می‌کند و به ارسال صرفاً نهایی بازمی‌گردد.
• پاسخ‌های رسانه‌ای همیشه پیوست‌ها را به‌شکل عادی ارسال می‌کنند؛ اگر نتوان از پیش‌نمایش قدیمی با اطمینان دوباره استفاده کرد، OpenClaw پیش از ارسال پاسخ رسانه‌ای نهایی آن را حذف می‌کند.
• به‌روزرسانی‌های پیش‌نمایش پیشرفت ابزار، هنگام فعال‌بودن جریان پیش‌نمایش به‌طور پیش‌فرض روشن هستند. برای حفظ ویرایش‌های پیش‌نمایش متن پاسخ و نگه‌داشتن پیشرفت ابزار در مسیر ارسال عادی، streaming.preview.toolProgress: false را تنظیم کنید.
• ویرایش‌های پیش‌نمایش، فراخوانی‌های اضافی Matrix API مصرف می‌کنند. برای محافظه‌کارانه‌ترین الگوی محدودیت نرخ، streaming: "off" را حفظ کنید.

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

یادداشت‌های صوتی ورودی 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: "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 setup

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

• --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 کار می‌کنند.
• وقتی threadBindings.spawnSessions فعال باشد، اجرای /focus در سطح اصلی یک رشتهٔ جدید Matrix ایجاد و آن را به نشست مقصد متصل می‌کند.
• اجرای /focus یا /acp spawn --thread here داخل یک رشتهٔ موجود Matrix، همان رشته را در جای خود متصل می‌کند.

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

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

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

روند سریع برای گرداننده:

• در پیام مستقیم، اتاق یا رشتهٔ موجود Matrix که می‌خواهید همچنان استفاده کنید، /acp spawn codex --bind here را اجرا کنید.
• در یک پیام مستقیم یا اتاق سطح اصلی، همان پیام مستقیم/اتاق فعلی به‌عنوان سطح گفت‌وگو باقی می‌ماند و پیام‌های آینده به نشست 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: بازنویسی‌های محدودتر برای ایجادهای مختص زیرعامل یا مختص ACP.
• 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> را می‌پذیرند. روند ترمیم:

• یک پیام مستقیم دقیقاً دونفره را که از قبل در m.direct نگاشت شده ترجیح می‌دهد
• در صورت نبود آن، به هر پیام مستقیم دقیقاً دونفره‌ای که در حال حاضر با آن کاربر به آن پیوسته‌اید بازمی‌گردد
• اگر پیام مستقیم سالمی وجود نداشته باشد، یک اتاق مستقیم جدید ایجاد و 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 بدون عبارت منظم سفارشی برای اشاره، مسیر فرمان را فعال می‌کند. این کار باعث می‌شود ربات به پیام‌های اتاقی به‌شکل @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" همچنان کار می‌کند.

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

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

ارتقا:

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

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

سرورهای خانگی خصوصی/شبکه محلی

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

اگر سرور خانگی شما روی localhost، یک IP شبکه محلی/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 را در همان homeserver پرس‌وجو می‌کند.
• جست‌وجوی اتاق‌ها، شناسه‌ها و نام‌های مستعار صریح اتاق را مستقیماً می‌پذیرد. جست‌وجو بر اساس نام اتاق‌های پیوسته‌شده به‌صورت بهترین‌تلاش انجام می‌شود و فقط زمانی برای فهرست‌های مجاز اتاق در زمان اجرا کاربرد دارد که dangerouslyAllowNameMatching: true تنظیم شده باشد.
• اگر نام یک اتاق به شناسه یا نام مستعار تبدیل نشود، در تفکیک فهرست مجاز زمان اجرا نادیده گرفته می‌شود.

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

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

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

حساب و اتصال

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

رمزنگاری

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

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

• groupPolicy: "open"، "allowlist" یا "disabled". پیش‌فرض: "allowlist".
• groupAllowFrom: فهرست مجاز شناسه‌های کاربر برای ترافیک اتاق.
• mentionPatterns: الگوهای عبارت منظم محدوده‌دار برای اشاره‌ها در اتاق. شیئی با ساختار { mode: "allow"|"deny", allowIn: [roomId, ...], denyIn: [roomId, ...] }. کنترل می‌کند که آیا agents.list[].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: اتاق‌ها/نام‌های مستعاری که هنگام "allowlist" بودن autoJoin مجازند. ورودی‌های نام مستعار در برابر homeserver تفکیک می‌شوند، نه در برابر وضعیتی که اتاق دعوت‌کننده ادعا کرده است.
• contextVisibility: میزان مشاهده‌پذیری زمینه تکمیلی ("all" پیش‌فرض، "allowlist"، "allowlist_quote").

رفتار پاسخ

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

تنظیمات تأیید اجرای فرمان

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

مرتبط

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