Matrix

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

ติดตั้ง

openclaw plugins install @openclaw/matrix

openclaw plugins install ./path/to/local/matrix-plugin

​

ตั้งค่า

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

​

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

openclaw channels add
openclaw configure --section channels

​

Config ขั้นต่ำ

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

​

Auto-join

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

​

รูปแบบเป้าหมายของ allowlist

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

​

การทำให้ Account ID เป็นมาตรฐาน

​

Credential ที่แคชไว้

• บัญชีเริ่มต้น: credentials.json
• บัญชีที่มีชื่อ: credentials-<account>.json

​

Environment variables

​

ตัวอย่าง Configuration

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

​

พรีวิว Streaming

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

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

• หากพรีวิวโตเกินขีดจำกัดขนาดต่อ event ของ Matrix OpenClaw จะหยุด preview streaming และ fallback ไปเป็นการส่งเฉพาะผลลัพธ์สุดท้าย
• คำตอบที่เป็นสื่อจะส่งไฟล์แนบตามปกติเสมอ หากไม่สามารถนำพรีวิวเก่ากลับมาใช้ซ้ำได้อย่างปลอดภัยอีกต่อไป OpenClaw จะ redact พรีวิวนั้นก่อนส่งคำตอบสื่อสุดท้าย
• การอัปเดตพรีวิวความคืบหน้าของเครื่องมือเปิดใช้ตามค่าเริ่มต้นเมื่อ Matrix preview streaming ทำงานอยู่ ตั้งค่า streaming.preview.toolProgress: false เพื่อคงการแก้ไขพรีวิวสำหรับข้อความคำตอบไว้ แต่ให้ความคืบหน้าของเครื่องมืออยู่บนเส้นทางการส่งปกติ
• การแก้ไขพรีวิวมีค่าใช้จ่ายเป็น Matrix API calls เพิ่มเติม ปล่อย streaming: "off" ไว้หากคุณต้องการ profile rate-limit ที่ระมัดระวังที่สุด

​

Metadata การอนุมัติ

​

กฎ push แบบ self-hosted สำหรับพรีวิว finalized แบบ quiet

​

ห้อง Bot-to-bot

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

• allowBots: true ยอมรับข้อความจากบัญชีบอต Matrix อื่นที่กำหนดค่าไว้ในห้องและ DM ที่อนุญาต
• allowBots: "mentions" ยอมรับข้อความเหล่านั้นเฉพาะเมื่อข้อความกล่าวถึงบอตนี้อย่างมองเห็นได้ในห้อง DM ยังอนุญาตอยู่
• groups.<room>.allowBots override การตั้งค่าระดับบัญชีสำหรับห้องหนึ่งห้อง
• OpenClaw ยังละเว้นข้อความจาก ID ผู้ใช้ Matrix เดียวกันเพื่อหลีกเลี่ยง loop การตอบตัวเอง
• Matrix ไม่เปิดเผย flag บอตแบบ native ที่นี่ OpenClaw ถือว่า “เขียนโดยบอต” หมายถึง “ส่งโดยบัญชี Matrix อื่นที่กำหนดค่าไว้บน Gateway OpenClaw นี้”

​

การเข้ารหัสและการตรวจสอบความถูกต้อง

​

เปิดใช้งานการเข้ารหัส

openclaw matrix encryption setup

• --recovery-key <key> ใช้ recovery key ก่อนการบูตสแตรป (แนะนำให้ใช้รูปแบบ stdin ที่ระบุไว้ด้านล่าง)
• --force-reset-cross-signing ละทิ้งตัวตน cross-signing ปัจจุบันและสร้างใหม่ (ใช้เมื่อจงใจเท่านั้น)

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

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

​

สถานะและสัญญาณความเชื่อถือ

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

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

​

ตรวจสอบยืนยันอุปกรณ์นี้ด้วย recovery key

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

• Recovery key accepted: Matrix ยอมรับคีย์สำหรับที่จัดเก็บความลับหรือความเชื่อถือของอุปกรณ์
• Backup usable: สามารถโหลดการสำรอง room-key ด้วยวัสดุการกู้คืนที่เชื่อถือได้
• Device verified by owner: อุปกรณ์นี้มีความเชื่อถือตัวตน cross-signing ของ Matrix อย่างสมบูรณ์

openclaw matrix verify self

​

บูตสแตรปหรือซ่อมแซม cross-signing

openclaw matrix verify bootstrap

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

• --recovery-key-stdin (ใช้คู่กับ printf '%s\n' "$MATRIX_RECOVERY_KEY" | …) หรือ --recovery-key <key>
• --force-reset-cross-signing เพื่อละทิ้งตัวตน cross-signing ปัจจุบัน (เมื่อจงใจเท่านั้น)

​

การสำรอง room-key

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

openclaw matrix verify backup reset --yes

​

การแสดงรายการ การขอ และการตอบกลับการตรวจสอบยืนยัน

openclaw matrix verify list

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

​

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

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 list
openclaw matrix devices prune-stale

​

การจัดการโปรไฟล์

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

​

Thread

​

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

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

​

การตอบกลับใน thread (threadReplies)

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

​

การสืบทอด thread และคำสั่ง slash

• ข้อความแบบเธรดขาเข้าจะรวมข้อความรากของเธรดเป็นบริบทเพิ่มเติมของเอเจนต์
• การส่งผ่าน message-tool จะสืบทอดเธรด 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 ที่มีอยู่จะผูกเธรดนั้นไว้กับที่

​

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

• เรียกใช้ /acp spawn codex --bind here ภายใน DM, ห้อง หรือเธรดที่มีอยู่ของ Matrix ที่คุณต้องการใช้ต่อ
• ใน DM หรือห้อง Matrix ระดับบนสุด DM/ห้องปัจจุบันจะยังเป็นพื้นผิวแชต และข้อความในอนาคตจะถูกส่งต่อไปยังเซสชัน ACP ที่สร้างขึ้น
• ภายในเธรด Matrix ที่มีอยู่ --bind here จะผูกเธรดปัจจุบันนั้นไว้กับที่
• /new และ /reset จะรีเซ็ตเซสชัน ACP ที่ผูกอยู่เดิมไว้กับที่
• /acp close จะปิดเซสชัน ACP และลบการผูกออก

• --bind here ไม่สร้างเธรดย่อยของ Matrix
• threadBindings.spawnSessions ควบคุม /acp spawn --thread auto|here ในกรณีที่ OpenClaw ต้องสร้างหรือผูกเธรดย่อยของ Matrix

​

การกำหนดค่าการผูกเธรด

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSessions
• threadBindings.defaultSpawnContext

• ตั้งค่า threadBindings.spawnSessions: false เพื่อบล็อกไม่ให้ /focus ระดับบนสุดและ /acp spawn --thread auto|here สร้าง/ผูกเธรด Matrix
• ตั้งค่า threadBindings.defaultSpawnContext: "isolated" เมื่อการสร้างเธรด subagent แบบเนทีฟไม่ควร fork ทรานสคริปต์ของพาเรนต์

​

รีแอ็กชัน

• react เพิ่มรีแอ็กชันไปยังอีเวนต์ Matrix
• reactions แสดงสรุปรีแอ็กชันปัจจุบันของอีเวนต์ Matrix
• emoji="" ลบรีแอ็กชันของบอตเองในอีเวนต์นั้น
• remove: true ลบเฉพาะรีแอ็กชันอีโมจิที่ระบุจากบอต

​

บริบทประวัติ

• channels.matrix.historyLimit ควบคุมจำนวนข้อความห้องล่าสุดที่รวมเป็น InboundHistory เมื่อข้อความในห้อง Matrix ทริกเกอร์เอเจนต์ ถอยกลับไปใช้ messages.groupChat.historyLimit; หากไม่ได้ตั้งค่าทั้งคู่ ค่าเริ่มต้นที่มีผลคือ 0 ตั้งค่า 0 เพื่อปิดใช้
• ประวัติห้อง Matrix เป็นแบบเฉพาะห้องเท่านั้น DM ยังคงใช้ประวัติเซสชันตามปกติ
• ประวัติห้อง Matrix เป็นแบบรอดำเนินการเท่านั้น: OpenClaw บัฟเฟอร์ข้อความห้องที่ยังไม่ได้ทริกเกอร์การตอบกลับ จากนั้นจึง snapshot หน้าต่างนั้นเมื่อมีการกล่าวถึงหรือทริกเกอร์อื่นมาถึง
• ข้อความทริกเกอร์ปัจจุบันไม่ถูกรวมอยู่ใน InboundHistory; ข้อความนั้นจะอยู่ในเนื้อหาขาเข้าหลักสำหรับรอบนั้น
• การลองซ้ำของอีเวนต์ Matrix เดียวกันจะใช้ snapshot ประวัติเดิมแทนที่จะเลื่อนไปยังข้อความห้องใหม่กว่า

​

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

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

​

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

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

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

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

​

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

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

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

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

​

การอนุมัติ exec

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

• การอนุมัติ exec ใช้ execApprovals.approvers และถอยกลับไปใช้ dm.allowFrom
• การอนุมัติ Plugin อนุญาตผ่าน dm.allowFrom เท่านั้น

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

​

คำสั่ง slash

​

หลายบัญชี

{
  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 เมื่อมี credential ที่แคชไว้ครอบคลุม auth

• เมื่อ OpenClaw เลื่อนระดับการกำหนดค่าแบบบัญชีเดียวเป็นหลายบัญชีระหว่างการซ่อมหรือการตั้งค่า ระบบจะรักษาบัญชีที่มีชื่อเดิมไว้หากมีอยู่ หรือหาก defaultAccount ชี้ไปยังบัญชีหนึ่งอยู่แล้ว เฉพาะคีย์ auth/bootstrap ของ Matrix เท่านั้นที่จะย้ายเข้าไปในบัญชีที่ถูกเลื่อนระดับ; คีย์นโยบายการส่งที่ใช้ร่วมกันจะยังคงอยู่ที่ระดับบนสุด

​

homeserver ส่วนตัว/LAN

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

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

​

การพร็อกซีทราฟฟิก Matrix

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

​

การแปลงเป้าหมาย

• ผู้ใช้: @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 บนโฮมเซิร์ฟเวอร์นั้น
• การค้นหาห้องรองรับ ID ห้องและนามแฝงที่ระบุชัดเจนโดยตรง การค้นหาชื่อห้องที่เข้าร่วมแล้วเป็นแบบพยายามอย่างดีที่สุด และใช้เฉพาะกับรายการอนุญาตของห้องขณะรันไทม์เมื่อมีการตั้งค่า dangerouslyAllowNameMatching: true
• หากไม่สามารถแปลงชื่อห้องเป็น ID หรือนามแฝงได้ ชื่อนั้นจะถูกละเว้นโดยการแปลงรายการอนุญาตขณะรันไทม์

​

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

​

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

• enabled: เปิดหรือปิดช่องทาง
• name: ป้ายชื่อที่แสดงสำหรับบัญชีแบบไม่บังคับ
• defaultAccount: ID บัญชีที่ต้องการใช้เมื่อกำหนดค่าบัญชี Matrix ไว้หลายบัญชี
• accounts: การกำหนดทับรายบัญชีแบบมีชื่อ ค่า channels.matrix ระดับบนสุดจะถูกสืบทอดเป็นค่าเริ่มต้น
• homeserver: URL ของโฮมเซิร์ฟเวอร์ เช่น 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 ผู้ใช้สำหรับทราฟฟิกห้อง
• 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" รายการนามแฝงจะถูกแปลงเทียบกับโฮมเซิร์ฟเวอร์ ไม่ใช่เทียบกับสถานะที่ห้องที่เชิญอ้างสิทธิ์
• contextVisibility: การมองเห็นบริบทเสริม ("all" ค่าเริ่มต้น, "allowlist", "allowlist_quote")

​

พฤติกรรมการตอบกลับ

• replyToMode: "off", "first", "all", หรือ "batched"
• threadReplies: "off", "inbound", หรือ "always"
• threadBindings: การกำหนดทับรายช่องทางสำหรับการกำหนดเส้นทางและวงจรชีวิตของเซสชันที่ผูกกับเธรด
• streaming: "off" (ค่าเริ่มต้น), "partial", "quiet", หรือรูปแบบอ็อบเจกต์ { mode, preview: { toolProgress } } true ↔ "partial", false ↔ "off"
• blockStreaming: เมื่อเป็น true บล็อกของผู้ช่วยที่เสร็จสมบูรณ์จะถูกเก็บเป็นข้อความความคืบหน้าแยกต่างหาก
• markdown: การกำหนดค่าการเรนเดอร์ Markdown แบบไม่บังคับสำหรับข้อความขาออก
• responsePrefix: สตริงแบบไม่บังคับที่เติมหน้าการตอบกลับขาออก
• textChunkLimit: ขนาดชิ้นส่วนขาออกเป็นจำนวนอักขระเมื่อ chunkMode: "length" ค่าเริ่มต้น: 4000
• chunkMode: "length" (ค่าเริ่มต้น แบ่งตามจำนวนอักขระ) หรือ "newline" (แบ่งที่ขอบเขตบรรทัด)
• historyLimit: จำนวนข้อความล่าสุดในห้องที่รวมเป็น InboundHistory เมื่อข้อความในห้องทริกเกอร์เอเจนต์ ย้อนกลับไปใช้ messages.groupChat.historyLimit; ค่าเริ่มต้นที่มีผลคือ 0 (ปิดใช้งาน)
• mediaMaxMb: เพดานขนาดสื่อเป็น MB สำหรับการส่งขาออกและการประมวลผลขาเข้า

​

การตั้งค่ารีแอ็กชัน

• 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>.allowBots: การกำหนดทับรายห้องสำหรับการตั้งค่าระดับช่องทาง (true หรือ "mentions")
  • groups.<room>.users: รายการอนุญาตผู้ส่งรายห้อง
  • groups.<room>.tools: การกำหนดทับอนุญาต/ปฏิเสธเครื่องมือรายห้อง
  • groups.<room>.autoReply: การกำหนดทับการควบคุมด้วยการกล่าวถึงรายห้อง true ปิดข้อกำหนดการกล่าวถึงสำหรับห้องนั้น; false บังคับให้เปิดกลับมา
  • groups.<room>.skills: ตัวกรอง Skills รายห้อง
  • groups.<room>.systemPrompt: ส่วนย่อยของ system prompt รายห้อง

​

การตั้งค่าการอนุมัติ exec

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

​

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

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