配置方法¶

SDK 的所有能力都从 OopzConfig 开始。

from oopz_sdk import OopzConfig, RetryConfig, HeartbeatConfig, ProxyConfig

config = OopzConfig.from_env(
    retry=RetryConfig(max_attempts=3),
    heartbeat=HeartbeatConfig(interval=10.0, reconnect_interval=2.0),
    proxy=ProxyConfig(http="http://127.0.0.1:7890", https="http://127.0.0.1:7890"),
)

登录方法详见认证与凭据

接受来自域的事件推送¶

默认情况下, SDK是不会收到来自域的事件 (例如域的设置更改, 用户进入退出房间等) 推送的, 需要进行手动注册。

您可以使用 send_subscribe_area_events 方法在bot启动后订阅特定域的事件：

area_ids = ["6bv5677gsfdb41e882694531567a0972"]  # 替换为你想订阅的域 ID

await bot.ws.send_subscribe_area_events(area_ids)

您也可以使用 auto_subscribe_joined_areas 选项在启动时自动订阅所有已加入域的事件：

注意

Oopz web端一般只会使用单个area_ids进行请求, 但是经过测试, 这个接口是支持批量订阅的, 但是传入多个area_ids造成的风险和问题目前还不清楚, 请谨慎使用多个域的事件订阅和auto_subscribe_joined_areas功能。

from oopz_sdk import OopzBot, OopzConfig

config = OopzConfig(
    auto_subscribe_joined_areas=True,
)

config.login("手机号", "密码")

bot = OopzBot(config)

@bot.on_ready
async def ready(ctx):
    print("Bot ready, joined area events subscribed")

这个功能会在机器人启动后自动查询已加入的域，并订阅这些域的事件推送。这样当有用户进入退出房间、域设置更改等事件时，机器人就能及时收到通知。

通过账号密码自动提取凭证¶

SDK 内置了一个基于 OOPZ Web 登录页的提取工具，会自动登录并从登录接口、请求头、WebSocket 鉴权消息和 Web Crypto 私钥钩子中提取 device_id、person_uid、jwt_token 和 private_key。

首次使用前需要安装 Chromium：

python -m playwright install chromium

命令行方式：

$env:OOPZ_LOGIN_PHONE = "你的 OOPZ 登录账号"
python -m oopz_sdk.cli.password_login --phone $env:OOPZ_LOGIN_PHONE --print-env powershell

如果登录过程需要人工验证，可以显示浏览器窗口：

python -m oopz_sdk.cli.password_login --phone $env:OOPZ_LOGIN_PHONE --headful --print-env powershell

命令会安全询问密码，并在成功后输出可设置 OOPZ_DEVICE_ID、OOPZ_PERSON_UID、OOPZ_JWT_TOKEN、OOPZ_PRIVATE_KEY 的环境变量命令。把这些命令只复制到本地 shell 执行，不要提交到仓库。

在代码中直接登录并创建配置：

import asyncio

from oopz_sdk import OopzConfig


async def main():
    config = await OopzConfig.from_env_async()
    print(config.person_uid)


asyncio.run(main())

以下设置一般不需要修改，除非你有特殊需求，例如使用代理或调整重试策略。

网关与请求配置¶

字段	默认值	说明
`base_url`	`https://gateway.oopz.cn`	Oopz的HTTP API 地址。
`ws_url`	`wss://ws.oopz.cn`	Oopz的WebSocket 网关地址。
`app_version`	`69514`	客户端版本标识。
`channel`	`Web`	客户端渠道。
`platform`	`windows`	平台标识。
`web`	`True`	是否按 Web 客户端行为发送。
`headers`	`{}`	额外请求头，会覆盖默认头。

重试配置 `RetryConfig`¶

字段	默认值	说明
`max_attempts`	`3`	最大尝试次数。

请求配置 `RequestConfig`¶

| timeout | (10, 30) | 连接超时和读取超时。 |

全局请求频率限制配置 `RateLimitConfig`¶

| interval | 0.0 | 全局请求之间的基础间隔，也兼容 config.rate_limit_interval。 |

心跳配置 `HeartbeatConfig`¶

字段	默认值	说明
`interval`	`10.0`	WebSocket 心跳间隔。
`reconnect_interval`	`2.0`	初始重连间隔。
`max_reconnect_interval`	`120.0`	最大重连间隔。

代理配置 `ProxyConfig`¶

字段	说明
`http`	HTTP 请求代理。
`https`	HTTPS 请求代理。
`websocket`	WebSocket 代理。

示例：

config = OopzConfig(
    ...,
    proxy=ProxyConfig(
        http="http://127.0.0.1:7890",
        https="http://127.0.0.1:7890",
        websocket="http://127.0.0.1:7890",
    ),
)

消息配置¶

字段	默认值	说明
`ignore_self_messages`	`True`	忽略自己发出的消息，避免机器人回复自己导致循环。
`use_announcement_style`	`False`	频道消息默认加 `IMPORTANT` 样式。

缓存配置¶

字段	默认值	说明
`area_members_cache_ttl`	`15.0`	域成员分页缓存有效期。
`area_members_stale_ttl`	`300.0`	预留的过期缓存时间。
`cache_max_entries`	`200`	缓存最大条目；小于等于 0 表示关闭缓存。

语音配置¶

字段	默认值	说明
`agora_app_id`	SDK 内置值	Agora App ID。
`agora_init_timeout`	`1800`	语音后端初始化超时。
`voice_backend`	`browser`	当前实现使用浏览器后端。
`voice_browser_headless`	`True`	是否无头运行浏览器。
`voice_browser_executable_path`	`""`	自定义 Chromium 路径。
`voice_agora_sdk_url`	Agora 官方 JS SDK URL	浏览器后端加载的 Agora SDK。

OneBot 配置¶

详见 OneBot 适配。