Matrix

Matrix เป็น channel plugin ที่ดาวน์โหลดได้ (@openclaw/matrix) ซึ่งสร้างขึ้นบน matrix-js-sdk อย่างเป็นทางการ รองรับ DM, ห้อง, เธรด, สื่อ, รีแอ็กชัน, แบบสำรวจ, ตำแหน่งที่ตั้ง และ 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 แยกต่างหาก channel จะยังไม่ทำงานจนกว่าจะกำหนดค่าตามด้านล่าง ดูกฎการติดตั้งทั่วไปได้ที่ Plugin

การตั้งค่า

1. สร้างบัญชี Matrix บน homeserver ของคุณ
2. กำหนดค่า channels.matrix ด้วย homeserver + accessToken หรือ homeserver + userId + password
3. รีสตาร์ต Gateway
4. เริ่ม DM กับบอต หรือเชิญบอตเข้าห้อง คำเชิญใหม่จะมีผลก็ต่อเมื่อ autoJoin อนุญาต

การตั้งค่าแบบโต้ตอบ

openclaw channels addopenclaw configure --section channels

วิซาร์ดจะขอ URL ของ homeserver, วิธีการยืนยันตัวตน (โทเค็นหรือรหัสผ่าน), ID ผู้ใช้ (เฉพาะการยืนยันตัวตนด้วยรหัสผ่าน), ชื่ออุปกรณ์ซึ่งไม่บังคับ, ต้องการเปิดใช้ E2EE หรือไม่ และการเข้าถึงห้อง/การเข้าร่วมอัตโนมัติ หากมีตัวแปรสภาพแวดล้อม MATRIX_* ที่ตรงกันอยู่แล้วและบัญชียังไม่มีข้อมูลยืนยันตัวตนที่บันทึกไว้ วิซาร์ดจะเสนอตัวเลือกทางลัดผ่านตัวแปรสภาพแวดล้อม แปลงชื่อห้องก่อนบันทึกรายการอนุญาตด้วย openclaw channels resolve --channel matrix "Project Room" การเปิดใช้ E2EE ในวิซาร์ดจะเรียกใช้กระบวนการเริ่มต้นเดียวกับ 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": บอตจะไม่ปรากฏในห้องหรือ DM ใหม่จากคำเชิญใหม่จนกว่าคุณจะเข้าร่วมด้วยตนเอง OpenClaw ไม่สามารถระบุได้ในเวลาที่ได้รับคำเชิญว่าคำเชิญนั้นเป็น DM หรือกลุ่ม ดังนั้นทุกคำเชิญจะผ่าน autoJoin ก่อน ส่วน dm.policy จะมีผลภายหลังเท่านั้น เมื่อบอตเข้าร่วมและระบบจำแนกห้องแล้ว

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

รูปแบบเป้าหมายของรายการอนุญาต

• DM (dm.allowFrom, groupAllowFrom, groups.<room>.users): ใช้ @user:server โดยค่าเริ่มต้นระบบจะไม่พิจารณาชื่อที่แสดง (เนื่องจากเปลี่ยนแปลงได้) ให้ตั้งค่า dangerouslyAllowNameMatching: true เฉพาะเมื่อต้องการความเข้ากันได้กับชื่อที่แสดงอย่างชัดเจน
• คีย์รายการอนุญาตของห้อง (groups, alias เดิม rooms): ใช้ !room:server หรือ #alias:server ระบบจะไม่พิจารณาชื่อแบบธรรมดา เว้นแต่ dangerouslyAllowNameMatching: true
• รายการอนุญาตสำหรับคำเชิญ (autoJoinAllowlist): ใช้ !room:server, #alias:server หรือ * ระบบจะปฏิเสธชื่อแบบธรรมดาเสมอ

การปรับ ID บัญชีให้เป็นรูปแบบมาตรฐาน

วิซาร์ดจะแปลงชื่อที่อ่านง่ายเป็น ID บัญชีในรูปแบบมาตรฐาน (Ops Bot -> ops-bot) เครื่องหมายวรรคตอนจะถูก escape แบบเลขฐานสิบหกในชื่อตัวแปรสภาพแวดล้อมที่มีขอบเขต เพื่อป้องกันบัญชีชนกัน: - (0x2D) จะกลายเป็น _X2D_ ดังนั้น ops-prod จึงแมปกับคำนำหน้าตัวแปรสภาพแวดล้อม MATRIX_OPS_X2D_PROD_

ข้อมูลยืนยันตัวตนที่แคชไว้

Matrix แคชข้อมูลยืนยันตัวตนของบัญชีไว้ในสถานะ Plugin state/openclaw.sqlite ที่ใช้ร่วมกัน เมื่อมีข้อมูลยืนยันตัวตนที่แคชไว้ OpenClaw จะถือว่า Matrix ได้รับการกำหนดค่าแล้ว แม้ไม่มี accessToken ในไฟล์การกำหนดค่า ซึ่งครอบคลุมการตั้งค่า, openclaw doctor และการตรวจสอบสถานะ channel การอัปเกรดจะนำเข้าไฟล์ ~/.openclaw/credentials/matrix/credentials*.json ที่เลิกใช้แล้วผ่าน openclaw doctor --fix ตรวจสอบแถวข้อมูลใน SQLite แล้วจึงเก็บไฟล์เข้าคลัง

ตัวแปรสภาพแวดล้อม

ตัวแปรสภาพแวดล้อมที่อิงคีย์การกำหนดค่า ซึ่งจะใช้เมื่อไม่ได้ตั้งค่าคีย์การกำหนดค่าที่เทียบเท่ากัน บัญชีเริ่มต้นใช้ชื่อที่ไม่มีคำนำหน้า ส่วนบัญชีที่มีชื่อจะแทรกโทเค็นบัญชีก่อนส่วนต่อท้าย (ดู การปรับให้เป็นรูปแบบมาตรฐาน)

สำหรับบัญชี ops ชื่อจะกลายเป็น MATRIX_OPS_HOMESERVER, MATRIX_OPS_ACCESS_TOKEN และอื่น ๆ ไม่สามารถตั้งค่า MATRIX_HOMESERVER (รวมถึงรูปแบบที่มีขอบเขต *_HOMESERVER ใด ๆ) จาก .env ของ workspace ได้ โปรดดู ไฟล์ .env ของ workspace

ตัวอย่างการกำหนดค่า

ค่าพื้นฐานที่ใช้งานได้จริงพร้อมการจับคู่ DM, รายการอนุญาตของห้อง และ 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" },    },  },}

ตัวอย่างคำตอบแบบสตรีม

การสตรีมคำตอบของ 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", // 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 (ค่าเริ่มต้น) กิจกรรมเครื่องมือ/ความคืบหน้าแบบสดจะปรากฏในฉบับร่าง

streaming.block.enabled (ค่าเริ่มต้น false) เป็นอิสระจาก streaming.mode:

หมายเหตุ:

• หากตัวอย่างมีขนาดเกินขีดจำกัดต่อเหตุการณ์ของ Matrix OpenClaw จะหยุดสตรีมตัวอย่างและเปลี่ยนไปส่งเฉพาะผลลัพธ์สุดท้าย
• คำตอบที่มีสื่อจะส่งไฟล์แนบตามปกติเสมอ หากไม่สามารถนำตัวอย่างเก่ากลับมาใช้ได้อย่างปลอดภัย OpenClaw จะลบตัวอย่างนั้นก่อนส่งคำตอบสื่อขั้นสุดท้าย
• การอัปเดตตัวอย่างความคืบหน้าของเครื่องมือจะเปิดอยู่โดยค่าเริ่มต้นเมื่อเปิดใช้การสตรีมตัวอย่าง ตั้งค่า streaming.preview.toolProgress: false เพื่อคงการแก้ไขตัวอย่างสำหรับข้อความคำตอบไว้ แต่ให้ความคืบหน้าของเครื่องมือใช้เส้นทางการส่งตามปกติ
• การแก้ไขตัวอย่างทำให้มีการเรียก Matrix API เพิ่มขึ้น ปล่อย streaming.mode: "off" ไว้เพื่อใช้โปรไฟล์จำกัดอัตราที่ระมัดระวังที่สุด
• ค่า streaming แบบ scalar/boolean เดิม และคีย์แบบแบน blockStreaming / chunkMode จะถูกเขียนใหม่เป็นโครงสร้างซ้อนนี้โดย openclaw doctor --fix

ข้อความเสียง

โน้ตเสียง Matrix ขาเข้าจะถูกถอดเสียงก่อนผ่านเกตการกล่าวถึงของห้อง ดังนั้นโน้ตเสียงที่พูดชื่อบอตจึงสามารถเรียกใช้เอเจนต์ในห้อง requireMention: true ได้ และเอเจนต์จะได้รับข้อความถอดเสียงแทนที่จะได้รับเพียงตัวยึดตำแหน่งไฟล์แนบเสียง

Matrix ใช้ผู้ให้บริการสื่อเสียงที่ใช้ร่วมกันภายใต้ tools.media.audio เช่น OpenAI gpt-4o-mini-transcribe ดูการตั้งค่าผู้ให้บริการและขีดจำกัดได้ที่ ภาพรวมเครื่องมือสื่อ

• เหตุการณ์ 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 อื่นที่กำหนดค่าไว้ในห้องและ DM ที่อนุญาต
• allowBots: "mentions" ยอมรับข้อความเหล่านั้นเฉพาะเมื่อมีการกล่าวถึงบอตนี้อย่างชัดเจนในห้อง ส่วน DM ยังคงได้รับอนุญาตไม่ว่าในกรณีใด
• 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 อ่านคีย์กู้คืนจาก 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 รายงานสัญญาณความน่าเชื่อถืออิสระ 3 รายการ (--verbose แสดงทั้งหมด):

• Locally trusted: ได้รับความเชื่อถือจากไคลเอนต์นี้เท่านั้น
• Cross-signing verified: SDK รายงานการยืนยันผ่านการลงนามข้าม
• Signed by owner: ลงนามโดยคีย์ลงนามตนเองของคุณ (เพื่อการวินิจฉัยเท่านั้น)

Verified by owner จะเป็น yes ก็ต่อเมื่อ Cross-signing verified เป็น yes เท่านั้น ความเชื่อถือภายในเครื่องหรือลายเซ็นของเจ้าของเพียงอย่างเดียวยังไม่เพียงพอ

--allow-degraded-local-state ส่งคืนการวินิจฉัยอย่างเต็มความสามารถโดยไม่ต้องเตรียมบัญชี Matrix ก่อน เหมาะสำหรับการตรวจสอบแบบออฟไลน์หรือการกำหนดค่าที่ยังไม่สมบูรณ์

ยืนยันอุปกรณ์นี้ด้วยคีย์กู้คืน

ส่งคีย์กู้คืนผ่าน stdin แทนการส่งผ่านบรรทัดคำสั่ง:

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

คำสั่งจะรายงาน 3 สถานะ:

• 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

คำสั่งซ่อมแซม/ตั้งค่าสำหรับบัญชีที่เข้ารหัส โดยจะดำเนินการตามลำดับดังนี้:

• เริ่มต้นพื้นที่จัดเก็บข้อมูลลับ โดยนำคีย์กู้คืนที่มีอยู่มาใช้ซ้ำเมื่อทำได้
• เริ่มต้นการลงนามข้ามและอัปโหลดกุญแจสาธารณะที่ขาดหายไป
• ทำเครื่องหมายและลงนามข้ามให้อุปกรณ์ปัจจุบัน
• สร้างข้อมูลสำรองคีย์ห้องฝั่งเซิร์ฟเวอร์ หากยังไม่มีอยู่

หากโฮมเซิร์ฟเวอร์กำหนดให้ใช้ 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 ทั้งหมด เพื่อใช้เป็นคำแนะนำติดตามผลทาง DM เมื่อการยืนยันยึดโยงกับห้องข้อความโดยตรงที่ระบุ

หมายเหตุเกี่ยวกับหลายบัญชี

หากไม่มี --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 ยอมรับ URL รูปประจำตัว mxc:// โดยตรง ส่วนการส่ง http:///https:// จะอัปโหลดไฟล์ก่อน แล้วบันทึก URL mxc:// ที่แปลงแล้วลงใน channels.matrix.avatarUrl (หรือค่าที่เขียนทับสำหรับแต่ละบัญชี)

เธรด

Matrix รองรับเธรดแบบเนทีฟทั้งสำหรับการตอบกลับอัตโนมัติและการส่งด้วยเครื่องมือข้อความ การทำงานควบคุมด้วยการตั้งค่าอิสระสองรายการ:

การกำหนดเส้นทางเซสชัน (sessionScope)

dm.sessionScope กำหนดวิธีจับคู่ห้อง DM ของ Matrix กับเซสชัน OpenClaw:

• "per-user" (ค่าเริ่มต้น): ห้อง DM ทั้งหมดที่มีคู่สนทนาซึ่งกำหนดเส้นทางเดียวกันจะใช้เซสชันร่วมกัน
• "per-room": ห้อง DM ของ Matrix แต่ละห้องจะได้รับคีย์เซสชันของตนเอง แม้จะเป็นคู่สนทนาคนเดียวกัน

การเชื่อมโยงบทสนทนาแบบชัดเจนมีลำดับความสำคัญเหนือ sessionScope เสมอ ห้องและเธรดที่เชื่อมโยงแล้วจะคงเซสชันเป้าหมายที่เลือกไว้

การตอบกลับแบบเธรด (threadReplies)

threadReplies กำหนดตำแหน่งที่บอตโพสต์คำตอบ:

• "off": คำตอบจะอยู่ที่ระดับบนสุด ข้อความขาเข้าในเธรดจะยังคงอยู่ในเซสชันหลัก
• "inbound": ตอบภายในเธรดเฉพาะเมื่อข้อความขาเข้าอยู่ในเธรดนั้นอยู่แล้ว
• "always": ตอบภายในเธรดที่มีข้อความกระตุ้นเป็นราก โดยบทสนทนานั้นจะกำหนดเส้นทางผ่านเซสชันที่มีขอบเขตระดับเธรดซึ่งตรงกัน ตั้งแต่การกระตุ้นครั้งแรกเป็นต้นไป

dm.threadReplies เขียนทับค่านี้สำหรับ DM เท่านั้น เช่น แยกเธรดของห้องออกจากกัน แต่คง DM ไว้แบบไม่แยกเธรด

การสืบทอดเธรดและคำสั่งสแลช

• ข้อความขาเข้าในเธรดจะรวมข้อความรากของเธรดเป็นบริบทเพิ่มเติมสำหรับเอเจนต์
• การส่งด้วยเครื่องมือข้อความจะสืบทอดเธรด Matrix ปัจจุบันโดยอัตโนมัติเมื่อกำหนดเป้าหมายเป็นห้องเดียวกัน (หรือเป้าหมายผู้ใช้ DM คนเดียวกัน) เว้นแต่จะระบุ threadId อย่างชัดเจน
• การนำเป้าหมายผู้ใช้ DM กลับมาใช้จะทำงานเฉพาะเมื่อข้อมูลเมตาของเซสชันปัจจุบันยืนยันว่าเป็นคู่สนทนา DM คนเดียวกันในบัญชี Matrix เดียวกัน มิฉะนั้น OpenClaw จะกลับไปใช้การกำหนดเส้นทางตามขอบเขตผู้ใช้ตามปกติ
• /focus, /unfocus, /agents, /session idle, /session max-age และ /acp spawn ที่เชื่อมโยงกับเธรด ล้วนทำงานได้ในห้องและ DM ของ Matrix
• /focus ระดับบนสุดจะสร้างเธรด Matrix ใหม่และเชื่อมโยงกับเซสชันเป้าหมายเมื่อเปิดใช้งาน threadBindings.spawnSessions
• การเรียกใช้ /focus หรือ /acp spawn --thread here ภายในเธรด Matrix ที่มีอยู่จะเชื่อมโยงเธรดนั้น ณ ตำแหน่งเดิม

เมื่อ OpenClaw ตรวจพบว่าห้อง DM ของ Matrix ขัดแย้งกับห้อง DM อื่นในเซสชันที่ใช้ร่วมกันเดียวกัน ระบบจะโพสต์ m.notice เพียงครั้งเดียว โดยชี้ไปยังทางออก /focus และแนะนำให้เปลี่ยน dm.sessionScope การแจ้งเตือนนี้จะปรากฏเฉพาะเมื่อเปิดใช้งานการเชื่อมโยงเธรด

การเชื่อมโยงบทสนทนา ACP

ห้อง DM และเธรด Matrix ที่มีอยู่สามารถกลายเป็นพื้นที่ทำงาน ACP แบบถาวรได้โดยไม่ต้องเปลี่ยนพื้นผิวการแชต

ขั้นตอนด่วนสำหรับผู้ปฏิบัติงาน:

• เรียกใช้ /acp spawn codex --bind here ภายใน DM ห้อง หรือเธรด Matrix ที่มีอยู่เพื่อใช้งานต่อ
• ใน DM หรือห้องระดับบนสุด DM/ห้องปัจจุบันจะยังคงเป็นพื้นผิวการแชต และข้อความในอนาคตจะถูกกำหนดเส้นทางไปยังเซสชัน 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 ที่เลิกใช้แล้วจะถูกย้ายไปยัง spawnSessions โดย openclaw doctor --fix
• threadBindings.defaultSpawnContext

การสร้างเซสชันที่เชื่อมโยงกับเธรด Matrix จะเปิดใช้งานเป็นค่าเริ่มต้น ตั้งค่า threadBindings.spawnSessions: false เพื่อป้องกันไม่ให้ /focus และ /acp spawn --thread auto|here ระดับบนสุดสร้างหรือเชื่อมโยงเธรด Matrix ตั้งค่า 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 จำกัดอยู่เฉพาะในห้อง ส่วน DM ยังคงใช้ประวัติเซสชันตามปกติ
• ประวัติห้องเก็บเฉพาะข้อความที่รอดำเนินการ: OpenClaw จะบัฟเฟอร์ข้อความในห้องที่ยังไม่กระตุ้นคำตอบ แล้วสร้างสแนปช็อตของช่วงนั้นเมื่อมีการกล่าวถึงหรือสิ่งกระตุ้นอื่นเข้ามา
• ข้อความกระตุ้นปัจจุบันจะไม่รวมอยู่ใน InboundHistory แต่จะยังคงอยู่ในเนื้อหาขาเข้าหลักสำหรับรอบนั้น
• การลองประมวลผลเหตุการณ์ Matrix เดิมอีกครั้งจะใช้สแนปช็อตประวัติเดิมซ้ำ แทนที่จะเลื่อนไปยังข้อความใหม่กว่าในห้อง

การมองเห็นบริบท

Matrix รองรับการควบคุม contextVisibility ที่ใช้ร่วมกันสำหรับบริบทเพิ่มเติมของห้อง เช่น ข้อความตอบกลับที่ดึงมา รากของเธรด และประวัติที่รอดำเนินการ

• contextVisibility: "all" เป็นค่าเริ่มต้น บริบทเพิ่มเติมจะคงไว้ตามที่ได้รับ
• contextVisibility: "allowlist" กรองบริบทเพิ่มเติมให้เหลือเฉพาะผู้ส่งที่ได้รับอนุญาตจากการตรวจสอบรายการอนุญาตของห้อง/ผู้ใช้ที่ใช้งานอยู่
• contextVisibility: "allowlist_quote" ทำงานเหมือน allowlist แต่ยังคงเก็บคำตอบที่อ้างอิงอย่างชัดเจนไว้หนึ่งรายการ

การตั้งค่านี้มีผลเฉพาะต่อการมองเห็นบริบทเพิ่มเติม ไม่ได้กำหนดว่าข้อความขาเข้าเองจะกระตุ้นคำตอบได้หรือไม่ การอนุญาตให้กระตุ้นยังคงมาจาก groupPolicy, groups, groupAllowFrom และการตั้งค่านโยบาย DM

นโยบาย DM และห้อง

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

หากต้องการปิดเสียง DM ทั้งหมดแต่ยังให้ห้องทำงาน ให้ตั้งค่า dm.enabled: false:

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

ดู กลุ่ม สำหรับการทำงานของการกำหนดให้ต้องกล่าวถึงและรายการอนุญาต

ตัวอย่างการจับคู่สำหรับ DM ของ Matrix:

openclaw pairing list matrixopenclaw pairing approve matrix <CODE>

หากผู้ใช้ Matrix ที่ยังไม่ได้รับอนุมัติส่งข้อความต่อเนื่องก่อนการอนุมัติ OpenClaw จะใช้รหัสจับคู่ที่รอดำเนินการเดิมซ้ำ และอาจส่งคำตอบเตือนหลังจากช่วงพักสั้นๆ แทนการสร้างรหัสใหม่

ดู การจับคู่ สำหรับขั้นตอนการจับคู่ DM ที่ใช้ร่วมกันและโครงสร้างพื้นที่จัดเก็บ

การซ่อมแซมห้องโดยตรง

หากสถานะข้อความโดยตรงคลาดเคลื่อน OpenClaw อาจมีการจับคู่ m.direct ที่ล้าสมัยซึ่งชี้ไปยังห้องเดี่ยวเก่าแทน DM ที่ใช้งานอยู่ ตรวจสอบการจับคู่ปัจจุบันของคู่สนทนา:

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

ซ่อมแซม:

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

ทั้งสองคำสั่งรองรับ --account <id> สำหรับการตั้งค่าแบบหลายบัญชี ขั้นตอนการซ่อมแซมจะ:

• เลือก DM แบบ 1:1 อย่างเคร่งครัดที่จับคู่ไว้แล้วใน m.direct เป็นลำดับแรก
• ใช้ DM แบบ 1:1 อย่างเคร่งครัดที่เข้าร่วมอยู่ในปัจจุบันกับผู้ใช้นั้นเป็นค่าสำรอง
• สร้างห้องโดยตรงใหม่และเขียน m.direct ใหม่ หากไม่มี DM ที่สมบูรณ์อยู่

ระบบจะไม่ลบห้องเก่าโดยอัตโนมัติ แต่จะเลือก DM ที่สมบูรณ์และอัปเดตการจับคู่ เพื่อให้การส่งผ่าน Matrix การแจ้งเตือนการยืนยัน และขั้นตอนข้อความโดยตรงอื่นๆ ในอนาคตกำหนดเป้าหมายไปยังห้องที่ถูกต้อง

การอนุมัติการดำเนินการ

Matrix สามารถทำหน้าที่เป็นไคลเอ็นต์อนุมัติแบบเนทีฟได้ กำหนดค่าภายใต้ channels.matrix.execApprovals (หรือ channels.matrix.accounts.<account>.execApprovals สำหรับการเขียนทับต่อบัญชี):

• enabled: ส่งคำขออนุมัติผ่านพรอมต์แบบเนทีฟของ Matrix หากไม่ได้ตั้งค่าหรือเป็น "auto" ระบบจะเปิดใช้งานอัตโนมัติเมื่อสามารถระบุผู้อนุมัติได้อย่างน้อยหนึ่งราย ตั้งค่า false เพื่อปิดใช้งานอย่างชัดเจน
• approvers: ID ผู้ใช้ Matrix (@owner:example.org) ที่ได้รับอนุญาตให้อนุมัติคำขอดำเนินการ หากไม่ได้กำหนดจะใช้ channels.matrix.dm.allowFrom เป็นค่าสำรอง
• target: ตำแหน่งที่จะส่งพรอมต์ "dm" (ค่าเริ่มต้น) ส่งไปยัง DM ของผู้อนุมัติ ส่วน "channel" ส่งไปยังห้องหรือ DM ต้นทาง และ "both" ส่งไปยังทั้งสองแห่ง
• agentFilter / sessionFilter: รายการอนุญาตเสริมสำหรับกำหนดว่าเอเจนต์/เซสชันใดจะกระตุ้นการส่งผ่าน Matrix

การอนุญาตจะแตกต่างกันเล็กน้อยระหว่างประเภทการอนุมัติ:

• การอนุมัติการดำเนินการ ใช้ execApprovals.approvers และใช้ dm.allowFrom เป็นค่าสำรอง
• การอนุมัติ Plugin อนุญาตผ่าน dm.allowFrom เท่านั้น

ทั้งสองประเภทรองรับทางลัดด้วยรีแอ็กชันของ Matrix และการอัปเดตข้อความเหมือนกัน ผู้อนุมัติจะเห็นทางลัดด้วยรีแอ็กชันบนข้อความขออนุมัติหลัก:

• ✅ อนุญาตครั้งเดียว
• ❌ ปฏิเสธ
• ♾️ อนุญาตเสมอ (เมื่อนโยบาย exec ที่มีผลอนุญาต)

คำสั่ง slash สำรอง: /approve <id> allow-once, /approve <id> allow-always, /approve <id> deny

เฉพาะผู้อนุมัติที่ระบุตัวตนได้เท่านั้นที่สามารถอนุมัติหรือปฏิเสธได้ การส่งการอนุมัติ exec ไปยังช่องทางจะรวมข้อความคำสั่งไว้ด้วย—เปิดใช้ channel หรือ both เฉพาะในห้องที่เชื่อถือได้

เนื้อหาที่เกี่ยวข้อง: การอนุมัติ Exec

คำสั่ง Slash

คำสั่ง Slash (/new, /reset, /model, /focus, /unfocus, /agents, /session, /acp, /approve เป็นต้น) ใช้งานได้โดยตรงใน DM ส่วนในห้อง OpenClaw ยังรู้จักคำสั่งที่ขึ้นต้นด้วยการกล่าวถึงบอต Matrix เอง ดังนั้น @bot:server /new จึงเรียกเส้นทางคำสั่งได้โดยไม่ต้องมี regex การกล่าวถึงแบบกำหนดเอง ซึ่งช่วยให้บอตตอบสนองต่อโพสต์รูปแบบห้อง @mention /command ที่ Element และไคลเอนต์ลักษณะเดียวกันส่งออกมา เมื่อผู้ใช้ใช้ Tab เติมชื่อบอตให้สมบูรณ์ก่อนพิมพ์คำสั่ง

กฎการอนุญาตยังคงมีผล: ผู้ส่งคำสั่งต้องผ่านนโยบายรายการที่อนุญาตหรือเจ้าของสำหรับ DM หรือห้อง เช่นเดียวกับข้อความทั่วไป

หลายบัญชี

{  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 เท่านั้นที่จะย้ายเข้าไปในบัญชีที่เลื่อนระดับ ส่วนคีย์นโยบายการส่งที่ใช้ร่วมกันจะยังอยู่ที่ระดับบนสุด

ดูรูปแบบหลายบัญชีที่ใช้ร่วมกันได้ที่ ข้อมูลอ้างอิงการกำหนดค่า

Homeserver ส่วนตัว/LAN

ตามค่าเริ่มต้น OpenClaw จะบล็อก homeserver Matrix แบบส่วนตัว/ภายในเพื่อป้องกัน SSRF เว้นแต่จะเลือกอนุญาตเป็นรายบัญชี

หาก homeserver ทำงานบน 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

การเลือกอนุญาตนี้อนุญาตเฉพาะปลายทางส่วนตัว/ภายในที่เชื่อถือได้เท่านั้น Homeserver สาธารณะที่ใช้ข้อความธรรมดา เช่น 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

ID ห้อง Matrix คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ เมื่อกำหนดค่าปลายทางการส่งที่ระบุอย่างชัดเจน งาน cron การผูก หรือรายการที่อนุญาต ให้ใช้ตัวพิมพ์ของ ID ห้องตรงตาม Matrix ทุกประการ OpenClaw จะเก็บคีย์เซสชันภายในในรูปแบบมาตรฐานสำหรับการจัดเก็บ ดังนั้นคีย์ตัวพิมพ์เล็กเหล่านั้นจึงไม่ใช่แหล่งข้อมูลที่เชื่อถือได้สำหรับ ID การส่งของ Matrix

การค้นหาไดเรกทอรีแบบสดใช้บัญชี Matrix ที่เข้าสู่ระบบอยู่:

• การค้นหาผู้ใช้จะสอบถามไดเรกทอรีผู้ใช้ Matrix บน homeserver นั้น
• การค้นหาห้องยอมรับ ID ห้องและนามแฝงที่ระบุอย่างชัดเจนโดยตรง การค้นหาจากชื่อห้องที่เข้าร่วมแล้วจะทำเท่าที่ทำได้ และใช้กับรายการห้องที่อนุญาตขณะรันไทม์เฉพาะเมื่อตั้งค่า dangerouslyAllowNameMatching: true
• หากไม่สามารถแปลงชื่อห้องเป็น ID หรือนามแฝงได้ ระบบจะไม่ใช้ชื่อนั้นในการระบุรายการที่อนุญาตขณะรันไทม์

ข้อมูลอ้างอิงการกำหนดค่า

ฟิลด์ผู้ใช้แบบรายการที่อนุญาต (groupAllowFrom, dm.allowFrom, groups.<room>.users) ยอมรับ ID ผู้ใช้ Matrix แบบเต็ม (ปลอดภัยที่สุด) รายการที่ไม่ใช่ ID จะถูกละเว้นตามค่าเริ่มต้น หากตั้งค่า dangerouslyAllowNameMatching: true ระบบจะระบุรายการที่ตรงกับชื่อที่แสดงในไดเรกทอรี Matrix ทุกประการเมื่อเริ่มต้นระบบ และทุกครั้งที่รายการที่อนุญาตเปลี่ยนแปลงขณะที่ตัวตรวจสอบกำลังทำงาน ส่วนรายการที่ไม่สามารถระบุได้จะถูกละเว้นขณะรันไทม์

คีย์รายการห้องที่อนุญาต (groups, rooms แบบเดิม) ควรเป็น ID ห้องหรือนามแฝง คีย์ที่เป็นเพียงชื่อห้องจะถูกละเว้นตามค่าเริ่มต้น ส่วน dangerouslyAllowNameMatching: true จะคืนค่าการค้นหาแบบเท่าที่ทำได้จากชื่อห้องที่เข้าร่วมแล้ว

บัญชีและการเชื่อมต่อ

• enabled: เปิดหรือปิดใช้งานช่องทาง
• name: ป้ายชื่อที่แสดงสำหรับบัญชี โดยระบุหรือไม่ก็ได้
• defaultAccount: ID บัญชีที่ต้องการใช้เป็นลำดับแรกเมื่อกำหนดค่าบัญชี Matrix หลายบัญชี
• accounts: ค่าที่กำหนดแทนเป็นรายบัญชีที่มีชื่อ ค่า channels.matrix ระดับบนสุดจะสืบทอดเป็นค่าเริ่มต้น
• homeserver: URL ของ homeserver เช่น https://matrix.example.org
• network.dangerouslyAllowPrivateNetwork: อนุญาตให้บัญชีนี้เชื่อมต่อกับ localhost, IP ของ LAN/Tailscale หรือชื่อโฮสต์ภายใน
• proxy: URL พร็อกซี HTTP(S) สำหรับทราฟฟิก Matrix โดยระบุหรือไม่ก็ได้ รองรับการกำหนดค่าแทนเป็นรายบัญชี
• userId: ID ผู้ใช้ Matrix แบบเต็ม (@bot:example.org)
• accessToken: โทเค็นการเข้าถึงสำหรับการรับรองความถูกต้องแบบใช้โทเค็น รองรับค่าข้อความธรรมดาและ SecretRef ผ่านผู้ให้บริการ env/file/exec (การจัดการข้อมูลลับ)
• password: รหัสผ่านสำหรับการเข้าสู่ระบบแบบใช้รหัสผ่าน รองรับค่าข้อความธรรมดาและ SecretRef
• deviceId: ID อุปกรณ์ Matrix ที่ระบุอย่างชัดเจน
• deviceName: ชื่อที่แสดงของอุปกรณ์ที่ใช้ขณะเข้าสู่ระบบด้วยรหัสผ่าน
• avatarUrl: URL อวาตาร์ของตนเองที่จัดเก็บไว้สำหรับการซิงค์โปรไฟล์และการอัปเดต profile set
• initialSyncLimit: จำนวนเหตุการณ์สูงสุดที่จะดึงระหว่างการซิงค์เมื่อเริ่มต้นระบบ

การเข้ารหัส

• encryption: เปิดใช้ E2EE ค่าเริ่มต้น: false
• startupVerification: "if-unverified" (ค่าเริ่มต้นเมื่อเปิด E2EE) หรือ "off" ขอให้ยืนยันอุปกรณ์ของตนเองโดยอัตโนมัติเมื่อเริ่มต้นระบบ หากอุปกรณ์นี้ยังไม่ได้รับการยืนยัน
• startupVerificationCooldownHours: ระยะพักก่อนส่งคำขออัตโนมัติครั้งถัดไปเมื่อเริ่มต้นระบบ ค่าเริ่มต้น: 24

การเข้าถึงและนโยบาย

• groupPolicy: "open", "allowlist" หรือ "disabled" ค่าเริ่มต้น: "allowlist"
• groupAllowFrom: รายการ ID ผู้ใช้ที่อนุญาตสำหรับทราฟฟิกในห้อง
• mentionPatterns: รูปแบบ regex แบบกำหนดขอบเขตสำหรับการกล่าวถึงในห้อง เป็นออบเจ็กต์ที่มี { mode: "allow"|"deny", allowIn: [roomId, ...], denyIn: [roomId, ...] } ควบคุมว่า agents.list[].groupChat.mentionPatterns ที่กำหนดไว้จะมีผลเป็นรายห้องหรือไม่
• dm.enabled: เมื่อเป็น false ให้ละเว้น DM ทั้งหมด ค่าเริ่มต้น: true
• dm.policy: "pairing" (ค่าเริ่มต้น), "allowlist", "open" หรือ "disabled" มีผลหลังจากบอตเข้าร่วมและจัดประเภทห้องเป็น DM แล้ว โดยไม่มีผลต่อการจัดการคำเชิญ
• dm.allowFrom: รายการ ID ผู้ใช้ที่อนุญาตสำหรับทราฟฟิก DM
• dm.sessionScope: "per-user" (ค่าเริ่มต้น) หรือ "per-room"
• dm.threadReplies: ค่าที่กำหนดแทนเฉพาะ DM สำหรับการตอบกลับแบบเธรด ("off", "inbound", "always")
• allowBots: ยอมรับข้อความจากบัญชีบอต Matrix อื่นที่กำหนดค่าไว้ (true หรือ "mentions")
• allowlistOnly: เมื่อเป็น true จะบังคับให้นโยบาย DM ที่ใช้งานอยู่ทั้งหมด (ยกเว้น "disabled") และนโยบายกลุ่ม "open" เป็น "allowlist" โดยไม่เปลี่ยนนโยบาย "disabled"
• dangerouslyAllowNameMatching: เมื่อเป็น true จะอนุญาตให้ค้นหาไดเรกทอรีตามชื่อที่แสดงของ Matrix สำหรับรายการผู้ใช้ที่อนุญาต และค้นหาตามชื่อห้องที่เข้าร่วมแล้วสำหรับคีย์รายการห้องที่อนุญาต ควรใช้ ID @user:server แบบเต็ม รวมถึง ID ห้องหรือนามแฝง
• autoJoin: "always", "allowlist" หรือ "off" ค่าเริ่มต้น: "off" มีผลกับคำเชิญ Matrix ทุกคำเชิญ รวมถึงคำเชิญแบบ DM
• autoJoinAllowlist: ห้อง/นามแฝงที่อนุญาตเมื่อ autoJoin เป็น "allowlist" รายการนามแฝงจะถูกระบุเทียบกับ homeserver ไม่ใช่เทียบกับสถานะที่ห้องซึ่งส่งคำเชิญอ้างไว้
• 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: แมปนโยบายแยกตามห้อง ข้อมูลประจำตัวของเซสชันใช้ ID ห้องแบบคงที่หลังจากการแปลงค่า (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: ID ผู้ใช้ Matrix ที่ได้รับอนุญาตให้อนุมัติ หากไม่มีค่าจะใช้ dm.allowFrom
• execApprovals.target: "dm" (ค่าเริ่มต้น), "channel" หรือ "both"
• execApprovals.agentFilter / execApprovals.sessionFilter: รายการอนุญาตเอเจนต์/เซสชันแบบไม่บังคับสำหรับการนำส่ง

ที่เกี่ยวข้อง

• ภาพรวมช่อง - ช่องทั้งหมดที่รองรับ
• การจับคู่ - ขั้นตอนการตรวจสอบสิทธิ์และการจับคู่สำหรับ DM
• กลุ่ม - ลักษณะการทำงานของแชตกลุ่มและการควบคุมด้วยการกล่าวถึง
• การกำหนดเส้นทางช่อง - การกำหนดเส้นทางเซสชันสำหรับข้อความ
• ความปลอดภัย - โมเดลการเข้าถึงและการเสริมความมั่นคงปลอดภัย