跳转至

WebUI

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

打开与登录

  1. 启动 OlivOS，等待日志出现 WebUI 已启动。默认地址是 http://127.0.0.1:20480，日志也会显示实际监听地址和认证文件路径。
  2. Windows 可以从右下角托盘选择“打开 WebUI”，通过本机生成的一次性凭证自动登录；Linux、macOS 或无桌面环境可使用浏览器访问日志中的地址。
  3. 手动打开网页时输入 WebUI 密码。全新安装首次启动会在本机终端或窗口显示一次随机初始密码；无交互界面的后台部署应先通过下文的终端命令设置密码。

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

登录成功后，当前浏览器的本地存储会保存本次 OlivOS 运行中签发的随机登录凭据，不保存密码。刷新页面、重新打开浏览器或访问同一地址时仍会尝试自动登录；凭据有效期为 12 小时，正常续期会延长。重启 OlivOS 或修改密码会使原有登录失效，需要重新输入密码或从托盘打开。密码不会因重启改变。点击“退出登录”或缓存凭据认证失效时会清除缓存。

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

Windows 托盘自动登录使用 60 秒内有效且只能兑换一次的凭证，通过网址的 # 部分交给浏览器，页面读取后立即清除。网址不携带长期密码。不要将自动登录链接转发给其他人；链接已使用或过期时，从托盘重新打开即可。

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 登录地址。

密码存储与旧令牌迁移

密码默认保存在 OlivOS 工作目录的 conf/webui_auth.json。文件只包含格式版本、scrypt 算法及参数、随机盐、密码哈希和凭据版本号，不保存明文或 MD5。登录时由服务端使用相同的盐和参数验证密码；哈希本身不能当作密码登录，也不能从文件查看原密码。

首次升级时，如果新认证文件不存在而 conf/webui_token.txt 存在，核心会自动迁移：

  1. 将旧令牌作为密码，沿用旧版本去掉文件首尾空白的读取方式。
  2. 生成盐和哈希，安全写入新文件并验证成功。
  3. 在本机交互式终端或本机窗口显示一次原密码，再删除旧明文令牌文件。Windows 有可见桌面时，源码版和编译版均使用本机弹窗显示，点击“复制密码”按钮即可复制，也可在只读输入框中选中后手动复制。弹窗保持打开时，OlivOS 仍会继续启动并运行，无需先关闭窗口；托盘内置终端只展示普通日志，不显示密码。密码不会进入普通日志文件、WebUI 日志或重定向输出。

迁移后仍使用原来的那串令牌作为密码登录，不需要手动执行迁移命令。自定义 server.token_path 的实例从其指定路径迁移，新文件位置由 server.auth_path 指定；两个路径不能相同。核心仍不读取旧的 data/webui_token、data/webui_token.txt。

新文件存在时以新文件为准，不会因为新文件损坏而回退使用旧密码。迁移写入失败时保留旧文件；新文件损坏、旧文件为空或权限不足时仅停用 WebUI，其他 OlivOS 组件继续运行，需在本机检查权限或重置密码。新文件已经写入、旧文件尚未删除时中断的迁移，会在下次启动继续核对和清理。

没有交互式终端或本机窗口的后台部署不会输出密码，也不会在全新安装时生成一个无法获取的密码。请先在对应实例目录运行下文的命令设置密码，再启动服务。已有旧令牌的后台实例可以直接迁移并继续使用原令牌；忘记原令牌时通过本机重置。

新文件不包含可恢复的明文，迁移也不会额外生成明文密码备份。需要退回使用旧认证机制的核心版本时，应在本机重新设置旧版所需的令牌文件，不能直接将哈希复制进去。认证文件和其他备份都应按敏感配置管理。

修改或重置密码

修改和重置都只允许从本机操作，不需要提供原密码。权限来自运行实例的系统用户，WebUI 网页不提供修改或重置密码接口。

Windows

右键托盘图标，选择“修改 WebUI 密码”，隐藏输入两次新密码。两次输入一致且非空后保存；取消或输入不一致不会修改。输入按原样处理，支持中文和空格，UTF-8 编码后最长 1024 字节。

Linux、macOS 与终端使用

使用运行该实例的同一系统用户，在终端操作；远程服务器可通过 SSH 登录后执行。先进入对应实例的工作目录，也就是平时保存 conf/、plugin/ 等目录的位置，避免多实例时改错密码。

下载的可执行发布包（没有 main.py）

Linux 和 macOS 的可执行发布包入口名为 OlivOS，直接给可执行文件传入参数即可，不需要 main.py，也不需要另外安装 Python。进入实例工作目录后，如果可执行文件也在该目录，运行：

./OlivOS --reset-webui-password

如果文件曾被重命名，将 OlivOS 换成实际文件名；如果可执行文件在其他位置，保持当前目录为实例工作目录，使用它的绝对路径，例如 "/安装位置/OlivOS" --reset-webui-password。

解压后若提示 Permission denied，先在可执行文件所在目录为当前用户添加执行权限，再运行重置命令：

chmod u+x ./OlivOS

以上参数需要包含密码重置功能的新版发布包。旧版本不支持时应先升级，不能通过创建空的 main.py 或修改哈希文件来代替重置。

源码部署或带 Python 的完整包

源码部署使用启动该实例时的 Python 环境执行：

python main.py --reset-webui-password

以上入口均会在终端隐藏输入两次新密码。命令不接受明文密码参数，也不从重定向的标准输入读取密码，避免密码进入命令历史、进程列表或日志。

  • 实例正在运行：通过仅当前系统用户可访问的 Unix Socket（Linux、macOS）或本机命名管道（Windows）完成重置，立即生效，无需重启 OlivOS，也不重启机器人或插件。
  • 实例未运行：更新认证文件，下次启动生效；命令本身不会启动机器人。
  • 运行中但本机管理入口不可用：明确报错，不将操作悄悄降为离线文件修改，也不报告已立即生效。

修改成功后，旧密码、所有浏览器登录凭据、插件页面会话及尚未使用的一次性登录凭证都会失效，已有 WebSocket 连接关闭。已打开的 WebUI 返回登录界面，使用新密码或从托盘重新打开即可。

登录错误与请求日志

登录页面显示具体失败原因。核心不按公网/内网 IP 禁止登录，监听范围由 server.host 决定。

状态 含义及处理
401 密码不正确、凭据缺失/失效，或一次性凭证已使用/过期；按页面提示重新登录
429 同一连接来源最近 60 秒内已有 10 次认证失败；等待失败记录陆续过期后重试，最多约一分钟

429 期间即使密码正确也会暂时拒绝，返回的 Retry-After 为 60 秒，限流请求本身不会延长计时。重启或改密后，旧页面使用失效浏览器凭据恢复连接仍返回 401，但不计入密码失败次数，也不清除已有失败记录；重新输入密码仍受限流约束。限流使用直接连接的来源地址，不信任客户端提供的转发地址；经过同一个反向代理的多个用户可能共用计数。本机重置成功会清除现有限流计数。

程序日志仅对状态码为 400 及以上的 HTTP 请求或 WebSocket 握手记录 WARN 级别访问日志，正常页面加载、轮询、登录成功和连接建立不输出访问日志。以 WebUI HTTP 开头的记录包含请求方法、路由模板、状态码、直接连接地址、耗时及认证失败原因。不会记录密码、认证头、Cookie、会话内容、请求正文或查询参数。若请求被上游拦截、尚未到达 OlivOS，不会出现对应的核心请求日志。上游返回 HTML 错误页时，登录界面会显示 HTTP 状态码。

公网访问使用 HTTPS 或上述 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.auth_path ./conf/webui_auth.json 新密码认证记录路径，相对 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 加入该对象即可。注意，不要删除原有配置里面的 system 键。

"models": {
    "OlivOS_webUI": {
        "enable": true,
        "server": {
            "auto": false,
            "type": "http",
            "host": "127.0.0.1",
            "port": 20480,
            "token_path": "./conf/webui_token.txt",
            "auth_path": "./conf/webui_auth.json",
            "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 自动转换为网页。普通插件菜单仍能在“插件”页调用；带原生窗口的菜单不一定适合无桌面环境。

侧栏按插件组织页面：只有一个入口时，直接显示 webui_config.title，下面固定显示插件命名空间（namespace），点击即可打开页面；多个入口时，父项显示插件名称和命名空间，点击父项只展开或收起，再选择各自的功能页面或外部链接，右侧数字表示子入口数量。子入口显示各自的 webui_config.title，悬停可查看完整标题。收起只隐藏入口，不关闭页面。每个功能子页面仍可独立打开、切换和关闭。

命名空间始终显示，即使插件名称没有重复，也能直接确认入口来源。侧栏标题会在空间不足时省略，悬停会显示完整的插件名称或页面标题；这样不会因为名称长度不同而改变布局，也不需要依靠截取前几个字来区分插件。

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

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

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