เมทริกซ์

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 จากเช็กเอาต์ในเครื่อง ให้ใช้ 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

ตัวช่วยสร้างจะถาม URL ของโฮมเซิร์ฟเวอร์ วิธีการยืนยันตัวตน (โทเค็นหรือรหัสผ่าน) 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": บอตจะไม่ปรากฏในห้องหรือข้อความส่วนตัวใหม่จากคำเชิญใหม่จนกว่าคุณจะเข้าร่วมด้วยตนเอง 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 หรือ * ชื่อแบบธรรมดาจะถูกปฏิเสธเสมอ

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

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

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

Matrix แคชข้อมูลยืนยันตัวตนไว้ภายใต้ ~/.openclaw/credentials/matrix/: credentials.json สำหรับบัญชีเริ่มต้น และ credentials-<account>.json สำหรับบัญชีที่ตั้งชื่อ เมื่อมีข้อมูลยืนยันตัวตนที่แคชไว้ OpenClaw จะถือว่า Matrix ได้รับการกำหนดค่าแล้ว แม้ไม่มี accessToken ในไฟล์กำหนดค่า ซึ่งครอบคลุมการตั้งค่า openclaw doctor และการตรวจสอบสถานะช่องทาง

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

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

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

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

ค่าพื้นฐานที่ใช้งานได้จริงพร้อมการจับคู่ข้อความส่วนตัว รายการอนุญาตของห้อง และ 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: "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 เช่น 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 สามารถอ่าน ID การอนุมัติ ชนิด สถานะ การตัดสินใจ และรายละเอียดการดำเนินการ/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 ยังคงเพิกเฉยต่อข้อความจาก ID ผู้ใช้ 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> ใช้คีย์กู้คืนก่อนเริ่มต้นระบบ (แนะนำให้ใช้รูปแบบ stdin ด้านล่าง)
• --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 ก่อน ซึ่งมีประโยชน์สำหรับการตรวจสอบแบบออฟไลน์หรือการตั้งค่าที่ยังไม่สมบูรณ์

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

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

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

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

การผูกการสนทนา ACP

ห้อง Matrix, 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: ค่าที่เขียนทับแบบเจาะจงยิ่งขึ้นสำหรับการสร้างเฉพาะเอเจนต์ย่อยหรือเฉพาะ ACP
• 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: รหัสผู้ใช้ 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 ร่วมกัน ผู้อนุมัติจะเห็นทางลัดรีแอ็กชันบนข้อความอนุมัติหลัก:

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

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

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

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

คำสั่งสแลช

คำสั่งสแลช (/new, /reset, /model, /focus, /unfocus, /agents, /session, /acp, /approve เป็นต้น) ใช้งานได้โดยตรงใน DM ในห้อง OpenClaw ยังจดจำคำสั่งที่นำหน้าด้วยการกล่าวถึง Matrix ของบอตเอง ดังนั้น @bot:server /new จะกระตุ้นเส้นทางคำสั่งโดยไม่ต้องใช้นิพจน์ทั่วไปสำหรับการกล่าวถึงแบบกำหนดเอง ซึ่งช่วยให้บอตตอบสนองต่อโพสต์รูปแบบห้อง @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 เท่านั้นที่จะย้ายไปยังบัญชีที่ยกระดับ ส่วนคีย์นโยบายการส่งที่ใช้ร่วมกันจะยังคงอยู่ที่ระดับบนสุด

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

โฮมเซิร์ฟเวอร์ส่วนตัว/LAN

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

หากโฮมเซิร์ฟเวอร์ของคุณทำงานบน 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 แยกแยะตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ ใช้รูปแบบตัวพิมพ์ของรหัสห้องตามที่ปรากฏใน Matrix ทุกประการเมื่อกำหนดค่าเป้าหมายการส่งแบบระบุชัดเจน งาน Cron การผูก หรือรายการอนุญาต 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: เปิดใช้ E2EE ค่าเริ่มต้น: false
• startupVerification: "if-unverified" (ค่าเริ่มต้นเมื่อเปิด E2EE) หรือ "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: ห้อง/นามแฝงที่อนุญาตเมื่อ autoJoin เป็น "allowlist" รายการนามแฝงจะถูกแปลงโดยอ้างอิงโฮมเซิร์ฟเวอร์ ไม่ใช่สถานะที่ห้องซึ่งส่งคำเชิญกล่าวอ้าง
• 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: ขีดจำกัดขนาดสื่อเป็น 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: ส่วนย่อยพรอมต์ระบบแยกตามห้อง

การตั้งค่าการอนุมัติการดำเนินการ

• execApprovals.enabled: ส่งคำขออนุมัติการดำเนินการผ่านพรอมต์แบบเนทีฟของ Matrix
• execApprovals.approvers: รหัสผู้ใช้ Matrix ที่ได้รับอนุญาตให้อนุมัติ หากไม่ได้กำหนดจะใช้ dm.allowFrom
• execApprovals.target: "dm" (ค่าเริ่มต้น), "channel" หรือ "both"
• execApprovals.agentFilter / execApprovals.sessionFilter: รายการอนุญาตเอเจนต์/เซสชันสำหรับการส่งซึ่งระบุหรือไม่ก็ได้

เนื้อหาที่เกี่ยวข้อง

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