WebUI

WebUI 是 OlivOS 自带的浏览器管理界面，可管理账号、查看日志和终端、管理插件，并打开插件提供的网页。需要使用包含 WebUI 功能的 OlivOS 核心。

打开与登录

启动 OlivOS，等待日志出现 WebUI 已启动。默认地址是 http://127.0.0.1:20480，日志也会显示实际监听地址和认证文件路径。
Windows 可以从右下角托盘选择“打开 WebUI”；Linux、macOS 或无桌面环境可使用浏览器访问日志中的地址。
打开 OlivOS 工作目录下的 conf/webui_token.txt，在登录页输入其中的令牌。

WebUI 端口被占用时会自动向后顺延，例如 20480 → 20481 → 20482，直到找到可用端口。启动日志和 Windows 托盘“打开 WebUI”使用实际端口，不会改写用户配置。多个 OlivOS 实例应使用独立工作目录；此行为仅适用于 WebUI，不改变机器人协议端的端口。使用 SSH 转发时，远端端口也应填写日志中的实际端口。

登录成功后，当前浏览器的本地存储会保存仅对本次 OlivOS 运行有效的登录凭据；同一次运行中，刷新页面、重新打开浏览器或访问同一地址时仍会自动登录。关闭 OlivOS 后重新启动，需要重新输入 conf/webui_token.txt 中的令牌，文件内容不会因重启改变。点击“退出登录”或缓存凭据认证失效时会清除缓存。

管理界面收到认证失败响应时会关闭弹窗和连接、清除登录状态并返回登录页。页面每 10 秒及重新获得焦点时检查认证或缓存；其他标签页退出或清除缓存时同步退出。网络暂时中断不会清除登录缓存。

认证文件不存在时，WebUI 会自动生成令牌并写入该文件；后续启动继续使用此文件。核心不会自动读取或迁移旧的 data/webui_token、data/webui_token.txt。不要把令牌写入插件代码、网页地址或日志。

127.0.0.1 指运行 OlivOS 的机器。远程服务器推荐通过 SSH 转发访问，例如在自己的电脑运行：

ssh -L 20480:127.0.0.1:20480 user@server

然后在本机访问 http://127.0.0.1:20480。user@server 替换为自己的 SSH 登录地址。

页面

页面	内容
仪表盘	核心版本、账号数量、连接状态及未知状态的账号明细、运行时长、更新检查、重载插件、社区论坛与退出
账号	查看基本信息、连接状态及 `bot_hash`，新增、编辑、删除、启停账号，保存并应用配置
日志	按级别筛选日志、自动滚动和实时日志
终端	已启动协议端的终端输出、输入和登录二维码
插件	插件列表、路径、菜单及插件重载
插件页面	插件通过 `webui_config` 注册的内嵌页面或外部链接

日志级别支持多选，默认勾选 INFO、WARN、ERROR、FATAL。筛选精确匹配所选级别，例如只勾选 INFO 和 WARN 时不会显示其他级别。每个级别默认独立保留最近 500 条，DEBUG 不会挤掉 INFO；所选级别合并后或选择“全部”时，页面最多显示最近 500 条。不勾选任何级别时暂停日志订阅并清空显示。需要调整时可覆盖 server.buffer_limit（范围 8–4096）；已有显式配置会继续使用用户设置。

终端只显示已经启动并被核心接入的协议端，不是任意系统命令终端。账号“在线”状态也不等于“已启用”：没有可用连接状态时，界面会明确提示。

账号页中的编辑先保存在网页草稿，点击“保存并应用”才写入账号文件。该操作不会重启整个 OlivOS，但默认会停止并重建 account_update 配置中的账号连接组件，可能影响多个账号并导致短暂断线重连；主进程、插件进程和 WebUI 继续运行。成功提示表示配置已保存并发起应用，不表示全部连接已经恢复。

已有账号配置保存前会生成同目录的 .webui-backup 文件，例如 conf/account.json.webui-backup。备份也可能包含账号凭据，应按原配置文件同样管理。

外观

登录页及登录后的侧栏均可选择“浅色”“深色”或“跟随系统”，选择会保存在当前浏览器。插件页面使用自己的网页样式。

内置默认值与用户配置

WebUI 默认启用，不需要在 conf/config.json 中预置 OlivOS_webUI。组件定义及默认参数内置于核心 OlivOS/core/boot/bootDataAPI.py，服务端也会补齐未指定的参数。

conf/config.json 仅用于用户主动设置的覆盖项，随项目提供的文件不重复写入这组默认值。正常使用无需修改；只有需要更换端口、监听地址或关闭 WebUI 时，才按核心的配置覆盖机制修改 models.OlivOS_webUI 下对应的用户设置，并重启 OlivOS 生效。部署脚本也可以使用环境变量设置监听地址和端口。

内置字段	默认值	说明
enable	`true`	启动 WebUI
server.host	`127.0.0.1`	默认只允许本机访问
server.port	`20480`	HTTP 与 WebSocket 共用的监听端口
server.token_path	`./conf/webui_token.txt`	认证文件路径，相对 OlivOS 工作目录
server.static_path	`./data/webui/static`	核心静态资源释放目录，启动时由内嵌资源更新
server.buffer_limit	`500`	每个日志级别及全部日志各自的上限，也用于终端和事件缓冲
server.plugin_page_cache	`10`	插件页面保活数量上限（1~20），超出时淘汰最久未使用的页面

环境变量 OLIVOS_WEBUI_HOST 和 OLIVOS_WEBUI_PORT 分别覆盖 server.host 和 server.port，优先级高于 conf/config.json，适合容器、启动脚本和临时部署。端口必须是 0 至 65535 的整数，0 表示由操作系统分配可用端口；空地址或无效端口会被忽略并继续使用配置值。启动后以日志和托盘使用的实际监听端口为准，环境变量不会写回配置文件。将地址设为 0.0.0.0 或 :: 会监听所有网卡，只有在网络访问确实需要时才这样设置，并继续保护好 WebUI 令牌。

需要修改时再添加

如果需要修改 WebUI，在现有 conf/config.json 中合并下面的配置，再修改所需的值。示例列出的是默认值，不是启用 WebUI 的必填配置；不要用此片段覆盖文件中的其他用户设置，已有 models 时将 OlivOS_webUI 加入该对象即可。

{
    "models": {
        "OlivOS_webUI": {
            "enable": true,
            "server": {
                "auto": false,
                "type": "http",
                "host": "127.0.0.1",
                "port": 20480,
                "token_path": "./conf/webui_token.txt",
                "static_path": "./data/webui/static",
                "buffer_limit": 500,
                "plugin_page_cache": 10
            }
        }
    }
}

例如，更换监听端口时修改 port；关闭 WebUI 时将 enable 改为 false。修改后重启 OlivOS。保持默认行为时，可以完全省略 OlivOS_webUI，由核心使用内置配置。只使用环境变量时，可以不在 conf/config.json 中写 server.host 和 server.port：

OLIVOS_WEBUI_HOST=127.0.0.1 OLIVOS_WEBUI_PORT=20480 python main.py

Windows PowerShell 使用 $env:OLIVOS_WEBUI_HOST = '127.0.0.1' 和 $env:OLIVOS_WEBUI_PORT = '20480' 后再启动 OlivOS。环境变量只控制监听地址和端口，不会关闭 WebUI，也不会改变令牌文件路径。

插件页面

插件作者需要提供网页并注册入口，核心不会把 Python 设置项或原生 GUI 自动转换为网页。普通插件菜单仍能在“插件”页调用；带原生窗口的菜单不一定适合无桌面环境。

侧栏按插件组织页面：只有一个入口时，点击插件直接打开页面，不增加子入口层级；多个入口时，点击插件名称只展开或收起，再选择所需的功能页面或外部链接，右侧数字表示子入口数量。收起只隐藏入口，不关闭页面。每个功能子页面仍可独立打开、切换和关闭。

插件重名时，分组会额外显示命名空间；同一插件内的子入口重名时，会额外显示页面路径或链接地址，方便区分。

关闭按钮的悬停说明和关闭后的提示会带上插件名称及页面标题，重名时补充命名空间或路径，与侧栏保持一致。关闭全部页面时，提示会分别统计涉及的插件数和页面数。

插件页面打开后会保持存活：切到日志、终端等其他页面再切回来不会重新加载，页面内的编辑内容与滚动位置都会保留。侧栏每个插件页面条目右侧有一个 × 单独关闭它，标题栏“插件页面”右侧的 × 一次关闭全部。同时保活的页面数量由 server.plugin_page_cache 控制（默认 10），超出后最久未打开的页面会被自动释放；刷新浏览器会清空全部保活页面并只重建当前停留的那一个。

开发入口见 WebUI 页面开发和官方插件模板。