配置（Config）

Matrix 适配器使用 Pydantic 模型管理配置，支持从 .env 文件和环境变量自动加载。

class nonebot.adapters.matrix.config.BotInfo(**data)

基类：BaseModel

参数:

• homeserver (str)

• access_token (str)

• refresh_token (str | None)

• access_token_expires_at_ms (int | None)

• refresh_before_expiry_ms (int)

• user_id (str | None)

• device_id (str | None)

• sync_filter (str | dict[str, Any] | None)

• set_presence (Literal['online', 'offline', 'unavailable'] | None)

• login_user (str | None)

• login_password (str | None)

• login_initial_device_display_name (str | None)

• oauth_enabled (bool)

• oauth_server_url (str | None)

• oauth_metadata_url (str | None)

• oauth_client_id (str | None)

• oauth_client_uri (str | None)

• oauth_redirect_uri (str | None)

• oauth_scope (str | None)

• oauth_device_id (str | None)

• oauth_open_browser (bool)

• oauth_callback_timeout (float)

• auto_accept_invites (bool)

• auto_accept_whitelist (list[str] | None)

• auto_accept_blacklist (list[str])

• e2ee_enabled (bool)

• auto_enable_cross_signing (bool)

• auto_enable_backups (bool)

• backup_download_strategy (Literal['Manual', 'OneShot', 'AfterDecryptionFailure'])

• encryption_sharing_strategy (Literal['AllDevices', 'ErrorOnVerifiedUserProblem', 'IdentityBasedStrategy', 'OnlyTrustedDevices'])

• recovery_key (str | None)

• recovery_code (str | None)

• secret_storage_passphrase (str | None)

• e2ee_store_path (str | None)

• session_type (str | None)

• oauth_token_endpoint (str | None)

homeserver: str

access_token: str

refresh_token: str | None

access_token_expires_at_ms: int | None

refresh_before_expiry_ms: int

user_id: str | None

device_id: str | None

sync_filter: str | dict[str, Any] | None

set_presence: Optional[Literal['online', 'offline', 'unavailable']]

login_user: str | None

login_password: str | None

login_initial_device_display_name: str | None

oauth_enabled: bool

oauth_server_url: str | None

oauth_metadata_url: str | None

oauth_client_id: str | None

oauth_client_uri: str | None

oauth_redirect_uri: str | None

oauth_scope: str | None

oauth_device_id: str | None

oauth_open_browser: bool

oauth_callback_timeout: float

auto_accept_invites: bool

auto_accept_whitelist: list[str] | None

auto_accept_blacklist: list[str]

e2ee_enabled: bool

auto_enable_cross_signing: bool

auto_enable_backups: bool

backup_download_strategy: Literal['Manual', 'OneShot', 'AfterDecryptionFailure']

encryption_sharing_strategy: Literal['AllDevices', 'ErrorOnVerifiedUserProblem', 'IdentityBasedStrategy', 'OnlyTrustedDevices']

recovery_key: str | None

recovery_code: str | None

secret_storage_passphrase: str | None

e2ee_store_path: str | None

session_type: str | None

oauth_token_endpoint: str | None

validate_recovery_credentials()

返回类型:

BotInfo

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class nonebot.adapters.matrix.config.Config(**data)

基类：BaseModel

参数:

• matrix_bots (list[BotInfo])

• matrix_api_timeout (float)

• matrix_sync_timeout (int)

• matrix_retry_interval (float)

• matrix_command_to_me (bool)

• matrix_auto_accept_verification (bool)

• matrix_handle_self_message (bool)

• matrix_handle_old_events (bool)

• matrix_proxy (str | None)

• matrix_token_store_path (str | None)

matrix_bots: list[BotInfo]

matrix_api_timeout: float

matrix_sync_timeout: int

matrix_retry_interval: float

matrix_command_to_me: bool

matrix_auto_accept_verification: bool

matrix_handle_self_message: bool

matrix_handle_old_events: bool

matrix_proxy: str | None

matrix_token_store_path: str | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

配置模型

Config

• matrix_bots — 机器人配置列表（对应 MATRIX_BOTS 环境变量）。

• matrix_api_timeout — 普通 API 超时（秒），默认 30.0。

• matrix_sync_timeout — /sync long-poll 超时（毫秒），默认 30000。

• matrix_retry_interval — 网络错误重试间隔（秒），默认 3.0。

• matrix_command_to_me — 是否将以 NoneBot 命令前缀开头的消息视为发给机器人，默认 false。

• matrix_handle_self_message — 是否处理自己的消息，默认 false。

• matrix_handle_old_events — 是否处理启动前的旧事件，默认 false。

• matrix_proxy — HTTP 代理地址，默认 None。

• matrix_token_store_path — Token 持久化文件路径，默认 None。

BotInfo

每个机器人的独立配置项，对应 MATRIX_BOTS 数组中的每个对象。

连接配置

• homeserver — Matrix homeserver 根地址（必填）。

• access_token — 当前 access token。

• refresh_token — Refresh token（登录后获得）。

• access_token_expires_at_ms — Token 过期时间（毫秒时间戳）。

• refresh_before_expiry_ms — 提前刷新阈值（毫秒），默认 60000。

• user_id — 校验 token 所属用户。

• device_id — 设备标识符。

• sync_filter — /sync filter，可为 filter ID 字符串或 filter JSON。

• set_presence — 在线状态："online" / "offline" / "unavailable"。

传统登录凭据

• login_user — 登录用户名。

• login_password — 登录密码。

• login_initial_device_display_name — 初始设备显示名。

OAuth2 配置

• oauth_enabled — 是否启用 OAuth2 流程。

• oauth_server_url — OAuth2/OIDC server 根地址。

• oauth_metadata_url — Metadata 文档地址。

• oauth_client_id — OAuth2 client ID。

• oauth_client_uri — 动态注册时的 client URI。

• oauth_redirect_uri — 回调 URI。

• oauth_scope — Authorization scope。

• oauth_device_id — 请求的设备 ID。

• oauth_open_browser — 是否自动打开浏览器。

• oauth_callback_timeout — 回调超时（秒）。

自动接受邀请

• auto_accept_invites — 是否启用自动接受。

• auto_accept_whitelist — 白名单（None 表示全员允许）。

• auto_accept_blacklist — 黑名单（优先级高于白名单）。

E2EE 配置

• e2ee_enabled — 是否初始化 E2EE，默认 True。

• auto_enable_cross_signing — 启动时自动创建交叉签名，默认关闭。

• auto_enable_backups — 启动时自动创建密钥备份，默认关闭。

• backup_download_strategy — Manual / OneShot / AfterDecryptionFailure。

• encryption_sharing_strategy — AllDevices / ErrorOnVerifiedUserProblem / IdentityBasedStrategy / OnlyTrustedDevices。

• recovery_key — Matrix recovery key（只读现有密钥备份）。

• recovery_code — MATRIX_RECOVERY_CODE（密钥恢复私钥）。

• secret_storage_passphrase — Secret Storage passphrase。

• matrix_auto_accept_verification — 只自动接受验证请求，不确认 SAS 或二维码（默认关闭）。

• e2ee_store_path — E2EE 持久化目录。

运行时字段（一般不需要手动设置）:

• session_type — "legacy_login" 或 "oauth2"。

• oauth_token_endpoint — OAuth2 refresh 端点。