Matrix

Matrix เป็น 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 จากเช็กเอาต์ในเครื่อง: 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. เริ่ม DM กับบอต หรือเชิญบอตเข้าห้อง คำเชิญใหม่จะมีผลก็ต่อเมื่อ 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": บอตจะไม่ปรากฏในห้องหรือ 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, นามแฝงแบบเดิม 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 ของเวิร์กสเปซ

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

ค่าพื้นฐานที่ใช้งานได้จริง พร้อมการจับคู่ 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", // เลือกจากป้ายกำกับที่กำหนดค่าหรือมีมาให้ (false เพื่อซ่อน)          labels: ["Thinking", "Writing", "Searching"], // ตัวเลือกสำหรับ label: "auto"          maxLines: 8, // จำนวนบรรทัดความคืบหน้าแบบเลื่อนสูงสุด (ค่าเริ่มต้น: 8)          maxLineChars: 120, // จำนวนอักขระสูงสุดต่อบรรทัดก่อนตัดทอน (ค่าเริ่มต้น: 120)          toolProgress: true, // แสดงกิจกรรมของเครื่องมือ/ความคืบหน้า (ค่าเริ่มต้น: true)        },      },    },  },}

• progress.label: ป้ายกำกับแบบกำหนดเอง ใช้ "auto"/ไม่ตั้งค่าเพื่อเลือกป้ายกำกับที่กำหนดค่าไว้หรือมีมาให้ หรือใช้ false เพื่อซ่อน
• progress.labels: ตัวเลือกที่ใช้เฉพาะเมื่อ label เป็น "auto" หรือไม่ได้ตั้งค่า
• progress.maxLines: จำนวนบรรทัดความคืบหน้าแบบเลื่อนสูงสุดที่เก็บไว้ในฉบับร่าง บรรทัดที่เก่ากว่านี้จะถูกตัดออก
• progress.maxLineChars: จำนวนอักขระสูงสุดต่อบรรทัดความคืบหน้าแบบกระชับก่อนตัดทอน
• progress.toolProgress: เมื่อเป็น true (ค่าเริ่มต้น) กิจกรรมเครื่องมือ/ความคืบหน้าแบบสดจะปรากฏในฉบับร่าง

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

หมายเหตุ:

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

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

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

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

• เหตุการณ์ m.audio และเหตุการณ์ m.file ที่มีประเภท MIME เป็น audio/* สามารถใช้ได้
• ในห้องที่เข้ารหัส OpenClaw จะถอดรหัสไฟล์แนบผ่านเส้นทางสื่อ Matrix ที่มีอยู่ก่อนถอดเสียง
• ข้อความถอดเสียงจะถูกทำเครื่องหมายว่าสร้างโดยเครื่องและไม่น่าเชื่อถือในพรอมต์ของเอเจนต์
• ไฟล์แนบจะถูกทำเครื่องหมายว่าถอดเสียงแล้ว เพื่อไม่ให้เครื่องมือสื่อปลายทางถอดเสียงซ้ำ
• ตั้งค่า tools.media.audio.enabled: false เพื่อปิดใช้งานการถอดเสียงทั่วทั้งระบบ

ข้อมูลเมตาการอนุมัติ

พรอมต์การอนุมัติแบบเนทีฟของ Matrix เป็นเหตุการณ์ m.room.message ปกติที่มีเนื้อหาเฉพาะของ OpenClaw ภายใต้คีย์ com.openclaw.approval ไคลเอนต์ทั่วไปยังคงแสดงเนื้อหาข้อความ ส่วนไคลเอนต์ที่รองรับ OpenClaw สามารถอ่านรหัสการอนุมัติ ชนิด สถานะ การตัดสินใจ และรายละเอียดการเรียกใช้/Plugin ที่มีโครงสร้างได้

เมื่อพรอมต์ยาวเกินกว่าจะใส่ในเหตุการณ์ Matrix เดียว OpenClaw จะแบ่งข้อความที่มองเห็นออกเป็นส่วน ๆ และแนบ com.openclaw.approval เฉพาะกับส่วนแรกเท่านั้น รีแอ็กชันอนุญาต/ปฏิเสธจะผูกกับเหตุการณ์แรกนั้น ดังนั้นพรอมต์ที่ยาวจึงยังคงมีเป้าหมายการอนุมัติเดียวกับพรอมต์แบบเหตุการณ์เดียว

กฎพุชแบบโฮสต์เองสำหรับตัวอย่างที่สรุปแล้วแบบเงียบ

streaming.mode: "quiet" จะแจ้งเตือนผู้รับเพียงครั้งเดียวเมื่อบล็อกหรือรอบการทำงานเสร็จสมบูรณ์ กฎพุชต่อผู้ใช้ต้องตรงกับเครื่องหมายตัวอย่างที่สรุปแล้ว ดูสูตรทั้งหมดที่ กฎพุช Matrix สำหรับตัวอย่างแบบเงียบ

ห้องระหว่างบอต

โดยค่าเริ่มต้น ข้อความ Matrix จากบัญชี Matrix อื่นของ OpenClaw ที่กำหนดค่าไว้จะถูกละเว้น ใช้ allowBots เพื่ออนุญาตการรับส่งข้อมูลระหว่างเอเจนต์โดยตั้งใจ:

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

• allowBots: true ยอมรับข้อความจากบัญชีบอต Matrix อื่นที่กำหนดค่าไว้ในห้องและ 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 รายงานสัญญาณความน่าเชื่อถือที่เป็นอิสระต่อกันสามรายการ (--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

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

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

หากโฮมเซิร์ฟเวอร์กำหนดให้ใช้ 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: ค่าที่เขียนทับแบบแคบกว่าสำหรับการสร้างเฉพาะเอเจนต์ย่อยหรือเฉพาะ 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: 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: ส่วนย่อยพรอมต์ระบบรายห้อง

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

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

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

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