OpenSquilla Web UI 本地控制台完全指南：从网关启动、聊天会话到审批与安全加固-平芜编程栈

人工智能
大模型
AI Agent
交互助手
工具调用
MCP 服务
Agent 记忆
RAG

【免费下载链接】opensquilla

OpenSquilla — Token-Efficient AI Agent with same budget, higher intelligence density

项目地址：https://gitcode.com/gh_mirrors/op/opensquilla

OpenSquilla Web UI（Control UI）是网关直接托管的 Vue 控制台，负责设置、聊天会话、审批、渠道、日志、Agent、用量与运行状态的可视化管理。本文以 docs/web-ui.md 为主线，结合网关配置、CLI 命令与opensquilla-webui源码实现，系统讲解如何启动 Web UI、从源码构建、使用聊天/目标/压缩/工件/审批等核心功能，以及公开暴露网关时的安全边界。读完本文，你将掌握 Web UI 的完整使用链路，并能对照源码理解每个功能背后由网关合约驱动的实现机制。

Web UI 是什么：本地控制台与 Vue 前端

OpenSquilla 的 Web UI 是运行在本地、面向浏览器的控制面，覆盖六大职责：配置（providers、router、search、channels、permissions）、聊天（含工具活动可视化）、审批（敏感工具调用的持久化决策点）、渠道与日志观测、Agent/调度（Cron）管理、用量统计。它通过网关暴露的 WebSocket 与 HTTP 合约通信，是浏览器端体验最佳的操作界面。

当前网关托管的 Control UI 是 Vue 产品 UI。历史上存在的control_ui.frontend = "legacy"设置仅被临时接受，以保证已有 profile 仍能启动；该取值已标记为废弃，会被归一化为"vue"，且不再激活旧的 vanilla-JS 客户端。这一逻辑在网关配置实现中可以看到：ControlUiConfig.frontend的类型被收紧为Literal["vue"]，其校验器会把legacy字符串映射回"vue"并发出DeprecationWarning与日志告警，提示移除该设置或改为"vue"：

# src/opensquilla/gateway/config.py _LEGACY_CONTROL_UI_FRONTEND_WARNING = ( "control_ui.frontend='legacy' is deprecated and no longer selects the " "retired vanilla-JS UI; Vue is always served. Remove this setting or set " "it to 'vue'." ) class ControlUiConfig(BaseSettings): model_config = SettingsConfigDict(env_prefix="OPENSQUILLA_CONTROL_UI_") enabled: bool = True base_path: str = "/control" frontend: Literal["vue"] = "vue" default_locale: Literal["en", "zh-Hans", "ja", "fr", "de", "es"] = "en" allowed_origins: list[str] = Field(default_factory=list)

值得注意的细节是ControlUiConfig还携带两个前端相关设置：base_path默认挂载在/control（尾斜杠会被剔除，根路径/不会被允许覆盖成""，以免前缀匹配命中所有请求）；default_locale决定浏览器无本地偏好时的首屏语言与网关固定渠道通知的默认语言，任意zh*会钳制为zh-Hans，其余前缀按ja/fr/de/es匹配，兜底为en。也就是说，Web UI 的多语言首选可以在网关配置层预先设定，而不是只能靠浏览器端切换。

快速启动 Web UI

前台网关

在终端前台运行网关：

opensquilla gateway run

然后打开控制台：

http://127.0.0.1:18791/control/

前台网关按Ctrl+C停止，停止时会优雅排空在途 Agent 回合与后台完成（详细生命周期见 docs/gateway.md）。

托管后台网关

让网关作为受管后台进程运行，以便 Web UI、渠道与定时任务在当前终端关闭后仍存活：

opensquilla gateway start --json opensquilla gateway status

--json输出机器可读的启动与就绪信息；gateway status用于查看运行状态。重启与停止分别使用opensquilla gateway restart与opensquilla gateway stop，二者同样走优雅停机：先排空在途回合，再进入强制 kill 截止线（默认 30 秒，可用OPENSQUILLA_GATEWAY_GRACEFUL_TIMEOUT调节）。

端口与监听地址

默认端口 18791 贯穿整套 CLI 工具链：例如 gateway_cmd.py 中--port选项的默认值、gateway_lifecycle.py 的port: int = 18791，以及 gateway_client.py 中回退的ws://localhost:18791/ws。需要换端口或绑定指定主机时：

opensquilla gateway run --port 18792 opensquilla gateway status --port 18792 opensquilla gateway run --listen 127.0.0.1 --port 18791

安全默认是只绑定回环地址127.0.0.1，因为本地网关掌握聊天、工具、会话、渠道、审批与配置的完整控制权。公开绑定属于主动选择，详见下文「安全加固」。

打包安装与源码构建

官方 Python wheel、Desktop 安装器与容器镜像均已内置构建好的 Vue 控制台，这些安装路径不需要用户机器上有 Node.js 或 npm，直接运行opensquilla gateway run即可访问/control/。

而 Git checkout 里只有 Web UI 源码、没有提交的构建产物。源码安装器（如 scripts/install_source.sh 中的build_webui()）会自动执行以下步骤并将结果随 OpenSquilla 一起打包：

cd opensquilla-webui npm ci npm run build

因此源码安装者与贡献者需要Node.js 22.12+ 与 npm（该版本要求写死在 opensquilla-webui/package.json 的engines.node中）。每次源码重装都会重新npm ci并重建控制台：首次运行下载依赖最多，热 npm 缓存能减少后续网络开销，但无法省去构建时间与磁盘写入。改动 Web UI 后，贡献者应重新构建。

构建采用「失败即关闭（fail-closed）」策略：标准 wheel 构建遇到缺失或过期的控制台会直接拒绝，而不是静默产出一个/control/空页面的 wheel。这一规则同样适用于直接pip install .、uv tool install .与 VCS URL 安装。本地 checkout 开发请先构建 Web UI；VCS URL 用户应先克隆仓库并运行源码安装器，或直接安装官方发布 wheel。

从 opensquilla-webui/package.json 可以看到构建链条比两条命令更严格：npm run build实际是typecheck（架构检查 + TypeScript 配置检查 + Vue 类型检查）+build:artifact（vite build后依次执行normalize-dist.mjs、check-theme-bundle.mjs、check-runtime-bundle.mjs、verify-dist.mjs --write、stage-dist.mjs），保证产物在主题、运行时包与目录结构层面都符合网关托管要求。

另外，控制台已不再包含背景音乐：现有浏览器偏好会被保留但忽略；旧public/music/目录中的个人文件会留在磁盘上，但被排除出构建、源码归档与容器构建上下文；所有 Web UI 产物都会拒绝残留音乐资产。聊天中的音频播放、录制与转写功能不受影响。

主功能区一览

区域	用途
Chat	运行与恢复聊天会话、查看工具活动、发布工件、使用手动压缩控制。
Conversations	从侧边栏切换活动会话，让长任务保持可见。
Overview / Health	查看就绪状态、Provider 状态、Memory 状态、沙箱姿态与恢复提示。
Settings	在模态流程中配置 Provider、路由器、搜索、渠道、权限及其他设置分区。
Channels	检查渠道适配器状态，并跳转引导式配置进行修改。
Skills	浏览可用技能及其就绪状态。
Sessions	检查持久化会话台账与运行状态。
Agents	管理持久化 Agent 条目。
Usage	查看 token 与预估成本汇总。
Cron	查看与管理定时任务。
Logs	检查运行时日志与诊断信息。
Approvals	响应敏感工具调用的审批请求。

前端入口 opensquilla-webui/src/main.ts 印证了这一模块划分：Vue 3 + Pinia + Vue Router + vue-i18n 之上，通过网关适配器（createGatewayAdapters）与私有 HTTP 传输（createPrivateHttpTransport）注册了approvalCenter、goalCenter、goalContinuity、planCenter、appSettings、providerConfiguration、setupWorkflow、sessionDirectory、turnCommands、pendingInputQueue等模块——每个主区域对应一组有测试保障的网关合约适配层（例如adapters/gateway/approvalCenterV4.ts的createApprovalCenterV4）。

聊天会话深度

会话能力清单

聊天 UI 支持以下能力：

流式（streaming）输出助手内容；
工具调用卡片；
回合活动与 RunTrace 视图，展示 Provider、Router、工具与用量事件；
敏感操作的内联审批请求；
工件卡片，有预览时附带缩略图；
交付物（deliverables）抽屉，用于追踪生成产物；
交接（share/export）操作；
会话切换侧边栏；
持久化/goal目标：结构化进度、用量、暂停/恢复、编辑、清除、护栏（guardrail）与 Plan 模式等待状态；
压缩或运行时工作进行中的待发消息队列行为；
手动/compact；
可用的每回合用量与节省元数据；
可复制的会话 ID；
移动端标签页，窄屏下仍可触达聊天、会话与运维视图。

使用会话选择器可在已有会话间切换；报告 bug 或请其他 OpenSquilla 表面检查同一会话时，复制会话 key 即可。

Slash 命令补全

Slash 命令的补全在运行之前完成：Tab总是完成当前候选；Enter完成部分匹配，且只有精确命令才会运行。未知命令会保留在 composer 中并附带恢复提示，避免误发送。

使用 /goal 开启多回合目标

执行/goal <objective>可启动多回合 Goal。其 ribbon 在工作或等待期间保持可见；变异结果、水合（hydration）与 Goal 事件流会在重连后持续同步。Goal 的生命周期、执行租约、护栏与 Plan 模式合约详见 docs/goal-mode.md。

手动压缩

长会话可以在聊天中直接压缩。若当前无需压缩，UI 会给出明确反馈：

Already within context budget; no compact was applied

若压缩正在进行，应等待其终态后再假设下一条消息已基于压缩后的上下文。压缩与缓存的底层机制（何时触发、缓存如何复用）参见 docs/features/compaction-and-cache.md；相关 Playwright 合约测试可在 opensquilla-webui/e2e/compaction-card.spec.ts 与 opensquilla-webui/e2e/compaction-live.spec.ts 中找到，覆盖压缩卡片状态与实时压缩交互。

工件（Artifacts）与 HTML 预览安全

当 Agent 发布文件时，Web UI 会显示工件卡片，适用于：生成的 HTML 原型、报告与简报、导出数据文件，以及 PDF、幻灯片、图片等生成输出。卡片可包含缩略图或预览元数据；交付物抽屉让已发布产物在原始回合滚出视野后仍然可发现。

HTML 工件预览始终标明当前使用的是完整网络访问还是离线模式：本地 Web UI 可请求任意模式；远程访问的 Web UI 会被强制离线，并在不透明沙箱中运行 bundle 脚本，同时明确提示 workers、持久化存储与根绝对路径不受保证。普通 web 链接继续在独立浏览器标签页中以noopener,noreferrer打开；Desktop 应用额外提供显式操作，把 HTTP(S) 链接放到其隔离的侧边浏览器中。

Desktop 的完整预览刻意做成浏览器形态而非特权 Electron 视图：每个打开项拥有独立的临时 cookie/存储/缓存分区，且没有 Node、preload、IPC、宿主机文件系统、OpenSquilla 身份或系统浏览器会话；关闭某项即清空其临时状态。设备权限、用户发起的下载、弹窗与外部协议仍由宿主中介处理；操作系统证书库中的客户端证书绝不会提供给预览页面。活动中的 OpenSquilla Gateway 在侧边预览内不可达，避免网络邻近性变成隐性的 OpenSquilla 身份——用户仍可在系统浏览器中显式打开链接。渠道投递限制与工件恢复详见 docs/artifacts-and-media.md。

审批（Approvals）

部分工具需要确认。审批区为操作员提供持久化的敏感操作决策点，而不是把决定埋在聊天文本里。以下场景应使用审批区：

Agent 想要写文件；
命令需要提权；
渠道或外部操作需要人工确认；
无人值守自动化在风险操作前应暂停。

审批中心的实现走网关合约：前端 approvalCenterV4.ts 通过 RPC 与事件订阅构建审批中心，配套合约测试（approvalCenterV4Contract.test.ts）与端到端测试 approval-card.spec.ts 保障了批准/拒绝在聊天卡片与审批中心之间的一致性。

日志与诊断

本地排障的推荐命令组合：

opensquilla diagnostics on opensquilla gateway status opensquilla doctor

在 Web UI 的日志与健康视图中，可将 Provider 就绪状态、渠道状态、会话状态与用户可见错误关联起来定位问题。若 Web UI 无法连接，请核对 URL 与网关绑定主机和端口是否一致；端口被占用时可改用--port 18792启动。

安全加固

Web UI 默认仅本地可访问。若确实需要把网关绑定到公共接口，必须先配置 token 认证与网络边界：

opensquilla gateway run --listen 0.0.0.0 --port 18791

切勿向公网暴露未认证的网关。更完整的防护要点见 docs/gateway.md：通配符监听被自定义 DNS 名或反向代理访问时，应在cors.allowed_origins中列出精确浏览器来源（如https://control.example）；IP 字面量与 localhost 权威无需该条目；"*"不会被接受，因为 OpenSquilla 有意不信任通配符监听器上的任意Host值，以阻止 DNS rebinding。浏览器扩展可通过chrome-extension://<id>自定义 scheme 来源访问回环网关（详见该文档的 CORS 配置示例）。

此外，网关停止采用优雅排空（默认 30 秒、可调），确保在途回合不会被截断——这既是稳定性设计，也是公开部署时的运维前提。