Ma trận - OpenClaw

Matrix là một Plugin kênh có thể tải xuống cho OpenClaw. Plugin này sử dụng matrix-js-sdk chính thức và hỗ trợ DM, phòng, luồng, phương tiện, phản ứng, cuộc thăm dò, vị trí và E2EE.

Cài đặt

Cài đặt Matrix từ ClawHub trước khi cấu hình kênh:

openclaw plugins install @openclaw/matrix

Các đặc tả Plugin trần sẽ thử ClawHub trước, sau đó dự phòng sang npm. Để buộc nguồn registry, hãy dùng openclaw plugins install clawhub:@openclaw/matrix hoặc openclaw plugins install npm:@openclaw/matrix. Từ một checkout cục bộ:

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

plugins install đăng ký và bật Plugin, nên không cần bước openclaw plugins enable matrix riêng. Plugin vẫn không làm gì cho đến khi bạn cấu hình kênh bên dưới. Xem Plugins để biết hành vi chung của Plugin và quy tắc cài đặt.

Thiết lập

Tạo tài khoản Matrix trên homeserver của bạn.
Cấu hình channels.matrix bằng homeserver + accessToken, hoặc homeserver + userId + password.
Khởi động lại Gateway.
Bắt đầu một DM với bot, hoặc mời bot vào một phòng (xem tự động tham gia - lời mời mới chỉ có hiệu lực khi autoJoin cho phép).

Thiết lập tương tác

openclaw channels add
openclaw configure --section channels

Trình hướng dẫn hỏi: URL homeserver, phương thức xác thực (access token hoặc mật khẩu), ID người dùng (chỉ xác thực bằng mật khẩu), tên thiết bị tùy chọn, có bật E2EE hay không, và có cấu hình quyền truy cập phòng và tự động tham gia hay không. Nếu các biến môi trường MATRIX_* khớp đã tồn tại và tài khoản được chọn chưa có thông tin xác thực đã lưu, trình hướng dẫn sẽ đề xuất lối tắt bằng biến môi trường. Để phân giải tên phòng trước khi lưu allowlist, chạy openclaw channels resolve --channel matrix "Project Room". Khi E2EE được bật, trình hướng dẫn ghi cấu hình và chạy cùng quy trình khởi tạo như openclaw matrix encryption setup.

Cấu hình tối thiểu

Dựa trên token:

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

Dựa trên mật khẩu (token được lưu vào bộ nhớ đệm sau lần đăng nhập đầu tiên):

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me", // pragma: allowlist secret
      deviceName: "OpenClaw Gateway",
    },
  },
}

Tự động tham gia

channels.matrix.autoJoin mặc định là off. Với mặc định này, bot sẽ không xuất hiện trong các phòng hoặc DM mới từ lời mời mới cho đến khi bạn tham gia thủ công. OpenClaw không thể biết tại thời điểm được mời liệu phòng được mời là DM hay nhóm, nên mọi lời mời - bao gồm cả lời mời kiểu DM - đều đi qua autoJoin trước. dm.policy chỉ áp dụng sau đó, khi bot đã tham gia và phòng đã được phân loại.

Đặt autoJoin: "allowlist" cùng với autoJoinAllowlist để giới hạn các lời mời bot chấp nhận, hoặc autoJoin: "always" để chấp nhận mọi lời mời.autoJoinAllowlist chỉ chấp nhận mục tiêu ổn định: !roomId:server, #alias:server, hoặc *. Tên phòng thuần bị từ chối; các mục alias được phân giải dựa trên homeserver, không dựa trên trạng thái do phòng được mời tuyên bố.

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

Để chấp nhận mọi lời mời, dùng autoJoin: "always".

Định dạng mục tiêu allowlist

Allowlist DM và phòng nên được điền bằng các ID ổn định:

DM (dm.allowFrom, groupAllowFrom, groups.<room>.users): dùng @user:server. Tên hiển thị mặc định bị bỏ qua vì chúng có thể thay đổi; chỉ đặt dangerouslyAllowNameMatching: true khi bạn thật sự cần tương thích với các mục tên hiển thị.
Khóa allowlist phòng (groups, rooms cũ): dùng !room:server hoặc #alias:server. Tên phòng thuần mặc định bị bỏ qua; chỉ đặt dangerouslyAllowNameMatching: true khi bạn thật sự cần tương thích với tra cứu tên phòng đã tham gia.
Allowlist lời mời (autoJoinAllowlist): dùng !room:server, #alias:server, hoặc *. Tên phòng thuần bị từ chối.

Chuẩn hóa ID tài khoản

Trình hướng dẫn chuyển một tên thân thiện thành ID tài khoản đã chuẩn hóa. Ví dụ, Ops Bot trở thành ops-bot. Dấu câu được escape trong tên biến môi trường theo phạm vi để hai tài khoản không thể va chạm: - → _X2D_, nên ops-prod ánh xạ thành MATRIX_OPS_X2D_PROD_*.

Thông tin xác thực được lưu vào bộ nhớ đệm

Matrix lưu thông tin xác thực đã lưu vào bộ nhớ đệm trong ~/.openclaw/credentials/matrix/:

tài khoản mặc định: credentials.json
tài khoản có tên: credentials-<account>.json

Khi thông tin xác thực đã lưu vào bộ nhớ đệm tồn tại ở đó, OpenClaw coi Matrix là đã được cấu hình ngay cả khi access token không có trong tệp cấu hình - điều đó bao gồm thiết lập, openclaw doctor, và các probe trạng thái kênh.

Biến môi trường

Được dùng khi khóa cấu hình tương đương chưa được đặt. Tài khoản mặc định dùng tên không có tiền tố; tài khoản có tên dùng ID tài khoản được chèn trước hậu tố.

Tài khoản mặc định	Tài khoản có tên (`<ID>` là ID tài khoản đã chuẩn hóa)
`MATRIX_HOMESERVER`	`MATRIX_<ID>_HOMESERVER`
`MATRIX_ACCESS_TOKEN`	`MATRIX_<ID>_ACCESS_TOKEN`
`MATRIX_USER_ID`	`MATRIX_<ID>_USER_ID`
`MATRIX_PASSWORD`	`MATRIX_<ID>_PASSWORD`
`MATRIX_DEVICE_ID`	`MATRIX_<ID>_DEVICE_ID`
`MATRIX_DEVICE_NAME`	`MATRIX_<ID>_DEVICE_NAME`
`MATRIX_RECOVERY_KEY`	`MATRIX_<ID>_RECOVERY_KEY`

Với tài khoản ops, các tên trở thành MATRIX_OPS_HOMESERVER, MATRIX_OPS_ACCESS_TOKEN, v.v. Các biến môi trường recovery-key được đọc bởi các luồng CLI có nhận biết phục hồi (verify backup restore, verify device, verify bootstrap) khi bạn pipe khóa vào qua --recovery-key-stdin. MATRIX_HOMESERVER không thể được đặt từ .env của workspace; xem Tệp .env của workspace.

Ví dụ cấu hình

Một baseline thực tế với ghép đôi DM, allowlist phòng và 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",
    },
  },
}

Bản xem trước streaming

Streaming trả lời của Matrix là tùy chọn bật. streaming kiểm soát cách OpenClaw gửi câu trả lời đang xử lý của trợ lý; blockStreaming kiểm soát việc mỗi khối đã hoàn tất có được giữ lại dưới dạng tin nhắn Matrix riêng hay không.

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

Để giữ bản xem trước câu trả lời trực tiếp nhưng ẩn các dòng công cụ/tiến trình tạm thời, dùng dạng object:

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

`streaming`	Hành vi
`"off"` (mặc định)	Chờ câu trả lời đầy đủ, gửi một lần. `true` ↔ `"partial"`, `false` ↔ `"off"`.
`"partial"`	Chỉnh sửa một tin nhắn văn bản thông thường tại chỗ khi model viết khối hiện tại. Các ứng dụng Matrix tiêu chuẩn có thể thông báo ở bản xem trước đầu tiên, không phải lần chỉnh sửa cuối.
`"quiet"`	Giống `"partial"` nhưng tin nhắn là notice không tạo thông báo. Người nhận chỉ nhận được thông báo khi một quy tắc push theo người dùng khớp với lần chỉnh sửa đã hoàn tất (xem bên dưới).

blockStreaming độc lập với streaming:

`streaming`	`blockStreaming: true`	`blockStreaming: false` (mặc định)
`"partial"` / `"quiet"`	Bản nháp trực tiếp cho khối hiện tại, các khối hoàn tất được giữ làm tin nhắn	Bản nháp trực tiếp cho khối hiện tại, hoàn tất tại chỗ
`"off"`	Một tin nhắn Matrix có thông báo cho mỗi khối đã hoàn tất	Một tin nhắn Matrix có thông báo cho toàn bộ câu trả lời

Ghi chú:

Nếu bản xem trước vượt quá giới hạn kích thước theo sự kiện của Matrix, OpenClaw dừng streaming bản xem trước và dự phòng sang chỉ gửi kết quả cuối.
Trả lời bằng phương tiện luôn gửi tệp đính kèm bình thường. Nếu một bản xem trước cũ không còn có thể được tái sử dụng an toàn, OpenClaw sẽ redacts nó trước khi gửi trả lời phương tiện cuối cùng.
Cập nhật bản xem trước tiến trình công cụ được bật mặc định khi streaming bản xem trước Matrix đang hoạt động. Đặt streaming.preview.toolProgress: false để giữ các chỉnh sửa bản xem trước cho văn bản câu trả lời nhưng để tiến trình công cụ đi theo đường gửi thông thường.
Chỉnh sửa bản xem trước tốn thêm lệnh gọi API Matrix. Để streaming: "off" nếu bạn muốn hồ sơ giới hạn tốc độ thận trọng nhất.

Siêu dữ liệu phê duyệt

Prompt phê duyệt native của Matrix là các sự kiện m.room.message thông thường với nội dung sự kiện tùy chỉnh riêng của OpenClaw trong com.openclaw.approval. Matrix cho phép các khóa nội dung sự kiện tùy chỉnh, nên ứng dụng tiêu chuẩn vẫn hiển thị phần thân văn bản trong khi ứng dụng nhận biết OpenClaw có thể đọc ID phê duyệt có cấu trúc, loại, trạng thái, các quyết định khả dụng, và chi tiết exec/Plugin. Khi prompt phê duyệt quá dài cho một sự kiện Matrix, OpenClaw chia văn bản hiển thị thành các phần và chỉ gắn com.openclaw.approval vào phần đầu tiên. Phản ứng cho quyết định allow/deny được ràng buộc với sự kiện đầu tiên đó, nên prompt dài vẫn giữ cùng mục tiêu phê duyệt như prompt một sự kiện.

Quy tắc push tự host cho bản xem trước cuối yên lặng

streaming: "quiet" chỉ thông báo cho người nhận khi một khối hoặc lượt đã hoàn tất - một quy tắc push theo người dùng phải khớp với marker bản xem trước đã hoàn tất. Xem Quy tắc push Matrix cho bản xem trước yên lặng để biết công thức đầy đủ (token người nhận, kiểm tra pusher, cài đặt quy tắc, ghi chú theo homeserver).

Phòng bot-với-bot

Theo mặc định, tin nhắn Matrix từ các tài khoản Matrix OpenClaw đã cấu hình khác sẽ bị bỏ qua. Dùng allowBots khi bạn chủ ý muốn lưu lượng Matrix giữa các agent:

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

allowBots: true chấp nhận tin nhắn từ các tài khoản bot Matrix đã cấu hình khác trong phòng và DM được phép.
allowBots: "mentions" chỉ chấp nhận các tin nhắn đó khi chúng nhắc đến bot này một cách hiển thị trong phòng. DM vẫn được cho phép.
groups.<room>.allowBots ghi đè thiết lập cấp tài khoản cho một phòng.
OpenClaw vẫn bỏ qua tin nhắn từ cùng ID người dùng Matrix để tránh vòng lặp tự trả lời.
Matrix không expose cờ bot native ở đây; OpenClaw coi “do bot viết” là “được gửi bởi một tài khoản Matrix đã cấu hình khác trên Gateway OpenClaw này”.

Dùng allowlist phòng nghiêm ngặt và yêu cầu nhắc đến khi bật lưu lượng bot-với-bot trong phòng dùng chung.

Mã hóa và xác minh

Trong các phòng được mã hóa (E2EE), sự kiện hình ảnh gửi đi dùng thumbnail_file để bản xem trước hình ảnh được mã hóa cùng với tệp đính kèm đầy đủ. Các phòng không mã hóa vẫn dùng thumbnail_url dạng thường. Không cần cấu hình - Plugin tự động phát hiện trạng thái E2EE. Tất cả lệnh openclaw matrix chấp nhận --verbose (chẩn đoán đầy đủ), --json (đầu ra máy đọc được), và --account <id> (thiết lập nhiều tài khoản). Theo mặc định, đầu ra ngắn gọn với nhật ký SDK nội bộ ở chế độ yên lặng. Các ví dụ dưới đây hiển thị dạng chuẩn; thêm các cờ khi cần.

Bật mã hóa

openclaw matrix encryption setup

Khởi tạo lưu trữ bí mật và ký chéo, tạo bản sao lưu khóa phòng nếu cần, rồi in trạng thái và các bước tiếp theo. Các cờ hữu ích:

--recovery-key <key> áp dụng khóa khôi phục trước khi khởi tạo (ưu tiên dạng stdin được ghi tài liệu bên dưới)
--force-reset-cross-signing loại bỏ danh tính ký chéo hiện tại và tạo danh tính mới (chỉ dùng khi có chủ ý)

Với tài khoản mới, bật E2EE khi tạo:

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

--encryption là bí danh của --enable-e2ee. Cấu hình thủ công tương đương:

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

Trạng thái và tín hiệu tin cậy

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

verify status báo cáo ba tín hiệu tin cậy độc lập (--verbose hiển thị tất cả):

Locally trusted: chỉ được ứng dụng khách này tin cậy
Cross-signing verified: SDK báo cáo xác minh qua ký chéo
Signed by owner: được ký bằng khóa tự ký của chính bạn (chỉ để chẩn đoán)

Verified by owner chỉ trở thành yes khi Cross-signing verified là yes. Chỉ có tin cậy cục bộ hoặc chữ ký chủ sở hữu là chưa đủ. --allow-degraded-local-state trả về chẩn đoán nỗ lực tốt nhất mà không chuẩn bị tài khoản Matrix trước; hữu ích cho các phép dò ngoại tuyến hoặc được cấu hình một phần.

Xác minh thiết bị này bằng khóa khôi phục

Khóa khôi phục là thông tin nhạy cảm - hãy truyền qua stdin thay vì truyền trên dòng lệnh. Đặt MATRIX_RECOVERY_KEY (hoặc MATRIX_<ID>_RECOVERY_KEY cho tài khoản có tên):

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

Lệnh báo cáo ba trạng thái:

Recovery key accepted: Matrix đã chấp nhận khóa cho lưu trữ bí mật hoặc tin cậy thiết bị.
Backup usable: có thể tải bản sao lưu khóa phòng bằng vật liệu khôi phục đáng tin cậy.
Device verified by owner: thiết bị này có đầy đủ tin cậy danh tính ký chéo Matrix.

Lệnh thoát khác 0 khi tin cậy danh tính đầy đủ chưa hoàn tất, ngay cả khi khóa khôi phục đã mở khóa vật liệu sao lưu. Trong trường hợp đó, hãy hoàn tất tự xác minh từ một ứng dụng khách Matrix khác:

openclaw matrix verify self

verify self chờ đến khi Cross-signing verified: yes trước khi thoát thành công. Dùng --timeout-ms <ms> để điều chỉnh thời gian chờ. Dạng khóa trực tiếp openclaw matrix verify device "<recovery-key>" cũng được chấp nhận, nhưng khóa sẽ nằm trong lịch sử shell của bạn.

Khởi tạo hoặc sửa ký chéo

openclaw matrix verify bootstrap

verify bootstrap là lệnh sửa và thiết lập cho các tài khoản được mã hóa. Theo thứ tự, lệnh này:

khởi tạo lưu trữ bí mật, tái sử dụng khóa khôi phục hiện có khi có thể
khởi tạo ký chéo và tải lên các khóa công khai còn thiếu
đánh dấu và ký chéo thiết bị hiện tại
tạo bản sao lưu khóa phòng phía máy chủ nếu chưa có

Nếu homeserver yêu cầu UIA để tải lên khóa ký chéo, OpenClaw thử không xác thực trước, rồi m.login.dummy, rồi m.login.password (yêu cầu channels.matrix.password). Các cờ hữu ích:

--recovery-key-stdin (dùng cùng printf '%s\n' "$MATRIX_RECOVERY_KEY" | …) hoặc --recovery-key <key>
--force-reset-cross-signing để loại bỏ danh tính ký chéo hiện tại (chỉ khi có chủ ý)

Sao lưu khóa phòng

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

backup status cho biết bản sao lưu phía máy chủ có tồn tại không và thiết bị này có thể giải mã nó không. backup restore nhập các khóa phòng đã sao lưu vào kho crypto cục bộ; nếu khóa khôi phục đã có trên đĩa, bạn có thể bỏ qua --recovery-key-stdin. Để thay một bản sao lưu hỏng bằng baseline mới (chấp nhận mất lịch sử cũ không thể khôi phục; cũng có thể tạo lại lưu trữ bí mật nếu không thể tải bí mật sao lưu hiện tại):

openclaw matrix verify backup reset --yes

Chỉ thêm --rotate-recovery-key khi bạn chủ ý muốn khóa khôi phục trước đó ngừng mở khóa baseline sao lưu mới.

Liệt kê, yêu cầu và phản hồi xác minh

openclaw matrix verify list

Liệt kê các yêu cầu xác minh đang chờ cho tài khoản đã chọn.

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

Gửi yêu cầu xác minh từ tài khoản OpenClaw này. --own-user yêu cầu tự xác minh (bạn chấp nhận lời nhắc trong một ứng dụng khách Matrix khác của cùng người dùng); --user-id/--device-id/--room-id nhắm đến người khác. Không thể kết hợp --own-user với các cờ nhắm mục tiêu khác. Để xử lý vòng đời ở mức thấp hơn - thường là khi theo dõi các yêu cầu đến từ một ứng dụng khách khác - các lệnh này tác động lên một yêu cầu <id> cụ thể (được in bởi verify list và verify request):

Lệnh	Mục đích
`openclaw matrix verify accept <id>`	Chấp nhận một yêu cầu đến
`openclaw matrix verify start <id>`	Bắt đầu luồng SAS
`openclaw matrix verify sas <id>`	In emoji hoặc số thập phân SAS
`openclaw matrix verify confirm-sas <id>`	Xác nhận SAS khớp với những gì ứng dụng khách kia hiển thị
`openclaw matrix verify mismatch-sas <id>`	Từ chối SAS khi emoji hoặc số thập phân không khớp
`openclaw matrix verify cancel <id>`	Hủy; nhận tùy chọn `--reason <text>` và `--code <matrix-code>`

accept, start, sas, confirm-sas, mismatch-sas, và cancel đều chấp nhận --user-id và --room-id làm gợi ý theo dõi DM khi xác minh được neo vào một phòng tin nhắn trực tiếp cụ thể.

Ghi chú nhiều tài khoản

Không có --account <id>, các lệnh CLI Matrix dùng tài khoản mặc định ngầm định. Nếu bạn có nhiều tài khoản có tên và chưa đặt channels.matrix.defaultAccount, chúng sẽ từ chối đoán và yêu cầu bạn chọn. Khi E2EE bị tắt hoặc không khả dụng cho một tài khoản có tên, lỗi trỏ đến khóa cấu hình của tài khoản đó, ví dụ channels.matrix.accounts.assistant.encryption.

Hành vi khởi động

Với encryption: true, startupVerification mặc định là "if-unverified". Khi khởi động, một thiết bị chưa xác minh sẽ yêu cầu tự xác minh trong một ứng dụng khách Matrix khác, bỏ qua các yêu cầu trùng lặp và áp dụng thời gian chờ (mặc định là 24 giờ). Điều chỉnh bằng startupVerificationCooldownHours hoặc tắt bằng startupVerification: "off".Khi khởi động, cũng chạy một lượt khởi tạo crypto thận trọng, tái sử dụng lưu trữ bí mật và danh tính ký chéo hiện tại. Nếu trạng thái khởi tạo bị hỏng, OpenClaw thử sửa có bảo vệ ngay cả khi không có channels.matrix.password; nếu homeserver yêu cầu UIA bằng mật khẩu, khởi động ghi cảnh báo và vẫn không gây lỗi nghiêm trọng. Các thiết bị đã được chủ sở hữu ký sẵn được giữ nguyên.Xem Di chuyển Matrix để biết toàn bộ luồng nâng cấp.

Thông báo xác minh

Matrix đăng thông báo vòng đời xác minh vào phòng xác minh DM nghiêm ngặt dưới dạng tin nhắn m.notice: yêu cầu, sẵn sàng (với hướng dẫn “Verify by emoji”), bắt đầu/hoàn tất, và chi tiết SAS (emoji/số thập phân) khi có.Các yêu cầu đến từ một ứng dụng khách Matrix khác được theo dõi và tự động chấp nhận. Với tự xác minh, OpenClaw tự động bắt đầu luồng SAS và xác nhận phía của nó khi xác minh emoji khả dụng - bạn vẫn cần so sánh và xác nhận “They match” trong ứng dụng khách Matrix của mình.Thông báo hệ thống xác minh không được chuyển tiếp vào pipeline trò chuyện agent.

Thiết bị Matrix đã xóa hoặc không hợp lệ

Nếu verify status cho biết thiết bị hiện tại không còn được liệt kê trên homeserver, hãy tạo một thiết bị Matrix OpenClaw mới. Với đăng nhập bằng mật khẩu:

openclaw matrix account add \
  --account assistant \
  --homeserver https://matrix.example.org \
  --user-id '@assistant:example.org' \
  --password '<password>' \
  --device-name OpenClaw-Gateway

Với xác thực bằng token, hãy tạo access token mới trong ứng dụng khách Matrix hoặc giao diện quản trị, rồi cập nhật OpenClaw:

openclaw matrix account add \
  --account assistant \
  --homeserver https://matrix.example.org \
  --access-token '<token>'

Thay assistant bằng ID tài khoản từ lệnh thất bại, hoặc bỏ qua --account cho tài khoản mặc định.

Vệ sinh thiết bị

Các thiết bị do OpenClaw quản lý cũ có thể tích tụ. Liệt kê và dọn bỏ:

openclaw matrix devices list
openclaw matrix devices prune-stale

Kho crypto

Matrix E2EE dùng đường dẫn crypto Rust chính thức của matrix-js-sdk với fake-indexeddb làm shim IndexedDB. Trạng thái crypto được lưu bền vào crypto-idb-snapshot.json (quyền tệp hạn chế).Trạng thái runtime được mã hóa nằm dưới ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/ và bao gồm kho đồng bộ, kho crypto, khóa khôi phục, snapshot IDB, liên kết luồng, và trạng thái xác minh khởi động. Khi token thay đổi nhưng danh tính tài khoản vẫn giữ nguyên, OpenClaw tái sử dụng root hiện có tốt nhất để trạng thái trước đó vẫn hiển thị.

Quản lý hồ sơ

Cập nhật self-profile Matrix cho tài khoản đã chọn:

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

Bạn có thể truyền cả hai tùy chọn trong một lần gọi. Matrix chấp nhận trực tiếp URL avatar mxc://; khi bạn truyền http:// hoặc https://, OpenClaw tải tệp lên trước và lưu URL mxc:// đã phân giải vào channels.matrix.avatarUrl (hoặc override theo từng tài khoản).

Luồng

Matrix hỗ trợ luồng Matrix nguyên bản cho cả trả lời tự động và gửi bằng công cụ tin nhắn. Hai nút điều khiển độc lập kiểm soát hành vi:

Định tuyến phiên (`sessionScope`)

dm.sessionScope quyết định cách các phòng DM Matrix ánh xạ tới phiên OpenClaw:

"per-user" (mặc định): tất cả phòng DM với cùng peer được định tuyến dùng chung một phiên.
"per-room": mỗi phòng DM Matrix có khóa phiên riêng, ngay cả khi peer giống nhau.

Các liên kết hội thoại tường minh luôn thắng sessionScope, nên các phòng và luồng đã liên kết giữ phiên mục tiêu đã chọn của chúng.

Tạo luồng trả lời (`threadReplies`)

threadReplies quyết định nơi bot đăng câu trả lời:

"off": câu trả lời ở cấp cao nhất. Tin nhắn theo luồng gửi vào vẫn ở phiên cha.
"inbound": chỉ trả lời bên trong một luồng khi tin nhắn gửi vào đã nằm trong luồng đó.
"always": trả lời bên trong một luồng bắt nguồn từ tin nhắn kích hoạt; hội thoại đó được định tuyến qua một phiên theo phạm vi luồng tương ứng kể từ lần kích hoạt đầu tiên.

dm.threadReplies ghi đè điều này chỉ cho DM - ví dụ, giữ các luồng phòng tách biệt trong khi giữ DM phẳng.

Kế thừa luồng và lệnh gạch chéo

Tin nhắn dạng luồng đi vào bao gồm tin nhắn gốc của luồng làm ngữ cảnh agent bổ sung.
Các lần gửi bằng công cụ nhắn tin tự động kế thừa luồng Matrix hiện tại khi nhắm tới cùng phòng (hoặc cùng mục tiêu người dùng DM), trừ khi cung cấp threadId rõ ràng.
Việc tái sử dụng mục tiêu người dùng DM chỉ kích hoạt khi metadata phiên hiện tại chứng minh đó là cùng một đối tác DM trên cùng tài khoản Matrix; nếu không, OpenClaw quay về định tuyến thông thường theo phạm vi người dùng.
/focus, /unfocus, /agents, /session idle, /session max-age, và /acp spawn gắn với luồng đều hoạt động trong phòng Matrix và DM.
/focus ở cấp cao nhất tạo một luồng Matrix mới và gắn nó với phiên đích khi threadBindings.spawnSessions được bật.
Chạy /focus hoặc /acp spawn --thread here bên trong một luồng Matrix hiện có sẽ gắn luồng đó tại chỗ.

Khi OpenClaw phát hiện một phòng DM Matrix xung đột với một phòng DM khác trên cùng phiên chia sẻ, nó đăng một m.notice một lần trong phòng đó, trỏ tới lối thoát /focus và đề xuất thay đổi dm.sessionScope. Thông báo chỉ xuất hiện khi binding luồng được bật.

Binding cuộc hội thoại ACP

Phòng Matrix, DM và các luồng Matrix hiện có có thể được chuyển thành workspace ACP bền vững mà không thay đổi bề mặt chat. Luồng thao tác nhanh:

Chạy /acp spawn codex --bind here bên trong DM Matrix, phòng, hoặc luồng hiện có mà bạn muốn tiếp tục sử dụng.
Trong DM hoặc phòng Matrix cấp cao nhất, DM/phòng hiện tại vẫn là bề mặt chat và các tin nhắn sau này định tuyến tới phiên ACP đã spawn.
Bên trong một luồng Matrix hiện có, --bind here gắn luồng hiện tại đó tại chỗ.
/new và /reset đặt lại cùng phiên ACP đã được binding tại chỗ.
/acp close đóng phiên ACP và xóa binding.

Ghi chú:

--bind here không tạo luồng Matrix con.
threadBindings.spawnSessions kiểm soát /acp spawn --thread auto|here, nơi OpenClaw cần tạo hoặc binding một luồng Matrix con.

Cấu hình binding luồng

Matrix kế thừa mặc định toàn cục từ session.threadBindings, đồng thời hỗ trợ ghi đè theo từng kênh:

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

Spawn phiên gắn với luồng Matrix mặc định được bật:

Đặt threadBindings.spawnSessions: false để chặn /focus cấp cao nhất và /acp spawn --thread auto|here tạo/binding luồng Matrix.
Đặt threadBindings.defaultSpawnContext: "isolated" khi các lần spawn luồng subagent native không nên fork transcript cha.

Phản ứng

Matrix hỗ trợ phản ứng gửi ra, thông báo phản ứng đi vào, và phản ứng xác nhận. Công cụ phản ứng gửi ra được kiểm soát bởi channels.matrix.actions.reactions:

react thêm một phản ứng vào sự kiện Matrix.
reactions liệt kê tóm tắt phản ứng hiện tại cho một sự kiện Matrix.
emoji="" xóa các phản ứng của chính bot trên sự kiện đó.
remove: true chỉ xóa phản ứng emoji đã chỉ định khỏi bot.

Thứ tự phân giải (giá trị đầu tiên được định nghĩa sẽ thắng):

Thiết lập	Thứ tự
`ackReaction`	theo từng tài khoản → kênh → `messages.ackReaction` → dự phòng emoji danh tính agent
`ackReactionScope`	theo từng tài khoản → kênh → `messages.ackReactionScope` → mặc định `"group-mentions"`
`reactionNotifications`	theo từng tài khoản → kênh → mặc định `"own"`

reactionNotifications: "own" chuyển tiếp các sự kiện m.reaction đã thêm khi chúng nhắm tới tin nhắn Matrix do bot viết; "off" tắt sự kiện hệ thống phản ứng. Việc xóa phản ứng không được tổng hợp thành sự kiện hệ thống vì Matrix biểu thị chúng dưới dạng redaction, không phải dưới dạng các lần xóa m.reaction độc lập.

Ngữ cảnh lịch sử

channels.matrix.historyLimit kiểm soát số lượng tin nhắn phòng gần đây được đưa vào dưới dạng InboundHistory khi một tin nhắn phòng Matrix kích hoạt agent. Quay về messages.groupChat.historyLimit; nếu cả hai đều chưa đặt, mặc định hiệu lực là 0. Đặt 0 để tắt.
Lịch sử phòng Matrix chỉ thuộc phạm vi phòng. DM tiếp tục dùng lịch sử phiên thông thường.
Lịch sử phòng Matrix chỉ là pending: OpenClaw đệm các tin nhắn phòng chưa kích hoạt trả lời, rồi chụp nhanh cửa sổ đó khi một mention hoặc trigger khác đến.
Tin nhắn trigger hiện tại không được đưa vào InboundHistory; nó vẫn nằm trong phần thân inbound chính cho lượt đó.
Các lần thử lại của cùng sự kiện Matrix tái sử dụng snapshot lịch sử gốc thay vì trôi về phía trước tới các tin nhắn phòng mới hơn.

Khả năng hiển thị ngữ cảnh

Matrix hỗ trợ điều khiển contextVisibility dùng chung cho ngữ cảnh phòng bổ sung như văn bản trả lời được lấy về, gốc luồng, và lịch sử pending.

contextVisibility: "all" là mặc định. Ngữ cảnh bổ sung được giữ như đã nhận.
contextVisibility: "allowlist" lọc ngữ cảnh bổ sung theo những người gửi được phép bởi các kiểm tra allowlist phòng/người dùng đang hoạt động.
contextVisibility: "allowlist_quote" hoạt động giống allowlist, nhưng vẫn giữ một trả lời được trích dẫn rõ ràng.

Thiết lập này ảnh hưởng tới khả năng hiển thị ngữ cảnh bổ sung, không ảnh hưởng việc chính tin nhắn inbound có thể kích hoạt trả lời hay không. Ủy quyền trigger vẫn đến từ groupPolicy, groups, groupAllowFrom, và các thiết lập chính sách DM.

Chính sách DM và phòng

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

Để tắt hoàn toàn DM trong khi vẫn giữ phòng hoạt động, đặt dm.enabled: false:

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

Xem Nhóm để biết hành vi kiểm soát bằng mention và allowlist. Ví dụ ghép nối cho DM Matrix:

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

Nếu một người dùng Matrix chưa được phê duyệt tiếp tục nhắn tin cho bạn trước khi được phê duyệt, OpenClaw tái sử dụng cùng mã ghép nối đang pending và có thể gửi trả lời nhắc nhở sau một khoảng cooldown ngắn thay vì tạo mã mới. Xem Ghép nối để biết luồng ghép nối DM dùng chung và bố cục lưu trữ.

Sửa phòng trực tiếp

Nếu trạng thái tin nhắn trực tiếp bị lệch đồng bộ, OpenClaw có thể có các mapping m.direct cũ trỏ tới các phòng solo cũ thay vì DM đang hoạt động. Kiểm tra mapping hiện tại cho một đối tác:

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

Sửa nó:

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

Cả hai lệnh đều chấp nhận --account <id> cho các thiết lập nhiều tài khoản. Luồng sửa:

ưu tiên DM 1:1 nghiêm ngặt đã được mapping trong m.direct
quay về bất kỳ DM 1:1 nghiêm ngặt đang tham gia nào với người dùng đó
tạo một phòng trực tiếp mới và ghi lại m.direct nếu không có DM khỏe mạnh nào tồn tại

Nó không tự động xóa các phòng cũ. Nó chọn DM khỏe mạnh và cập nhật mapping để các lần gửi Matrix trong tương lai, thông báo xác minh, và các luồng tin nhắn trực tiếp khác nhắm tới đúng phòng.

Phê duyệt exec

Matrix có thể hoạt động như một client phê duyệt native. Cấu hình dưới channels.matrix.execApprovals (hoặc channels.matrix.accounts.<account>.execApprovals cho ghi đè theo từng tài khoản):

enabled: gửi phê duyệt qua prompt native của Matrix. Khi chưa đặt hoặc là "auto", Matrix tự động bật khi có thể phân giải ít nhất một người phê duyệt. Đặt false để tắt rõ ràng.
approvers: ID người dùng Matrix (@owner:example.org) được phép phê duyệt yêu cầu exec. Tùy chọn - quay về channels.matrix.dm.allowFrom.
target: nơi gửi prompt. "dm" (mặc định) gửi tới DM của người phê duyệt; "channel" gửi tới phòng Matrix hoặc DM khởi nguồn; "both" gửi tới cả hai.
agentFilter / sessionFilter: allowlist tùy chọn cho những agent/phiên kích hoạt việc gửi qua Matrix.

Ủy quyền hơi khác nhau giữa các loại phê duyệt:

Phê duyệt exec dùng execApprovals.approvers, quay về dm.allowFrom.
Phê duyệt Plugin ủy quyền chỉ qua dm.allowFrom.

Cả hai loại dùng chung shortcut phản ứng Matrix và cập nhật tin nhắn. Người phê duyệt thấy shortcut phản ứng trên tin nhắn phê duyệt chính:

✅ cho phép một lần
❌ từ chối
♾️ luôn cho phép (khi chính sách exec hiệu lực cho phép)

Lệnh slash dự phòng: /approve <id> allow-once, /approve <id> allow-always, /approve <id> deny. Chỉ người phê duyệt đã được phân giải mới có thể phê duyệt hoặc từ chối. Việc gửi qua kênh cho phê duyệt exec bao gồm văn bản lệnh - chỉ bật channel hoặc both trong các phòng đáng tin cậy. Liên quan: Phê duyệt exec.

Lệnh slash

Lệnh slash (/new, /reset, /model, /focus, /unfocus, /agents, /session, /acp, /approve, v.v.) hoạt động trực tiếp trong DM. Trong phòng, OpenClaw cũng nhận diện các lệnh có tiền tố là mention Matrix của chính bot, vì vậy @bot:server /new kích hoạt đường dẫn lệnh mà không cần regex mention tùy chỉnh. Điều này giúp bot phản hồi với các bài đăng kiểu phòng @mention /command mà Element và các client tương tự phát ra khi người dùng dùng tab-complete bot trước khi nhập lệnh. Quy tắc ủy quyền vẫn áp dụng: người gửi lệnh phải thỏa mãn cùng chính sách chủ sở hữu/allowlist DM hoặc phòng như tin nhắn thường.

Nhiều tài khoản

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

Kế thừa:

Các giá trị channels.matrix cấp cao nhất đóng vai trò mặc định cho các tài khoản được đặt tên, trừ khi một tài khoản ghi đè chúng.
Giới hạn phạm vi một mục phòng được kế thừa cho một tài khoản cụ thể bằng groups.<room>.account. Các mục không có account được chia sẻ giữa các tài khoản; account: "default" vẫn hoạt động khi tài khoản mặc định được cấu hình ở cấp cao nhất.

Chọn tài khoản mặc định:

Đặt defaultAccount để chọn tài khoản được đặt tên mà định tuyến ngầm định, probing, và lệnh CLI ưu tiên.
Nếu bạn có nhiều tài khoản và một tài khoản đúng nghĩa được đặt tên là default, OpenClaw dùng nó ngầm định ngay cả khi defaultAccount chưa đặt.
Nếu bạn có nhiều tài khoản được đặt tên và chưa chọn mặc định, lệnh CLI từ chối đoán - đặt defaultAccount hoặc truyền --account <id>.
Khối channels.matrix.* cấp cao nhất chỉ được xem là tài khoản default ngầm định khi auth của nó hoàn chỉnh (homeserver + accessToken, hoặc homeserver + userId + password). Các tài khoản được đặt tên vẫn có thể được phát hiện từ homeserver + userId khi thông tin xác thực đã cache bao phủ auth.

Thăng cấp:

Khi OpenClaw thăng cấp cấu hình một tài khoản thành nhiều tài khoản trong quá trình sửa hoặc thiết lập, nó giữ nguyên tài khoản được đặt tên hiện có nếu có hoặc nếu defaultAccount đã trỏ tới một tài khoản. Chỉ các khóa auth/bootstrap Matrix được chuyển vào tài khoản đã thăng cấp; các khóa chính sách gửi dùng chung vẫn ở cấp cao nhất.

Xem Tham chiếu cấu hình để biết mẫu nhiều tài khoản dùng chung.

Homeserver riêng/LAN

Theo mặc định, OpenClaw chặn homeserver Matrix riêng/nội bộ để bảo vệ khỏi SSRF trừ khi bạn chủ động chọn tham gia theo từng tài khoản. Nếu homeserver của bạn chạy trên localhost, IP LAN/Tailscale, hoặc hostname nội bộ, hãy bật network.dangerouslyAllowPrivateNetwork cho tài khoản Matrix đó:

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

Ví dụ thiết lập CLI:

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

Lựa chọn bật này chỉ cho phép các đích riêng tư/nội bộ đáng tin cậy. Các máy chủ nhà công khai dùng văn bản rõ như http://matrix.example.org:8008 vẫn bị chặn. Ưu tiên https:// bất cứ khi nào có thể.

Proxy lưu lượng Matrix

Nếu bản triển khai Matrix của bạn cần proxy HTTP(S) đi ra rõ ràng, hãy đặt channels.matrix.proxy:

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

Các tài khoản có tên có thể ghi đè mặc định cấp cao nhất bằng channels.matrix.accounts.<id>.proxy. OpenClaw dùng cùng thiết lập proxy cho lưu lượng Matrix khi chạy và các phép dò trạng thái tài khoản.

Phân giải đích

Matrix chấp nhận các dạng đích này ở bất cứ nơi nào OpenClaw yêu cầu bạn cung cấp đích phòng hoặc người dùng:

Người dùng: @user:server, user:@user:server, hoặc matrix:user:@user:server
Phòng: !room:server, room:!room:server, hoặc matrix:room:!room:server
Bí danh: #alias:server, channel:#alias:server, hoặc matrix:channel:#alias:server

ID phòng Matrix phân biệt chữ hoa chữ thường. Hãy dùng đúng kiểu chữ của ID phòng từ Matrix khi cấu hình đích gửi rõ ràng, tác vụ cron, liên kết hoặc danh sách cho phép. OpenClaw giữ khóa phiên nội bộ ở dạng chuẩn tắc để lưu trữ, vì vậy các khóa chữ thường đó không phải là nguồn đáng tin cậy cho ID gửi của Matrix. Tra cứu thư mục trực tiếp dùng tài khoản Matrix đã đăng nhập:

Tra cứu người dùng truy vấn thư mục người dùng Matrix trên máy chủ nhà đó.
Tra cứu phòng chấp nhận trực tiếp ID phòng và bí danh rõ ràng. Tra cứu tên phòng đã tham gia là nỗ lực tối đa và chỉ áp dụng cho danh sách cho phép phòng khi chạy nếu đã đặt dangerouslyAllowNameMatching: true.
Nếu không thể phân giải tên phòng thành ID hoặc bí danh, tên đó sẽ bị bỏ qua trong quá trình phân giải danh sách cho phép khi chạy.

Tham chiếu cấu hình

Các trường người dùng kiểu danh sách cho phép (groupAllowFrom, dm.allowFrom, groups.<room>.users) chấp nhận ID người dùng Matrix đầy đủ (an toàn nhất). Các mục người dùng không phải ID mặc định bị bỏ qua. Nếu bạn đặt dangerouslyAllowNameMatching: true, các kết quả khớp chính xác tên hiển thị trong thư mục Matrix được phân giải khi khởi động và bất cứ khi nào danh sách cho phép thay đổi trong lúc bộ giám sát đang chạy; các mục không thể phân giải sẽ bị bỏ qua khi chạy. Khóa danh sách cho phép phòng (groups, rooms cũ) nên là ID phòng hoặc bí danh. Khóa tên phòng thuần túy mặc định bị bỏ qua; dangerouslyAllowNameMatching: true khôi phục tra cứu nỗ lực tối đa theo tên phòng đã tham gia.

Tài khoản và kết nối

enabled: bật hoặc tắt kênh.
name: nhãn hiển thị tùy chọn cho tài khoản.
defaultAccount: ID tài khoản ưu tiên khi cấu hình nhiều tài khoản Matrix.
accounts: các ghi đè theo từng tài khoản có tên. Các giá trị cấp cao nhất channels.matrix được kế thừa làm mặc định.
homeserver: URL máy chủ nhà, ví dụ https://matrix.example.org.
network.dangerouslyAllowPrivateNetwork: cho phép tài khoản này kết nối tới localhost, IP LAN/Tailscale hoặc tên máy chủ nội bộ.
proxy: URL proxy HTTP(S) tùy chọn cho lưu lượng Matrix. Hỗ trợ ghi đè theo từng tài khoản.
userId: ID người dùng Matrix đầy đủ (@bot:example.org).
accessToken: mã truy cập cho xác thực dựa trên mã. Hỗ trợ giá trị văn bản thuần và SecretRef trên các nhà cung cấp env/file/exec (Quản lý bí mật).
password: mật khẩu cho đăng nhập dựa trên mật khẩu. Hỗ trợ giá trị văn bản thuần và SecretRef.
deviceId: ID thiết bị Matrix rõ ràng.
deviceName: tên hiển thị của thiết bị dùng tại thời điểm đăng nhập bằng mật khẩu.
avatarUrl: URL ảnh đại diện tự thân đã lưu cho đồng bộ hồ sơ và cập nhật profile set.
initialSyncLimit: số sự kiện tối đa được lấy trong quá trình đồng bộ khởi động.

Mã hóa

encryption: bật E2EE. Mặc định: false.
startupVerification: "if-unverified" (mặc định khi E2EE bật) hoặc "off". Tự động yêu cầu tự xác minh khi khởi động nếu thiết bị này chưa được xác minh.
startupVerificationCooldownHours: thời gian chờ trước yêu cầu khởi động tự động tiếp theo. Mặc định: 24.

Truy cập và chính sách

groupPolicy: "open", "allowlist", hoặc "disabled". Mặc định: "allowlist".
groupAllowFrom: danh sách cho phép ID người dùng cho lưu lượng phòng.
dm.enabled: khi false, bỏ qua tất cả DM. Mặc định: true.
dm.policy: "pairing" (mặc định), "allowlist", "open", hoặc "disabled". Áp dụng sau khi bot đã tham gia và phân loại phòng là DM; không ảnh hưởng đến xử lý lời mời.
dm.allowFrom: danh sách cho phép ID người dùng cho lưu lượng DM.
dm.sessionScope: "per-user" (mặc định) hoặc "per-room".
dm.threadReplies: ghi đè chỉ dành cho DM đối với phân luồng trả lời ("off", "inbound", "always").
allowBots: chấp nhận tin nhắn từ các tài khoản bot Matrix đã cấu hình khác (true hoặc "mentions").
allowlistOnly: khi true, buộc tất cả chính sách DM đang hoạt động (trừ "disabled") và chính sách nhóm "open" thành "allowlist". Không thay đổi chính sách "disabled".
dangerouslyAllowNameMatching: khi true, cho phép tra cứu thư mục tên hiển thị Matrix cho các mục danh sách cho phép người dùng và tra cứu tên phòng đã tham gia cho khóa danh sách cho phép phòng. Ưu tiên ID @user:server đầy đủ và ID phòng hoặc bí danh.
autoJoin: "always", "allowlist", hoặc "off". Mặc định: "off". Áp dụng cho mọi lời mời Matrix, bao gồm lời mời kiểu DM.
autoJoinAllowlist: phòng/bí danh được phép khi autoJoin là "allowlist". Các mục bí danh được phân giải theo máy chủ nhà, không theo trạng thái mà phòng mời tuyên bố.
contextVisibility: khả năng hiển thị ngữ cảnh bổ sung ("all" mặc định, "allowlist", "allowlist_quote").

Hành vi trả lời

replyToMode: "off", "first", "all", hoặc "batched".
threadReplies: "off", "inbound", hoặc "always".
threadBindings: ghi đè theo từng kênh cho định tuyến phiên gắn với luồng và vòng đời.
streaming: "off" (mặc định), "partial", "quiet", hoặc dạng đối tượng { mode, preview: { toolProgress } }. true ↔ "partial", false ↔ "off".
blockStreaming: khi true, các khối trợ lý đã hoàn tất được giữ làm tin nhắn tiến trình riêng biệt.
markdown: cấu hình kết xuất Markdown tùy chọn cho văn bản gửi đi.
responsePrefix: chuỗi tùy chọn được thêm vào trước các trả lời gửi đi.
textChunkLimit: kích thước đoạn gửi đi tính bằng ký tự khi chunkMode: "length". Mặc định: 4000.
chunkMode: "length" (mặc định, tách theo số ký tự) hoặc "newline" (tách tại ranh giới dòng).
historyLimit: số tin nhắn phòng gần đây được bao gồm dưới dạng InboundHistory khi tin nhắn phòng kích hoạt tác nhân. Quay về messages.groupChat.historyLimit; mặc định hiệu lực là 0 (tắt).
mediaMaxMb: giới hạn kích thước phương tiện tính bằng MB cho gửi đi và xử lý đến.

Thiết lập phản ứng

ackReaction: ghi đè phản ứng xác nhận cho kênh/tài khoản này.
ackReactionScope: ghi đè phạm vi ("group-mentions" mặc định, "group-all", "direct", "all", "none", "off").
reactionNotifications: chế độ thông báo phản ứng đến ("own" mặc định, "off").

Công cụ và ghi đè theo phòng

actions: kiểm soát công cụ theo từng hành động (messages, reactions, pins, profile, memberInfo, channelInfo, verification).
groups: bản đồ chính sách theo từng phòng. Danh tính phiên dùng ID phòng ổn định sau khi phân giải. (rooms là bí danh cũ.)
- groups.<room>.account: giới hạn một mục phòng kế thừa vào một tài khoản cụ thể.
- groups.<room>.allowBots: ghi đè theo từng phòng của thiết lập cấp kênh (true hoặc "mentions").
- groups.<room>.users: danh sách cho phép người gửi theo từng phòng.
- groups.<room>.tools: ghi đè cho phép/từ chối công cụ theo từng phòng.
- groups.<room>.autoReply: ghi đè kiểm soát yêu cầu nhắc đến theo từng phòng. true tắt yêu cầu nhắc đến cho phòng đó; false buộc bật lại.
- groups.<room>.skills: bộ lọc Skills theo từng phòng.
- groups.<room>.systemPrompt: đoạn lời nhắc hệ thống theo từng phòng.

Thiết lập phê duyệt exec

execApprovals.enabled: gửi phê duyệt exec qua lời nhắc gốc Matrix.
execApprovals.approvers: ID người dùng Matrix được phép phê duyệt. Quay về dm.allowFrom.
execApprovals.target: "dm" (mặc định), "channel", hoặc "both".
execApprovals.agentFilter / execApprovals.sessionFilter: danh sách cho phép tác nhân/phiên tùy chọn để gửi.

Liên quan

Tổng quan về kênh - tất cả kênh được hỗ trợ
Ghép nối - xác thực DM và luồng ghép nối
Nhóm - hành vi trò chuyện nhóm và kiểm soát yêu cầu nhắc đến
Định tuyến kênh - định tuyến phiên cho tin nhắn
Bảo mật - mô hình truy cập và gia cố

Documentation Index

​Cài đặt

​Thiết lập

​Thiết lập tương tác

​Cấu hình tối thiểu

​Tự động tham gia

​Định dạng mục tiêu allowlist

​Chuẩn hóa ID tài khoản

​Thông tin xác thực được lưu vào bộ nhớ đệm

​Biến môi trường

​Ví dụ cấu hình

​Bản xem trước streaming

​Siêu dữ liệu phê duyệt

​Quy tắc push tự host cho bản xem trước cuối yên lặng

​Phòng bot-với-bot

​Mã hóa và xác minh

​Bật mã hóa

​Trạng thái và tín hiệu tin cậy

​Xác minh thiết bị này bằng khóa khôi phục

​Khởi tạo hoặc sửa ký chéo

​Sao lưu khóa phòng

​Liệt kê, yêu cầu và phản hồi xác minh

​Ghi chú nhiều tài khoản

​Quản lý hồ sơ

​Luồng

​Định tuyến phiên (sessionScope)

​Tạo luồng trả lời (threadReplies)

​Kế thừa luồng và lệnh gạch chéo

​Binding cuộc hội thoại ACP

​Cấu hình binding luồng

​Phản ứng

​Ngữ cảnh lịch sử

​Khả năng hiển thị ngữ cảnh

​Chính sách DM và phòng

​Sửa phòng trực tiếp

​Phê duyệt exec

​Lệnh slash

​Nhiều tài khoản

​Homeserver riêng/LAN

​Proxy lưu lượng Matrix

​Phân giải đích

​Tham chiếu cấu hình

​Tài khoản và kết nối

​Mã hóa

​Truy cập và chính sách

​Hành vi trả lời

​Thiết lập phản ứng

​Công cụ và ghi đè theo phòng

​Thiết lập phê duyệt exec

​Liên quan

Cài đặt

Thiết lập

Thiết lập tương tác

Cấu hình tối thiểu

Tự động tham gia

Định dạng mục tiêu allowlist

Chuẩn hóa ID tài khoản

Thông tin xác thực được lưu vào bộ nhớ đệm

Biến môi trường

Ví dụ cấu hình

Bản xem trước streaming

Siêu dữ liệu phê duyệt

Quy tắc push tự host cho bản xem trước cuối yên lặng

Phòng bot-với-bot

Mã hóa và xác minh

Bật mã hóa

Trạng thái và tín hiệu tin cậy

Xác minh thiết bị này bằng khóa khôi phục

Khởi tạo hoặc sửa ký chéo

Sao lưu khóa phòng

Liệt kê, yêu cầu và phản hồi xác minh

Ghi chú nhiều tài khoản

Quản lý hồ sơ

Luồng

Định tuyến phiên (`sessionScope`)

Tạo luồng trả lời (`threadReplies`)

Kế thừa luồng và lệnh gạch chéo

Binding cuộc hội thoại ACP

Cấu hình binding luồng

Phản ứng

Ngữ cảnh lịch sử

Khả năng hiển thị ngữ cảnh

Chính sách DM và phòng

Sửa phòng trực tiếp

Phê duyệt exec

Lệnh slash

Nhiều tài khoản

Homeserver riêng/LAN

Proxy lưu lượng Matrix

Phân giải đích

Tham chiếu cấu hình

Tài khoản và kết nối

Mã hóa

Truy cập và chính sách

Hành vi trả lời

Thiết lập phản ứng

Công cụ và ghi đè theo phòng

Thiết lập phê duyệt exec

Liên quan