使用 Web GUI

Web GUI 就装在 daemon 里：启动 daemon，打开浏览器，就可以不碰终端地操作 Agent、 工作项、Skill 和文件。本页讲第一次使用和几个主要界面。

快速开始

# 启动 daemon（Web GUI 默认启用）
holon daemon start

然后在浏览器中打开 http://127.0.0.1:7878/。

Web GUI 由编译进 holon 二进制的内嵌资源提供。默认 CORS 配置允许 localhost 来源，因此在本机上开箱即用。

注意： 如果你配置了自定义监听地址或端口，请相应调整 URL。

身份认证与登录

在远程访问或启用了认证的环境下，浏览器访问控制台需要先在 /login 完成认证：

• 本地 Token 模式 (auth.mode = "local")：输入静态 Control Token，系统将自动换取 HttpOnly 的 holon_session Cookie。
• OIDC 单点登录模式 (auth.mode = "oidc")：点击 Continue with organization login，跳转至企业 IdP 完成认证。

有关 IdP 接入与会话超时策略的完整配置，请参阅配置 OIDC 身份认证。

页面

仪表盘

仪表盘提供运行时总览：

• Agent 名册 — 所有 Agent 及其状态（Awake、Asleep、Booting）、待处理消息数和当前模型。
• 运行时健康 — 调度器状态、唤醒提示和近期活动。
• 任务列表 — 点击任务打开详情面板，查看状态、命令、workdir 和输出。任务事件（创建、状态更新、完成）会实时刷新列表。
• 快捷操作 — 创建 Agent、挂载 workspace、查看 Agent 详情。
• Agent 生命周期 — 直接在仪表盘上启动、停止和删除 Agent。删除会永久移除该 Agent 及其数据，可选择一并移除它的私有子 Agent。

Agent 会话

从仪表盘选择 Agent 即可打开它的会话页面：

• 消息流 — 以线索式会话展示近期消息、工具调用和简报。
• 显示级别 — 在 Info（紧凑的面向用户输出）、Verbose（工具调用和中间结果）与 Debug（完整运行时元数据，含工具执行记录）之间切换。
• 输入栏 — 向选中的 Agent 发送 operator 消息。
• 事件时间线 — 侧栏展示近期事件的时间线，包括轮次、工具执行和状态转换。
• 虚拟滚动 — 消息列表采用虚拟化渲染，长对话下依然流畅，且不带来 DOM 开销。
• 工具执行详情 — 在消息流中展开单次工具调用，查看请求/响应载荷、耗时和元数据。工具结果面板同时展示结构化输出和原始数据，便于调试 Agent 行为。
• 实时 SSE 流式传输 — 直连 /api/agents/:id/events/stream，实现思考过程（reasoning tokens）、活跃工具执行状态指示器与即时简报（briefs）的流式刷新。
• 调度等待与交付状态指示 — 当 Agent 执行 WaitFor（等待后台命令任务、外部回调或用户输入）时，界面显式呈现等待原因与交付模式（final 或 silent）。

搜索

在浏览器中搜索 Agent 记忆。

结果包含：

• 摘录 — 每条结果展示高亮匹配词的上下文片段，无需打开完整记录即可判断相关性。
• 可展开的来源 — 点击结果就地展开完整内容，无需离开搜索页。
• 按 Agent 过滤 — 把结果限定在一个或多个 Agent ID 上。
• 全文搜索 — 跨 Agent 查询运行时记忆索引。

Agent 模板

可以直接在 Web GUI 中浏览、安装模板并据此创建 Agent。页面位于 /templates：

• 模板目录 — 浏览已安装模板的显示名、描述和来源信息（本地、远程 URL 或已同步来源）。
• 创建 Agent — 点击模板打开已预填模板选择器的“创建 Agent”对话框。Agent 会按模板的角色契约和预装 skills 初始化。
• 远程来源 — 查看和管理已配置的远程模板来源（GitHub 仓库）。daemon 启动时会从这些来源同步模板。
• 模板详情 — 点击模板查看完整元数据，包括模板 manifest、预装 skills 和来源。

命令行管理模板见 Agent 模板指南。

Skill 管理

在浏览器中管理 Skill Library 和 Agent skills：

• 库目录 — 浏览本地 Skill Library 中注册的全部 skills，含名称、描述和来源信息。
• 添加 skill — 从本地路径、远程 URL 或 GitHub uses 简写导入 skill。
• 移除 skill — 从库中移除 skill。
• 启用/停用 — 用开关按 Agent 启用或停用单个 skill，并可查看每个 Agent 当前生效的 skills。
• Skill 详情 — 点击 skill 查看完整元数据，包括 scope、source root 和发现路径。

Skill 管理页面位于 Web GUI 的 /skills。daemon 运行内嵌 GUI 时，也可以从导航侧栏进入。

通过 Web GUI 安装 skill 是非阻塞的：在浏览器中添加 skill 后，安装会作为后台任务运行（见 Job API）。进度指示器显示当前状态，任务状态存在 localStorage 中，刷新页面也能继续跟踪。

Skills 页面还支持更新已安装的 skill。远程来源中发布了新版本的 skill 会显示更新按钮，点击后会创建一个拉取最新版本的目录更新任务。任务完成后就地显示成功或错误反馈，更新任务同样以后台任务运行（见 Job API）。Skill 目录更新也作为任务运行。

命令行管理 skill 见 Skills 指南。

Workspace 文件浏览器

从右侧面板的 文件 标签进入，或点击会话中的文件引用。选中文件后直接显示正文；Markdown 支持“预览 / 源码”切换，文本文件支持语法高亮。

• 浏览目录：切回所在目录，保留选中文件和阅读位置；展开面板后可以并排查看目录与正文。
• 位置栏：切换工作区、浏览上层目录。长路径折叠中间目录；点击“文件信息”查看完整路径、执行根、类型、大小和修改时间。
• 文件操作：复制路径、Markdown 引用、网页链接，以及下载和刷新，都在 ⋯ 菜单中。新窗口按钮可以打开独立阅读页面。
• 返回来源：面板顶部的返回按钮沿文件浏览历史返回原来的详情；右上角关闭按钮关闭整个面板。

文件定位保留工作区和执行根身份。路径穿越与符号链接越界会被拦截；文本预览上限为 1 MB，下载可获取完整文件。

可选的 Finder 集成（macOS）

当 Holon 直接运行在浏览器所在的 Mac 上时，可以在启动时明确开启：

holon daemon start --access local --desktop-integration
# 对已经运行的本机实例，有意重启后启用：
holon daemon restart --access local --desktop-integration

Holon macOS 菜单应用启动或重启它管理的 daemon 时，会自动添加 --desktop-integration。文件操作菜单会出现 在 Finder 中显示，用于定位文件，不会打开或执行文件内容。其他平台仍支持预览、复制和下载。

直接使用 CLI 启动时，此选项默认关闭，需要手动指定；菜单应用每次启动或重启都会开启。CLI 重启会继承设置，也可以用 --desktop-integration=false 覆盖。运行时只允许回环地址监听。不要对端口转发、反向代理或容器实例启用：localhost 并不能证明文件属于当前电脑。因此界面显示“本机地址”，不据此断言“本机运行”。

设置

在浏览器中配置 Holon：

• 模型设置 — 查看和修改默认模型、覆盖单个 Agent 的模型，并设置推理强度。备用模型列表使用 chip 组件，支持拖动排序，便于调整优先级。
• API key — 通过凭据存储添加或更新提供商凭据（API key），无需手动改 JSON 文件。设置页会为每个提供商自动判断合适的凭据方式：api_key 提供商走 API key 输入，Codex 这类 OAuth 提供商走设备登录链接。
• Ollama 发现 — 本机运行的 Ollama 服务会被自动发现，无需 API key；其模型会出现在模型选择器中。
• 语言 — 切换 Web GUI 显示语言，支持英文（EN）和简体中文（ZH-CN）。所有界面文案（导航、按钮、标签、状态消息）都会实时更新，无需重载页面。
• 图像生成 — 直接在设置页配置默认图像生成模型（image_generation.default）。模型选择器只显示支持图像生成能力的模型。
• 控制面访问与 Bearer Token — 在远程访问或开启鉴权的环境中，支持在界面中直接配置并安全存储 Bearer 访问令牌。
• 运行时配置 — 查看当前执行环境、已挂载的 workspaces 和策略快照。
• Decision 决策设置 — 直接在浏览器中配置决策路由与提供者。支持在远程端点（如 TypeSafe Jev 或 OpenAI 兼容模型）与零外发本地 ONNX 预设之间切换，查看决策遥测数据，并开启或关闭咨询工具访问。

国际化（i18n）

Web GUI 使用 react-i18next 做完整国际化。设置页的语言选择器可在英文和简体中文之间切换。所有界面文案（导航项、按钮标签、表单提示、状态消息和错误页）都会在选中后立即切换。翻译资源与 UI 资源一起编译进内嵌构建，无需外部文件或网络访问。

设置页还包含 search provider 区块，可在浏览器中配置网页搜索和原生搜索提供商。

UI 图标

Web GUI 的状态指示、导航图标和文件浏览器图标现在统一使用 lucide 图标（通过 lucide-react），取代了之前的 Unicode 符号方案。工具提示经过精简以更清晰，面板标题统一使用 label(N) 格式。

检查器（右侧面板）

查看 Agent 或仪表盘时，右侧面板显示：

• Agent 身份 — Agent ID、可见性、归属和 profile preset。
• 当前工作 — 进行中的工作项、计划状态和 todo 清单。
• Token 用量 — 累计及每轮 token 消耗。
• 活跃子 Agent — 派生的子 Agent 及其状态。
• 工具延迟 — 每个工具的调用次数和总耗时。

右侧面板也承载上下文详情视图。例如，在仪表盘中点击任务会在主视图旁打开任务详情面板，显示状态、类型、命令、workdir 和输出。

右侧面板支持展开为全屏模式；模型菜单通过固定定位 portal 渲染，不会被布局溢出裁剪。

远程访问

Web GUI 兼容 Holon 的远程访问模式。daemon 配置为远程访问（tunnel、tailnet 或 LAN）后，通过同一端点打开 GUI URL：

# 示例：从同一网络中的另一台机器经 LAN 访问
http://<daemon-host>:7878/

从不同来源访问时需要配置 CORS。详见远程访问和配置。

内嵌构建与开发构建

内嵌构建在发布时通过 rust-embed 编译进 holon 二进制。生产使用无需单独执行 npm 安装或构建。

做 UI 开发时启动开发服务器：

cd web-gui/app
npm install
npm run dev

开发服务器支持热重载，没有 Holon 服务端在运行时使用 fixture 数据。可设置 HOLON_API_PROXY_TARGET 把开发服务器的 /api 代理指向运行中的 Holon daemon（默认 http://127.0.0.1:7878）。

性能诊断

Web GUI 通过 /api/control/runtime/performance 暴露运行时性能指标。该端点返回按阶段分组的细粒度计时数据：

每个指标包含 count、total_ms、max_ms 和 avg_ms。可用来诊断慢轮次、找出耗时的工具，或长期跟踪 provider 延迟。

Job 监控

skill 安装这类长时间操作会作为可跟踪的任务运行，而不是阻塞请求：

• 就地进度 — Skills 页面为运行中的任务显示进度指示器，完成时给出成功或错误反馈。
• Job API — 运行时通过 /api/jobs/{job_id} 暴露任务读模型，包含状态、阶段和进度项。

另请参阅

• 运行你的第一个 Holon 任务 — 用几条命令试用 Holon
• 连接远程 Holon 运行时 — 从另一台机器使用 GUI
• 排查 Holon 任务问题 — 诊断常见问题
• 配置参考 — CORS、端口和控制平面设置
• 配置 OIDC 身份认证 — 设置团队 SSO 与会话策略