Skip to content

webui-guide.md

Latest commit

 

History

History
252 lines (167 loc) · 21.8 KB

webui-guide.md

File metadata and controls

252 lines (167 loc) · 21.8 KB
Raw

WebUI 使用指南

WebUI 是 Undefined 的主要管理入口，提供配置编辑、日志查看、认知记忆管理、表情包库、AI 对话和系统监控等一站式功能。即使 config.toml 尚未创建，也可以通过 WebUI 补全配置并启动 Bot。

快速开始

启动

uv run Undefined-webui

默认监听 http://127.0.0.1:8787。相关配置位于 config.toml 的 [webui] 节：

[webui]
url = "127.0.0.1"      # 监听地址
port = 8787             # 端口
password = "changeme"   # 密码（必须在首次登录时修改）
autostart_bot = false   # 启动 WebUI 时是否自动启动 Bot（默认 false）
check_updates = true    # 打开 WebUI 时后台检查正式 Release（默认 true）

如需远程访问，将 url 改为 0.0.0.0 或实际 IP。

首次登录

  1. 浏览器打开 http://127.0.0.1:8787
  2. 输入初始密码 changeme
  3. 系统强制要求修改默认密码后才能进入管理界面

修改后的密码会写入 config.toml。桌面端 / Android 客户端也使用同一密码连接。

功能概览

WebUI 的主要页签如下。

概览（Overview）

仪表盘页面，展示系统运行状态：

指标 说明
Bot 状态 运行中 / 已停止
系统运行时间 自启动以来的持续时间
CPU 使用率 实时百分比
内存占用 已用 / 总量 / 百分比
运行环境 CPU 型号、操作系统、Python 版本
资源趋势图 CPU / 内存随时间的变化曲线

页面会自动刷新，也可手动触发。

配置管理（Config）

提供两种编辑方式：

  • 表单模式：按固定纵向顺序展示配置分组，组内字段会根据可用宽度自动排布；浏览长分组时标题和折叠入口会保持可见，展开或折叠不会打乱其他分组的位置。
  • TOML 原始编辑器：直接编辑 config.toml 文本，带语法高亮，适合批量变更。

其他能力：

  • 验证：保存前自动进行 TOML 语法检查和严格配置校验，错误项会标红提示。
  • 搜索与折叠：搜索会临时展开匹配分组并保留原折叠状态，清除搜索后自动恢复；也可使用“全部展开 / 全部折叠”快速整理页面。
  • 配置历史：每次保存自动生成带时间戳的备份（最多 50 版本），可随时回滚到任意历史版本。
  • 模板同步：一键将 config.toml.example 中新增的配置项合并到当前配置，不覆盖已有值。

配置支持热更新——大多数配置项修改后即时生效，无需重启 Bot。需要重启的项（如 onebot_ws_url、webui_port）会在保存时提示。

日志查看（Logs）

  • 支持 Bot 日志 和 WebUI 日志 切换。
  • 实时流式推送（SSE）：日志实时滚动到最新。
  • 可暂停 / 恢复流式推送，WebUI 默认显示最近 5000 行；接口支持 lines 参数，范围 1–10000（未传时默认 1000）。
  • 搜索、日志等级和时间范围均按完整日志记录过滤；关键词命中多行 JSON、参数或异常堆栈中的任意续行时，会保留并显示该记录的全部内容。
  • 左侧文件列表展示所有日志文件（含归档），可选择查看历史日志。
  • 支持下载日志文件。

探针与诊断（Probes）

三类探针帮助排查问题：

  • 内部探针：版本号、Python 版本、平台、运行时间、OneBot 连接状态及 WebSocket 地址；同时展示请求队列、消息合并器（含投机预发送状态、当前缓冲桶 phase 与 inflight 标记）、长期记忆 / 认知服务、技能统计（可调用工具、工具集、Agent、自动管线、斜杠命令、Anthropic Skills）等运行态指标。
  • 外部探针：Runtime API 的可用端点和能力列表。
  • 引导探针：检查 config.toml 是否存在、TOML 语法是否合法、配置值是否有效，并给出修复建议。

认知记忆（Memory）

分为三个子面板，对应 认知记忆系统 的不同层次：

认知事件搜索

输入关键词进行语义搜索，查看 AI 提取并存储的用户 / 群聊事实记录。支持调整返回条数和排序方式。

认知侧写查看

  • 按关键词搜索侧写。
  • 按 QQ 号或群号精确查看对应的完整侧写内容。

长期记忆管理

AI 的置顶备忘录（自我约束、待办事项等），支持完整 CRUD：

  • 新建记忆条目
  • 编辑现有内容
  • 删除条目
  • 关键词搜索

表情包库（Memes）

管理 全局表情包库 的 Web 界面：

  • 浏览与搜索：分页列表展示，支持关键词搜索和语义搜索（以及混合模式）。输入时自动防抖搜索，Enter 立即触发。
  • 筛选与排序：按启用 / 禁用、静态 / 动态、置顶等条件筛选，按创建或更新时间排序。
  • 详情与操作：查看元数据（UID、描述、标签）和预览图；支持编辑描述 / 标签、启用 / 禁用、置顶 / 取消、删除。
  • 重分析 / 重索引：对单张表情包重新触发 AI 描述生成或搜索索引更新。
  • 统计概览：总数、启用 / 禁用数、静态 / 动态数等。

自动化（Automations）

在这里查看、创建和编辑自动化工作流，触发条件与节点类型的完整说明见 自动化：

  • 任务列表：按 ID、名称、触发类型、场景和上次运行状态搜索；卡片显示启停、上次结果和下次执行时间。列表与画布同页上下各占一屏，滚动切换，点选卡片会滚到画布而不是替换列表。
  • 预设起稿：新建时从空白图或内置预设（每日主 AI、@ + 关键词、入群欢迎、热点 DAG）进入编辑器。
  • 全屏画布：左侧节点盘，中间点选出点再点目标连线，右侧结构化检查器。空白 LLM 的工具 / 工具集 / Agent 用搜索点选。工具参数值按 JSON 编辑并保留数字、布尔值、数组、对象与字符串类型。工具与 LLM 节点可勾选「存储为变量」并填写名称，下游用 {{名称}} 引用输出。三种 LLM 节点还可配置变量提取（名称 + 说明），运行时注入 extract_<名称> 工具。分支带 case 锚点；检查器修改 case 的 ID / 文本时会保留高级 JSON 中的 mentions、text_match、sender_ids 与 clock 条件。循环以分组框表示；JSON 仅作为高级排障。
  • Start 检查器：场景多选（群 / QQ 私聊 / 微信）、群号与 QQ、@ 条款、剩余文本、pass_text、clock / 星期、冷却与时间类字段。新建默认关闭「拦截主 AI」和「自动发送终值」；关闭拦截时工作流后台执行，主 AI 立刻继续。
  • 深链接：/?tab=schedules&task=<id> 直接打开一条自动化。

WebUI 会先验证登录态，再通过后端代理访问 Runtime API 的 /api/v1/automations。浏览器前端不会直接读取或暴露 [api].auth_key。

微信接入（WeChat）

管理微信 ClawBot/iLink 私聊通道：

可从首页的“微信接入”快捷入口直接打开，也可进入控制台后从侧栏切换到该页面。

  • 扫码绑定：填写本地帐号别名与逻辑 QQ 号；页面会在二维码生成期间显示加载状态，并支持刷新二维码、查询扫码状态和提交验证码。
  • 帐号生命周期：查看在线/离线/异常状态，启停、改绑或解绑帐号。
  • 权限确认：绑定管理员或超级管理员逻辑 QQ 时，页面要求第二次明确确认。
  • 隔离来源：只显示未匹配来源的元数据与计数；消息正文不会进入 WebUI、历史或 AI。
  • 审计记录：查看登录、绑定、启停、改绑、解绑和高权限确认操作。

该页面要求 Bot 主进程正在运行且 [weixin].enabled = true。二维码和帐号管理请求由已鉴权的 Management 后端代理到 Runtime API，浏览器不会读取 Runtime API Key 或 iLink 凭据。完整安全边界与实机验证步骤见 微信 iLink 接入。

AI 对话（Chat）

WebUI 内置的对话界面，直接与 Bot 的 AI 进行交互：

  • WebUI WebChat 与 Undefined Chat 共用 Runtime 的会话、历史、任务、事件和附件合同。区别在于 WebUI 通过 Management 后端代理 Runtime，并以 JSON polling 续接为主；Undefined Chat 是独立 Tauri 客户端，SSE 优先并在断线或 Android 生命周期恢复时使用 JSON fallback。
  • 右侧会话抽屉支持多对话管理：新建对话、切换对话、重命名对话和删除对话。桌面端默认折叠，鼠标移到右侧触发区会自动展开；移动端默认只显示“对话”按钮，点击后展开会话列表，切换会话后自动收起。新建成功后会显示提示，并短暂高亮新会话。多对话只作用于 WebChat，不影响 QQ 私聊 / 群聊历史。每个会话在后端保存为 data/webchat/conversations/<conversation_id>.json，删除对话会删除对应 JSON 文件；如果仍有 WebChat job 运行或正在收尾落盘，删除和清空会被拒绝。
  • WebChat 的 AI 视角始终是同一个虚拟私聊用户 system#42，权限仍为 superadmin。切换 WebUI 会话只切换后端提供给 AI 的当前 WebChat 历史，不改变 user_id、sender_id 或身份提示，因此 AI 不会把多个 WebUI 会话看成不同真实用户。
  • 输入框开头输入 / 时会从后端 /api/v1/commands?scope=webui 获取当前可用斜杠命令并在输入框上方展开补全面板。面板按命令名、别名、说明和用法即时筛选，支持点击选择，也支持方向键选择、Enter / Tab 填入；直接手打 /faq、/changelog 或 alias /cl 这类复合命令后（命令末尾需带空格），会切换为子命令补全并显示具体用法。命令数据尚未返回时面板显示”正在加载可用命令”，不会提前显示”未找到匹配命令”；输入 /h 这类已命中 alias 但命令本身没有声明子命令的内容时（末尾带空格），会显示命令帮助块，包含说明、用法、示例和别名，例如 /h [命令名] [-t]，便于继续补参数；只有命令或子命令确实没有匹配项时才显示无匹配提示。命令清单按 WebChat 的虚拟私聊执行身份过滤，因此不会提示当前 WebUI 会话实际不可用的命令。
  • 旧版 WebChat 历史会在首次打开时自动迁移到默认会话。迁移完成后会写入标记文件，之后不会重复迁移；即使删除该默认会话，也不会再从旧历史文件恢复。未选择会话的旧接口调用会按需创建一个空的默认会话以保持向后兼容。
  • 会话标题先使用第一条用户消息的前若干字符作为临时标题；当会话已有首问和首答后，后端会使用 chat model 根据首问 + 首答生成正式标题。手动重命名的标题不会被自动生成覆盖；临时或生成失败的标题会在后续能处理时继续尝试。
  • 支持文本、图片和文件消息。图片或文件可通过 + 选择，也可直接粘贴到输入框；粘贴只会加入待发送附件条，不会立即发送，点击发送或按 Enter 时才随同当前文本进入同一条 WebChat 消息。无待发送附件时输入框会占满可用宽度；添加附件后右侧预览轨道随数量平滑展开，图片显示缩略图，附件较多时输入框保持最小可用宽度并压缩预览卡片，避免输入区跳动。移动端会把引用和附件预览轨道放到输入框上方，保证正文输入和发送按钮不被挤压。
  • AI 回复支持 Markdown 渲染，Markdown 内的常见 HTML 片段会经过 WebUI 白名单净化后自动渲染；完整 HTML 文档或独立块级 HTML 片段会先净化再直渲染，避免被 Markdown 缩进规则误判成代码块。脚本、事件属性、危险协议、危险样式以及 head / style 等文档元信息会被剥离。聊天中的图片可点击放大查看，支持点击遮罩、关闭按钮或按 Esc 退出。代码块使用本地随包的 highlight.js 做多语言语法高亮，不依赖外部 CDN；显式语言优先，未知语言会自动检测，库不可用时回退为安全转义文本。较长代码块默认以固定高度折叠，代码区内部可滚动，可用常驻工具栏展开 / 折叠，复制和运行按钮始终可见。可运行的 HTML 代码块会额外显示“运行”，在前端沙箱 iframe 中本地预览完整 HTML/CSS/JS，不调用后端执行；预览环境允许 inline script 以支持完整 HTML 交互，但不允许 unsafe-eval，安全边界依赖 WebUI CSP 和 iframe sandbox。预览小窗可拖动位置并调整大小，窗口尺寸变化时会自动保持在可见区域。HTML 预览面板可关闭，也可进入选择模式：第一次点击 iframe 内元素只预览并锁定引用范围，第二次点击确认后才把对应 HTML 片段加入待引用区。
  • WebUI 场景下，代码优先直接作为聊天回复输出，不要默认转成文件附件；只有用户明确要求文件交付、代码过长不适合聊天展示，或确需附件工作流时才使用文件。所有代码块都应显式标注语言，例如 ```python、```javascript、```html、```bash，不确定语言时用 ```text。
  • AI 消息支持引用：可引用整条 AI 消息、选中的某段文字，或 HTML 预览中点选的元素。引用会显示在输入框右侧的待发送引用条中，可在发送前移除；实际发送时不会新增接口或附件，而是自动在用户消息前拼接为 Markdown > 引用块，例如 > 引用 AI:，随后和文本、图片、文件一起进入同一条 WebChat job 消息。发送后的引用块会像代码块一样折叠显示，展开后内部固定高度并可滚动。发送失败时待引用内容会保留，发送成功后清空。
  • 默认加载最新 50 条消息并滚动到底部；向上滚动到顶部会按后端返回的 next_before 游标懒加载更早历史，并保持原视口偏移，避免一次性恢复大量工具块造成卡顿。“自动滚动到底部”开关默认开启并保存在浏览器本地，关闭后 AI 回复、工具 / Agent 状态和 AI 阶段刷新不会打断当前位置；首次加载和主动发送新消息仍会定位到底部。系统开启减少动态效果时，聊天滚动会改为即时跳转。
  • 对话由 WebChat job 执行。刷新页面、关闭页面、网络短暂中断或换另一个客户端重新访问 WebUI 时，后端任务继续运行，前端会从后端查询会话列表、当前运行 job，并用 conversation_id + job_id + seq 每 0.5 秒轮询增量事件、当前阶段快照和运行中工具 / Agent 快照自动续接；前端不会把关键任务状态只存放在浏览器本地，历史、会话、运行中 job 和事件游标都以 Runtime API 返回值为准。如果刷新后首次查询运行中 job 失败，WebUI 会退避重试并在网络恢复时再次尝试；如果后端已完成 job 并落盘，前端会刷新历史并解除发送锁。SSE 仅作为兼容方式保留，WebUI 不依赖长连接。
  • 运行中的 WebChat job 可从正在生成的 AI 气泡中取消。取消会调用 Runtime 的 job cancel 接口并解除当前会话的发送锁；如果取消发生在 AI 尚未产生任何回复内容前，前端会移除空 AI 气泡，并在最后一条用户消息上显示“重试”。点击重试会带 reuse_previous_user_message=true 用同一条纯文本重新发起 WebChat job，前端不再追加一条相同用户气泡，后端也会校验并复用最后一条可见用户历史，避免把同一条输入重复写入会话。
  • 运行中的 AI 气泡会在 AI 标签后实时显示当前阶段和后端计算的总已用时，例如构建上下文、查长期记忆、查认知记忆、等待模型、等待工具、发送消息；任务完成后该位置显示本轮回复总用时。工具 / Agent 摘要行会在名称旁显示调用耗时，运行中先显示后端快照时间，轮询间隙用本地时间临时递增，下一次查询后自动校准；结束后固定显示后端结束事件的总耗时。轮询刷新只更新已有状态和计时节点，结构未变化时不会重建工具 / Agent 块，避免运行中闪烁。状态条区分运行中、成功和失败；整轮回复总耗时会写入 WebChat 历史 metadata。
  • WebChat job 事件会更新同一个 AI 气泡；AI 正文和主对话工具 / Agent 调用按事件时序显示，例如工具调用、正文回复、结束工具会依次出现在同一气泡内。
  • 工具 / Agent 调用块展开后会分区展示由后端脱敏截断后的输入和输出预览；Agent 内部工具、子 Agent 和发送出的正文会按后端提供的 timeline 嵌套显示，并保留各自状态、输出和耗时。Agent 内部阶段只作为对应 Agent 摘要行的当前状态展示，不单独占用一行。并发工具结束事件按实际完成时间发布，结构化预览会渲染为带颜色的键值字段。输出内容继续支持 Markdown、安全 HTML、图片和文件卡片渲染，并保留适合移动端的单行工具摘要。
  • WebChat 内由 send_message / send_private_message 发送给当前虚拟私聊的正文会作为 AI 消息展示，工具块只显示紧凑发送状态，避免重复展示参数和“已发送”结果；end 成功结束时同样只显示紧凑状态。
  • WebChat 的工具 / Agent 展示块、嵌套调用树、权威展示 timeline 和正文事件会随 Bot 回复一起写入虚拟私聊历史，用于刷新页面后恢复同一个聊天块的时序；若任务失败或取消，后端会在落盘时补齐未闭合工具的错误 / 取消状态。这部分展示元数据不会注入给 AI 作为后续上下文。
  • 清空历史接口保留为兼容能力，只删除当前 WebChat 会话的虚拟私聊 system#42 聊天历史，不影响其他 WebChat 会话、长期记忆、认知记忆或 profile。WebUI 主界面不提供清空按钮，推荐通过新建对话开始新的上下文；若仍有运行中或正在收尾落盘的 WebChat job，清空会被拒绝。
  • 发出的消息会经过与 QQ 侧相同的处理流程（安全检查、工具调用等）。

关于（About）

显示当前版本号、版本更新记录和 MIT 许可证文本。版本更新默认展示当前运行版本，可通过下拉框切换查看其他 CHANGELOG.md 版本条目。

Bot 控制

WebUI 首页（Landing Page）提供 Bot 的启停控制：

  • 启动 Bot：点击启动按钮，Bot 进程在后台运行。
  • 停止 Bot：安全停止当前 Bot 进程。
  • 状态指示：实时显示 Bot 运行状态。

概览页提供手动 Release 更新检查；默认也会在鉴权成功后执行一次静默后台检查。

Release 更新检查

  • 更新来源为 69gg/Undefined 的最新正式 GitHub Release。检查通过异步 HTTP 完成，不阻塞页面或 WebUI 事件循环。
  • 每次打开并登录 WebUI 都会请求本机检查接口；后端对 GitHub 结果缓存 15 分钟，并让成功或失败的并发检查共享同一个在途任务，以避免重复重试和触发未认证 API 限流。
  • 检测到新版本后会显示当前版本、目标版本、Release 链接，以及“稍后”和“拉取并重启”操作。对话框位于全局页面层级，在 Landing 与 App 视图均可见；关闭提示只对当前页面有效，下次打开仍会检查。
  • [webui].check_updates = false 只关闭页面打开时的自动检查，概览页“检查更新”仍可手动使用。配置支持热更新。
  • 自动更新要求源码部署处于官方 origin、本地 main 分支且工作区干净。不满足条件时仍展示新版本和 Release 链接，但不会允许自动拉取。
  • 确认更新后，WebUI 会获取官方 main 与目标 Release 标签，验证标签属于官方 main，再仅快进到该标签；随后同步子模块，并在依赖清单变化时执行 uv sync。更新请求总等待上限为 30 分钟，失败或超时会尝试恢复原 Bot；成功后使用仓库根目录下的恢复标记重启 WebUI 并恢复原 Bot 运行状态。Release 外链仅在 HTTPS 地址有效时显示。
  • 直接运行 uv run Undefined 不再自动检查、拉取或重启；更新交互只由 WebUI 发起。

自动启动 Bot

若希望 WebUI 启动后自动拉起 bot 进程，可在 config.toml 中配置：

[webui]
autostart_bot = true

启用后，uv run Undefined-webui 会自动启动机器人，无需手动点击"启动 Bot"按钮。默认为 false。

注意：

  • 该配置仅在 WebUI 启动时生效，运行时修改需重启 WebUI 才能应用。
  • 与 WebUI 更新重启后的自动恢复机制（pending_bot_autostart marker）互不冲突，自动恢复优先级更高。

键盘快捷键

快捷键 功能
Cmd/Ctrl + K 打开命令面板，可快速跳转到任意页签或执行操作

远程访问

WebUI 和桌面端 / Android 客户端共享同一 Management API：

  1. 将 [webui].url 设为 0.0.0.0（或你的 LAN/公网 IP）。
  2. 确保防火墙放行 [webui].port（默认 8787）。
  3. 桌面端 / Android 客户端输入 http://<IP>:8787 和密码即可连接。

如果启用了 Runtime API（[api].enabled = true），WebUI 会自动代理 Runtime API 的功能（探针、记忆查询、自动化、AI Chat 等），无需单独暴露 Runtime API 端口。

常见问题

Q: 忘记密码怎么办？

直接编辑 config.toml 中的 [webui].password 字段，重启 WebUI 即可。

Q: 配置保存后 Bot 没反应？

大多数配置项支持热更新。但少数关键配置（如 WebSocket 地址、WebUI 端口、API 端口）需要重启才能生效，保存时会有提示。

Q: 日志不滚动了？

检查是否意外暂停了日志流。点击日志页面的播放按钮恢复实时推送。

Q: 探针显示 Runtime API 不可达？

确认 [api].enabled = true 且 Bot 正在运行。Runtime API 由 Bot 主进程提供，Bot 未启动时自然不可达。