Work：隔离工作区
Work 是 Libre WebUI 原生编程代理界面。每个任务结合持久对话、明确的模型提供商路由
和 /workspace 中的专用文件系统。所选模型可以检查和编辑文件，在任务专属 Docker
容器或 Kubernetes Pod 中运行命令，并启动浏览器预览。
Work 直接实现在 Libre WebUI 中，不需要 Libre Claw 或其他代理 daemon。
所有 Work API 都要求已认证且有 Work 权限的账户。默认仅管理员可用；管理员可在 设置中的用户管理选项卡向所有活跃用户开放（主机文件夹工作区始终仅管理员，因为会绑定服务器路径）。 Work 明确允许模型在沙箱内执行任意 shell 命令。除非所选命名运行时政策禁用，任务 具有网络出站。请把所有获准人员视为可信运行时运维人员，而不只是聊天用户。
版本亮点
本版本把 Work 作为完整任务工作流：
- 主侧边栏中独立的 Work 和 Chat 操作，清楚显示当前模式。
- Work 任务位于普通侧边栏而非第二任务轨；运行更新时位置保持稳定，可直接删除。
- 每任务独立沙箱身份和持久 Docker 卷或 Kubernetes PVC；可停止或重建而不删文件。
- 对话、运行状态、工具活动、模型选择和任务所有权持久保存在数据库中。
- 认证实时流涵盖助手文本、提供商公开推理、工具调用/结果、用量、技能和状态变化。
- 服务器拥有的 worker 技能教模型高效检查、编辑、验证和预览，不向项目写控制文件。
- 支持工具的本地 Ollama、Ollama Cloud 和已配置聊天/补全插件。
- 响应式对话/工作区分栏；桌面支持拖动和键盘，小屏可切换界面。
- 集成文件、活动、Git、终端、预览和屏幕；屏幕即可观察和教学的 Work Computer。
- 明暗语法高亮、浏览器端格式化、保存冲突检测和临时草稿。
- 选择远程提供商时按用户显示可关闭披露。
- 25 种语言的完整翻译，包括原生阿拉伯 RTL，而代码、路径、模型 ID 和命令输出保持 LTR。
持久单元是任务工作区，不是持续运行的容器。Libre WebUI 按需启动、停止或重建容器， 同时保留命名卷。
架构
Libre WebUI（而非模型或浏览器）选择沙箱和工作区名称、镜像、挂载、用户、限制、 网络模式和预览端口。模型只获得：
list_filesread_filewrite_filedelete_filemove_filesearch_filesrun_commandstart_previewstop_preview
delete_file 和 move_file 与其他文件工具一样受路径保护：拒绝离开工作区、绝不
穿越符号链接、删除目录前要求明确递归标志、移动不覆盖目标。它们通过文件辅助程序
而非 shell 运行，因此预览运行且 run_command 被阻止时仍可工作。
模型请求由 Libre WebUI 后端发出，不来自 Work 容器，也不依赖容器网络政策。
要求
Work 需要配置沙箱后端：
- 默认后端要求安装 Docker、daemon 可达，并允许后端调用
docker（或WORK_DOCKER_COMMAND配置的可执行文件）。 - Kubernetes 后端要求 API 凭据，以及 Helm 在
work.enabled=true时创建的 Role、RoleBinding、沙箱命名空间和 NetworkPolicies。
所有后端还需要：
- 支持工具的模型，可来自健康 Ollama（包括 Ollama Cloud），或活动聊天/补全插件， 且当前管理员已配置准确模型和凭据。
- 足够的运行时存储，用于镜像、生成项目和项目本地依赖。
- 有 Work 权限的已认证账户；默认仅管理员，可开放给所有活跃用户。
Libre WebUI 创建运行前检查 Ollama 宣告能力，拒绝未宣告 tools 的模型。插件模型
必须支持其提供商工具调用协议。远程模型拒绝工具时运行失败，不会静默切换。
本地启动
最简单的受支持设置是在浏览器所在电脑运行 Libre WebUI 和 Docker：
docker info
npx libre-webui@latest
打开 http://localhost:8080，以管理员登录，选择 Work 和兼容模型，然后描述
项目或更改。
Docker 缺失、停止或不可访问时，Work 显示运行时不可用和原因，并禁用运行编辑器。 Libre WebUI 绝不会退回在主机直接执行 Work 命令。
首次使用会检查运行时镜像，缺少时自动拉取，因此第一项操作可能更慢。
使用 Work 界面
创建和重新访问任务
在侧边栏选择 Work，输入指令、选择模型并点击运行。第一条消息创建任务、 首次运行、提供商路由和持久工作区。
任务保留在主侧边栏。重新打开会恢复最近对话、文件视图、提供商/模型和工作区；旧 消息可分页加载。可从标题重命名，从菜单或侧边栏永久删除。
每任务只能有一个活动运行。后续指令在同一对话和文件系统中创建新运行。
编辑器支持听写：麦克风按钮优先使用浏览器语音 API，否则使用配置的语音转文字模型， 并把转写附加到已输入内容。运行创建或移动的文件会在对应工具活动下显示为可点击 标签；点击会在文件编辑器打开（窄屏自动切换工作区）。标签只来自修改型工具，因此 读了二十个文件但写一个时只显示该一个产物。
雇用代理
有角色时，首页提供雇为代理：选择角色后，任务成为持久命名代理，而非一次性任务。 角色名称和系统提示词会前置到 Work 系统提示词（沙箱运行时契约始终覆盖它们）。 侧边栏在临时任务上方的代理组固定这些代理，并显示头像、活动指示和单行状态。 侧边栏收起时，导航栏中只保留这些固定的代理头像；展开侧边栏后，一次性 Work 任务 会重新出现。
状态有两级。对于已雇代理，运行结束时一次低成本无工具模型请求会要求约 8 个词的
状态（"Inbox at zero. 2 replies ready."）；回复限制为一个 90 字符行，失败或超时
回退到确定性级别，即最终助手消息首行。临时任务和失败运行只用确定性级别；
WORK_STATUS_BLURB_MODEL=0 完全禁用模型请求。代理还带未读指示：打开任务推进按任务
已查看标记（单调且跨设备同步），运行在该标记后到达终态时侧边栏显示圆点。
代理也通过通知报告状态，可在应用内及启用时通过 Web Push：完成时
work-run-finished，等待输入或失败时 work-run-attention，请求人类接管屏幕时
work-takeover（屏幕横幅仅在屏幕标签打开时可见，推送可在其他位置联系你）。
每条通知直接链接代理。
可使用自己拥有或别人共享的角色雇用；共享视图绝不暴露所有者角色记忆。如果角色
后来删除，代理会在没有角色的情况下继续运行并记录警告。创建任务 API 接受
personaId 和 isAgent；带角色创建的任务自动成为代理。
代理标签
代理工作区会多一个位于最前的代理标签：
- **身份：**角色头像、名称、活动指示和最新状态行。
- **屏幕：**政策授予 Work Computer 时，显示代理屏幕的紧凑实时只读缩略图。它是 真正查看器（计入每任务查看器预算）；点击打开完整屏幕标签，其中有接管、教学和音频。
- **例程：**绑定该任务的自动化。每次触发都在代理自己的工作区和
对话中，使用其模型和运行时，不会创建新任务，因此晨间简报会积累在一个位置。
行以文字显示日程并有暂停/恢复开关，内联 + 例程表单已绑定代理。代理忙碌时
触发会诚实失败为
work-task-busy，不会排队。 - **自动审查：**按代理的审批开关，以及代理已积累的“始终允许”规则（移除某条规则即可 重新收紧其范围）。任务策略强制审查时，该开关会被锁定为开启。
- **已教学技能：**教学模式演示的程序，每项技能有启用/禁用开关。
已连接工具（MCP 和 OpenAPI 服务器）
Work 代理可以调用为聊天配置的同一批工具服务器——MCP 或 OpenAPI，由管理员在设置 → 工具中注册。工具以带命名空间的名称（server__tool）呈现给代理，调用由 Libre WebUI 后端通过加固的工具网关发出（带 SSRF 防护的出站、按用户划分的凭据、大小与时间上限），绝不从沙箱内部发出。
提供给自主运行的工具是诚实的：
- 离线任务不提供任何工具：无论后端能否出站，没有网络访问的任务始终保持离线，理由与
web_search相同。 - 需要用户尚未保存的个人凭据的服务器会在提供阶段被过滤掉，因为自主运行无法停下来索要凭据。在设置 → 工具中补上凭据后，下一次运行就会提供该服务器。
- 工具访问模式（仅管理员或所有用户）和按服务器的可见性与聊天中完全一致；角色的工具服务器绑定还会收窄其受雇代理可见的服务器范围。
- 审批生效时，服务器归类为有副作用的已连接工具会像其他受控操作一样暂停等待你的决定；只读工具无需询问即可运行。
代理之间的委派（@ 提及）
受雇代理之间可以互相移交工作。在 Work 输入框中键入 @ 即可提及你的另一个代理；当前代理会在指令中看到同伴名册（名称和状态行），并用 message_agent 工具委派相符的请求。委派是通过消息进行的协作，刻意不共享计算机：每个代理都保有自己隔离的工作区和沙箱，被委派方看不到发起委派的对话——请求必须自带上下文。
委派是异步的。工具立即返回，目标代理在它自己的任务中运行（其对话中会把该请求标注为由发送方委派），当它结束时——完成、需要输入、失败或被取消——它的最终回复会作为一条标注为该代理报告的消息送回发起委派的对话。如果发起方仍在运行，报告会在下一轮到达其模型；如果它处于空闲，报告就留在对话中等待——报告绝不会自动开始一次运行，因此两个代理不会互相来回触发。被委派的运行不能再向下委派；目标代理忙碌时会诚实失败而不是排队；审批生效时，message_agent 也会像其他有副作用的操作一样暂停等待审查（“始终允许”规则只作用于那一个目标代理）。
操作审批（自动审查）
有副作用的操作可以在执行前暂停等待你的决定。当任务的审批生效时——其 Work 策略设置了对有副作用的操作要求审批，或代理的自动审查开关处于开启——运行会在执行 run_command、computer_act、delete_file、move_file 或 message_agent 之前停下，并在对话中显示一张决策卡片：允许一次、始终允许或拒绝。
- 允许一次只运行这一次调用，下次仍会询问。
- 始终允许运行该调用，并在任务上持久保存一条规则：文件和计算机操作按工具整体生效；
run_command按命令的程序名（第一个词）限定范围——批准npm run build会预先批准以后的npm命令，而不是整个 Shell；message_agent则限定为那一个目标代理。规则列在代理标签的“自动审查”区域，也可以在那里移除。 - 拒绝会拒绝该调用。模型会被告知用户拒绝了这项操作且不得原样重试；运行带着这个答复继续。
待处理的审批还会产生一条通知（应用内，启用后也会走 Web 推送），因为运行撞上这道关卡时，可能已经无人值守地工作了几分钟。若五分钟内无人决定，请求过期，操作不会执行，运行以需要输入结束并正常交接，而不是耗尽自己的预算。
审批约束的是操作而不是可见性：write_file 和各项只读工具不受限制，而每一次决定都会记入安全审计日志。
理解任务状态
| 界面状态 | 后端状态 | 指示颜色 |
|---|---|---|
| 空闲 | idle | rgb(255, 255, 255) |
| 思考中 | preparing 或 running | rgb(48, 121, 255) |
| 已完成 | completed | rgb(76, 212, 117) |
| 需要输入 | needs_input 或 cancelled | rgb(255, 204, 0) |
| 错误 | failed | rgb(255, 61, 129) |
停止活动运行会改为需要输入并保留文件。耗尽轮次或工具安全预算也会在最终无工具 交接后进入该状态，因此未完成工作绝不标为已完成。
活动运行不锁定对话：工作期间发送的消息立即加入，并在下一轮到达模型，因此可不停机 引导、纠正或补充上下文；停止按钮仍在发送旁。
调整工作区大小
在 xl 桌面断点，对话和工作区共享可拖动分栏：
- 默认对话宽度 45%。
- 首选范围 30%–70%，受内容最小宽度约束。
- 比例按当前浏览器中的登录用户保存。
- 方向键移动 2%；按住 Shift 为 10%。
- Home 和 End 选择最小/最大。
- Enter 或双击重置。
控件遵循书写方向。阿拉伯语中对话在右、工作区在左，拖动和键盘仍符合视觉方向。 小屏使用任务标题中的对话/工作区控件切换。
文件
文件标签浏览 /workspace 的直接子项，只打开严格有效 UTF-8 文本，并保存到任务卷。
无效字节序列会被拒绝，不会有损替换。
编辑器提供：
- 常见网页、系统、脚本、数据和标记语言的明暗语法高亮；
Cmd/Ctrl+S保存；Shift+Alt+F格式化受支持文件；- 乐观保存冲突检测；
- 按任务和路径存储在浏览器会话中的草稿；以及
- 有未保存编辑时的导航警告。
超过 8,000 个字符或 400 行时实时高亮暂停。JavaScript/JSX、TypeScript/TSX、 JSON、CSS/SCSS/Less、HTML、Markdown/MDX、YAML 格式化支持 100,000 字符和 4,000 行。
模型更改已打开文件时，文件标签显示自本轮开始的红绿更改视图，折叠长未变片段。
工具栏切换 diff/编辑器，+added −removed 汇总。基线是本轮前浏览器最后所见内容；
本轮后首次打开的文件无 diff。
浏览器草稿只是便利，不是备份；成功保存、删除任务或会话结束后会消失。
活动
活动标签显示工具调用、结果、文件操作、命令输出和错误。工具元数据可在对话中展开。 即使界面 RTL，命令和工具输出也保持 LTR。
运行期间，Libre WebUI 打开认证服务器发送事件流，可携带：
- 初始
snapshot和后续run_state； - 提供商明确暴露时的
reasoning_delta； assistant_delta文本；tool_call和tool_result；usage；- 服务器指导的
skill_loaded；以及 - 终态
error或done。
推理可用性和粒度取决于模型/提供商。Libre WebUI 只显示 API 返回内容，无法恢复 隐藏思维链；部分模型没有推理流。文本和工具可独立流式。输出明确受限；截断不代表 没有更多内容，应缩小检查范围。
Git
Git 标签对任务自己的 /workspace 提供本地操作：
- 初始化带
main分支的仓库； - 查看 porcelain 状态、领先/落后及最多 20 个提交；
- 查看路径的受限文本 diff；
- 每次暂存最多 200 个明确路径；
- 用管理员用户名和邮箱或本地 no-reply 地址提交；
- 首次提交后创建本地分支；以及
- 工作树干净时切换现有本地分支。
此界面明确仅本地：没有 clone、fetch、pull、push、远程管理、任意 Git 命令、 令牌、SSH 密钥或 pull request。远程操作需要独立可信凭据代理，最好是单仓库单操作 的 GitHub App。不要把长期 Git 凭据放入工作区、容器环境或仓库配置。
读取可在空闲或活动时运行。模型运行、终端或预览占用容器时拒绝写入；切分支还要求 干净工作树，避免与模型竞争。
每个 UI Git 命令都是固定参数数组，以 UID/GID 1000:1000 在容器执行；用户输入
绝不由 shell 解释。系统/全局配置、提示、hooks、凭据助手、提交签名、子模块递归、
外部 diff、textconv 和网络协议均禁用。工作树不准确为 /workspace 或 Git/common
目录解析到外部的仓库会被拒绝；可执行 clean、smudge、process 过滤器也阻止相关写入。
这些控制保护 Libre WebUI Git API。管理员仍可用终端、模型仍可用 run_command
运行普通 Git；沙箱和部署边界仍控制任意命令。
内置 worker 技能
每次运行获得服务器拥有的工作区指南，说明 /workspace 持久边界、只读容器根、
临时进程和 /tmp、网络政策、命令/输出限制及预览生命周期。技能要求模型：
- 编辑前检查项目指令、清单、锁文件、脚本和仓库状态；
- 保留无关工作并批量读取/搜索；
- 继续实施，不止停在计划；
- 先聚焦验证再广泛检查；
- 诊断失败而非盲目重试；以及
- 在最后启动长期预览前验证应用。
指南只在模型上下文存在；Libre WebUI 不在工作区创建 AGENTS.md、技能目录或其他
控制文件。项目指令不能覆盖容器或工具安全边界。
终端
终端标签连接同一沙箱容器中的交互 shell，让管理员在浏览器内检查、手动构建或调试。
它以 1000:1000 在 /workspace 中运行，采用与模型工具相同的加固政策，不授予
run_command 没有的权限。
- **认证：**浏览器用普通 Authorization 换取绑定任务和 Work 终端协议的短期单次
票据；
/ws/work-terminalURL 只含票据和任务 ID。每次输入前重查账户、权限和所有权。 - **来源检查：**配置
CORS_ORIGIN或BASE_URL后，浏览器升级必须匹配。无来源 Electron/非浏览器客户端仍需票据和实时授权；用 TLS、防火墙和代理控制。 - **准入：**开放终端取得运行时租约并计入
WORK_MAX_ACTIVE_RUNTIMES_*。 - **容器寿命：**连接终端保持容器运行。
- 并发：
WORK_TERMINAL_MAX_SESSIONS_PER_TASK默认 2。 - 空闲超时：
WORK_TERMINAL_IDLE_TIMEOUT_MS默认 15 分钟。 - **运行期间：**模型拥有容器，本轮结束后 shell 才打开。
终端直接使用 Docker Engine API，因为 TTY 需要劫持双向流。它依次使用
WORK_DOCKER_SOCKET、DOCKER_HOST（unix:// 或普通 HTTP tcp://，含通过
Connection: Upgrade 转发的代理）和 /var/run/docker.sock。不支持 ssh://
或设置 DOCKER_TLS_VERIFY 的 tcp:// 时会报告原因，不会连接其他位置。Kubernetes
通过 API 服务器 exec 子资源的 TTY WebSocket（含调整大小）运行，不涉及 Docker。
终端会话不记录，输入命令不出现在活动时间线。
预览
预览标签启动、停止、嵌入和打开生成应用。命令为空时，Libre WebUI 检查工作区并：
- 运行根
package.json的dev脚本并指定主机和端口； - 用内置零依赖静态服务器提供根
index.html；或 - 对一个嵌套应用使用相同规则。
根应用优先。多个同等嵌套应用或无入口时返回可操作错误，不会尝试无关 npm 命令。
其他布局请在启动预览前输入自定义命令。命令从 /workspace 开始，例如
cd apps/web && npm run dev -- --host 0.0.0.0 --port 4173，必须监听 0.0.0.0
和配置的 WORK_PREVIEW_PORT。Work 最多等待 15 秒。
模型也可通过 start_preview 启动。这是模型留下运行进程的唯一受支持方式；普通
run_command 完成时会清理后台后代。
屏幕（Work Computer）
观看完整演示：一次真实、未经剪辑的运行 （先 30x，后实时），Work 代理在自己的屏幕浏览 NASA 图库、选择照片，然后构建并 测试交互式 Three.js 图库，全程只用一个提示词。
政策启用 Work Computer 的任务会获得屏幕标签：同一沙箱中虚拟桌面的实时窗口， 包含窗口管理器、dock 和 1280×800 的 Chromium。你可以观看代理、接管鼠标键盘、 收听音频并通过演示教学。打开标签按需启动 GUI（无人查看时不运行）并连接 VNC-over- WebSocket 查看器。
管理员在 Work 首页的 Work Computer 卡点击启用即可。它在部署自己的 Docker
daemon 上构建内置 GUI 镜像（首次几分钟）并创建可用政策，无需手动 docker build
或填写政策字段。过滤代理明确拒绝 build；请在 Docker 主机拉取
ghcr.io/libre-webui/libre-work-computer 并标为 libre-work-computer:latest，
或从 deploy/work-computer/ 构建；启用随后只创建政策。任务必须有网络，因为
屏幕像预览一样通过 loopback 发布端口访问。
安全模型：容器 VNC 绑定 localhost，使用每会话只读密码和全控密码。所有授权查看者
只获只读密码，当前控制租约持有人独占全控密码，因此其他输入由 VNC 自身禁用。
WebSocket 桥是唯一可达面，发布在主机 loopback，绝不直接暴露。查看者用绑定会话和
任务的单次票据认证，每次连接重查 Work 权限；撤权立即断开。每屏最多四个查看者，
查看计入任务活动。查看不与运行竞争：可附着运行中的沙箱，不阻止下一次运行，运行
结束后仍维持，包括使用独立 worker 的团队部署。浏览器配置持久在
/workspace/.browser-profile，登录可跨容器重启。
代理获得两个工具：computer_observe 返回完整截图、光标、活动窗口、当前 URL、页面
是否拥有键盘焦点、焦点元素摘要和截图哈希；语义信号来自容器 loopback 的 DevTools，
旧 GUI 镜像中缺失。computer_act 批量执行最多 24 个鼠标/键盘操作并返回稳定截图。
type/key 可声明 focus，焦点不符时安全失败；窗口出现、标题变化或焦点中途移动
会提前停止；可声明预期标题、URL 或区域变化，由自适应期限验证，“pending”表示尚未
观察，绝不代表成功。屏幕通过轮询自适应稳定。坐标点击返回附近像素是否变化；
scroll_until 滚向文本或页面边缘并报告可见性；观察与前一项比较。subgoal 可作为
检查点保留并在恢复提示中回显。三次相同无效操作触发一次恢复提示，再重复会请求输入；
连续未验证预期触发重新落地。轮次、工具延迟、截图、护栏和预期结论写入工具记录并在
结束汇总。
截图在所有提供商路由中作为真实图像送给模型：Ollama、Anthropic、Gemini 及兼容 OpenAI 的 Chat/Responses 插件。因此驱动任务应为视觉模型。如果提供商拒绝图像输入 （纯文本模型），运行不会失败：余下运行丢弃截图，通知模型依赖文本观察，并在转录中 记录降级。但看不到屏幕的模型验证能力明显更弱，计算机任务应优先视觉模型。实时上下文 只保留最近截图，持久转录只存文本观察，绝不存图像字节。
浏览器内置内容拦截：uBlock Origin Lite 拦广告和跟踪器（镜像构建时固定版本并校验 校验和，过滤模式由托管政策固定），另有自动关闭 cookie 同意横幅的工具，因为广告和 同意墙会浪费截图、令牌和点击。已知广告脚本会按 uBlock 方式解析为无害本地 stub， 保持页面工作。代理被要求绝不输入凭据或完成 CAPTCHA/2FA，而是报告阻碍。不可信任务 应配合过滤 DNS；桌面浏览器使网络出站政策更重要。
音频默认静音（浏览器要求点击）；屏幕面板扬声器按钮实时传输声音。PulseAudio 输出到
null sink，monitor 作为原始 PCM 捕获并通过第二条认证 loopback WebSocket 桥提供，
使用相同票据、权限复验和查看者上限。要求当前或更新的 deploy/work-computer/ 镜像。
接管提供鼠标键盘，用于登录、处理 CAPTCHA 或代理不得执行的步骤；完成归还。
控制租约有 TTL（遗弃后两分钟内过期）、界面打开时续租且不可抢占。政策可禁用
允许屏幕接管；查看仍可用。人类控制时 computer_observe 和 computer_act
都被阻止。request_takeover 在屏幕显示原因并等待接管后归还。凭据直接从键盘到页面，
不经过模型或转录。旧镜像会话仍可看，但所有人只读。
教学任务记录演示：你接管真实屏幕并显示录制标志，捕获指针、键盘和滚动坐标。
每次点击还会解析元素标签、ID、可见标签和 URL，使步骤写成
"Click "button#submit (Place order)""，坐标只是提示。保存过程确定且无模型参与：
按键合并为文本，8 像素区分点击/拖动，停顿转成等待，包含秘密词汇或凭据形状的文本
（8+ 字符混合三类字符）会脱敏并替换为 request_takeover。自然语言程序含适用时机、
输入、步骤、验证、从实际访问主机派生的允许范围（离开前必须停下询问）、审批边界
和失败处理。它保存为普通技能（slug 前缀 taught-），支持版本、编辑和共享。运行会
加载所有者启用的教学技能。完成后可一键标记成功/失败，在技能历史记录中追加有界
日期行，每行都是新版本。录制时不要输入真实密码。
提供商、路由与数据披露
支持的提供商路由
| 路由 | 验证与行为 |
|---|---|
| 本地 Ollama | Ollama 健康且准确模型宣告工具支持 |
| Ollama Cloud | 明确经 Ollama 路由；云后缀模型显示远程披露 |
| 补全/聊天插件 | 插件活跃、列出准确模型、当前管理员有凭据 |
| Anthropic 插件 | 使用 Work 的 Anthropic messages/tool-use 适配器 |
| Gemini 插件 | 使用 Work 的 Gemini contents/function-calling 适配器 |
| 其他兼容插件 | 使用 OpenAI 风格消息、工具和工具选择 |
提供商类型和插件 ID 同时保存在任务和每次运行上。模型名绝不单独选择路由；同名插件 无法截获现有 Ollama 任务。
提供商收到的内容
每轮可能收到：
- Work 系统提示词；
- 内置 worker 技能和当前限制；
- 最近最多 30 条用户/助手消息，限制 256 KB；
- Work 工具定义；
- 助手工具调用历史；以及
- 工具结果，包括目录列表、所请求文件内容、搜索、命令输出和错误。
命名卷不会整体上传，但工具返回的文件内容和输出会成为模型对话的一部分并发给提供商。 敏感源代码使用前检查远程提供商保留、训练、定价和用量政策。
提供商凭据留在 Libre WebUI 后端，绝不挂载到 Work 容器。应用层凭据加密不是整任务 加密：对话、工具结果、命令输出和元数据是普通数据库内容；文件和依赖是 Docker 卷 或 PVC 中的普通文件。威胁模型要求静态加密时使用主机访问控制和磁盘加密。
远程提供商披露
Work 将插件模型及以 :cloud 或 -cloud 结尾的 Ollama 名称视为远程。选择时显示
可关闭提示，说明数据流和多次计费调用；偏好按用户保存。
所有路由使用 WORK_MAX_AGENT_ROUNDS，默认 48 轮，无单独 12 轮插件限制。工具安全
预算是 128 次或每配置轮 8 次中的较大者。预算耗尽时，Libre 请求一次最终无工具交接，
说明完成内容、检查、阻碍和后续步骤，随后记录为需要输入。后续运行在同一持久
工作区继续；一次运行仍可能产生多次计费请求。
主机文件夹工作区（可选）
Docker 后端通常让 /workspace 使用任务专属命名卷，模型无法接触真实文件。部署可
允许绑定主机实际文件夹；Kubernetes 拒绝并使用任务 PVC。
设置两个变量并重启：
WORK_HOST_WORKSPACES_ENABLED=true
WORK_HOST_WORKSPACE_ROOTS=/Users/you/Projects
WORK_HOST_WORKSPACE_ROOTS 是 : 分隔根列表，默认服务器用户 home。启用后首页有
可选工作区文件夹；留空仍使用隔离卷。
路径必须绝对、存在、为目录，并在解析符号链接后位于配置根内。.ssh、.gnupg、
.aws、.config、.kube、.docker、.claude、.libre-webui、node_modules
一律拒绝。解析路径随任务保存并在标题显示。
主机工作区意味着模型读写真正文件，非 root、能力移除和资源限制不再把它与该目录 隔开。除非明确需要，否则保持关闭；根尽量狭窄，并优先受版本控制的目录。
持久性与运行时生命周期
Libre WebUI 分离持久状态和执行状态：
| 状态 | 存储 | 生命周期 |
|---|---|---|
| 任务所有权、标题、提供商和状态 | Libre WebUI 数据库 | 直到删除任务或所属用户 |
| 运行、错误、消息和工具活动 | Libre WebUI 数据库 | 直到删除任务 |
| 工作区文件 | 任务 Docker 卷或 K8s PVC | 运行取消、预览停止、沙箱/应用重启后仍保留 |
| 根文件系统和临时文件 | 任务容器或 Pod | 可丢弃；可停止或重建 |
| 预览进程 | 运行中的任务沙箱 | 临时；仅在验证健康时保留 |
| 未保存编辑草稿 | 浏览器会话存储 | 临时便利状态 |
每任务获得服务器生成 UUID。沙箱和工作区名称由后端派生，绝不接受浏览器提供。资源带 管理和任务所有权标签；复用或删除前验证，拒绝属于其他任务的资源。
沙箱按需准备。文件辅助操作会停止原本空闲的沙箱，命令完成后停止沙箱，健康预览可保持 运行供用户检查。重启或重建时重新挂载持久工作区。
管理员可从设置中的用户管理选项卡定义命名运行时政策：镜像、内存/CPU/PID 限制、Kubernetes 工作区大小、空闲超时、默认网络，以及 Work Computer (GUI + browser) 和 允许屏幕接管。任务按政策运行；空字段继承全局值，删除政策后任务下次重建恢复 全局值。政策只调整资源和能力开关，不能削弱非 root、只读根、能力移除和网络隔离。
WORK_RUNTIME_IDLE_TIMEOUT_MS 限制预览宽限：设置后，清理程序会停止在该毫秒数内
没有命令、终端或签名代理预览活动的沙箱，释放准入。工作区持久，下一次使用重启。
默认 0 保持预览到明确停止。
后端启动时活动运行标为失败，预览状态清除，因为代理循环和代理无法恢复。驱动通过 一次标签查询列出资源；停止已知任务的运行沙箱，保留已停止沙箱，删除无任务行的孤儿。 所有权来自标签而非名称。不要让两个实例指向同一资源。无法证明清理时 Work 安全关闭， 每 10 秒重试并阻止新可变操作。
网络行为
没有命名政策的任务默认启用网络。管理员可定义默认关闭网络的政策，创建者可选择。 没有独立任务网络开关；更改政策后需重建沙箱才生效。
Docker 网络任务连接专用托管 bridge（默认 libre-webui-work，由
WORK_NETWORK_NAME 指定），并关闭容器间通信
（com.docker.network.bridge.enable_icc=false）。因此 Work 沙箱不能互连，也不能
访问默认 bridge 上未明确发布的数据库或 Ollama 等部署容器。
若配置名称已存在但不是托管网络，Libre WebUI 会拒绝启动而非静默连接。
Kubernetes Pod 带相同网络标签。Helm 安装默认拒绝 NetworkPolicy、仅预览入站，
以及只对启用网络 Pod 开放互联网出站，同时排除
work.networkPolicy.blockedEgressCidrs。只有 CNI 强制执行时才有效，见
Kubernetes 指南。
外部出站仍允许，因为包下载、远程 Git 和外部 API 是 Work 的用途。这不是出站防火墙。 生成代码可能访问 Docker 主机服务、主机 LAN、互联网服务和基础设施元数据端点。
出站政策挂钩
组合使用：
- **
WORK_RUNTIME_DNS(Docker)：**逗号分隔 IPv4/IPv6 解析器，通过--dns强制。 非地址条目拒绝并记录，不能注入其他 Docker 标志。 - 主机或上游防火墙规则应用于稳定的托管 bridge 子网。
WORK_NETWORK_NAME指向预创建网络；必须有托管标签并禁用 ICC。
DNS 只限制名称解析，不阻止直接 IP；需要主机、集群或上游防火墙。不要假设 Work 防止数据传输，只授予可信用户。需要离线时使用命名无网络政策；无全局环境变量改变默认。
网络不添加凭据。Libre WebUI 不挂载 SSH 密钥、云凭据、浏览器配置、主机 home 或
Docker socket。但用户或模型写入 /workspace 的秘密仍可被代码传出。
沙箱流量与模型流量分离；Ollama 和插件请求始终由后端发往明确选择的路由。
沙箱安全边界
Docker Work 容器：
- 以非 root UID/GID
1000:1000运行； - 使用
/workspace作为工作目录； - 只挂载所选任务卷；
- 使用只读根和受限
/tmp； - 移除全部 Linux capabilities；
- 启用
no-new-privileges； - 非特权并使用 init；
- 限制 CPU、内存、进程、命令时间和输出；
- 将
--memory-swap设为--memory； - 使用禁用容器间通信的托管网络或无网络；以及
- 只把预览端口发布到 Docker 分配的主机 loopback 端口。
复用前通过 docker inspect 复验所有内容，整体哈希写入
ai.libre-webui.policy。政策早于 Libre WebUI 升级的容器会销毁重建，使加固自动
覆盖现有任务。
Kubernetes 采用等价安全上下文：非 root UID/GID、只读根、RuntimeDefault seccomp、
禁止提权、移除全部能力、受限临时存储和资源、不挂 ServiceAccount 令牌，任务 PVC
挂载 /workspace。复用或删除 Pod/PVC 前验证标签和政策指纹。
路径验证拒绝绝对路径、遍历段、反斜杠、NUL 和过长路径。文件辅助程序解析真实路径并 拒绝符号链接逃逸；写入使用临时文件和原子重命名。
这些控制减少意外主机暴露，但不会把 Work 变成虚拟机或安全恶意软件分析环境。 容器共享主机内核；Docker、Kubernetes、运行时、镜像、依赖或内核漏洞可能越界。
Docker 命名卷没有独立磁盘配额。生成项目或包安装可能耗尽存储；监控卷增长并应用 主机级限制。Kubernetes 请求 PVC 大小；实际强制取决于存储供应器。
Docker 生产加固清单
此清单专用于 Docker。Kubernetes 运维人员还应按 Kubernetes 指南验证命名空间 RBAC、Pod 安全、存储类和 CNI NetworkPolicy 强制执行。应用可设置容器标志、验证路径并保护自身 API，但无法强制 主机防火墙、存储驱动配额或 daemon 权限；这些是私有实例的明确部署工作。
1. 隔离 Docker 控制
主容器需要 daemon 控制来创建和检查 Work 容器。因此挂载 socket 是控制面凭据， 不是普通数据挂载；应用被攻破可能导致主机被攻破。
docker-compose.socket-proxy.yml 把 socket 完全放在 Libre WebUI 容器外。内部代理
持有 /var/run/docker.sock，只转发容器、镜像、卷、网络、exec 和 info；swarm、
secrets、configs、build、commit、system 在到达 daemon 前被拒绝。Libre WebUI 通过
DOCKER_HOST=tcp://docker-socket-proxy:2375 访问，无需挂载或组成员；CLI、终端和诊断
都使用它。代理缩小 API 面，不缩小允许操作的影响：能创建容器者仍可挂载主机路径。
更强边界是在专用 VM 运行 Libre WebUI 和 Work daemon；更进一步使用专用 rootless daemon 或独立运行主机。上线前验证所有权、预览路由、清理和终端。只读挂载同一 rootful socket 不会让 API 只读。
2. 阻止沙箱访问主机管理服务
禁用容器间通信不阻止访问绑定在 Docker 主机的服务。检查真实 bridge 和子网：
docker network inspect libre-webui-work \
--format 'id={{.Id}} subnets={{range .IPAM.Config}}{{.Subnet}} {{end}}'
ss -lntup
用持久防火墙拒绝来自 bridge 到 SSH、Docker API、数据库和管理端口的流量。从临时
容器测试规则和允许下载后持久化。DOCKER-USER 控制转发；目的为主机本身时还可能
需要 bridge 接口的 INPUT 规则。
3. 限制出站目的地
除非项目明确需要，否则阻止云元数据、私有基础设施和客户 LAN。结合
WORK_RUNTIME_DNS 与主机/上游防火墙。DNS 可被字面 IP 绕过；任意命令可直连时
HTTP 代理也不足，应在容器外强制。为离线、仅包注册表和开放出站维护独立政策。
4. 强制真实存储配额
CPU、内存、swap、PID 限制不约束命名卷。多客户前选择可强制每工作区配额的存储：
XFS 项目配额、配额逻辑卷或有限大小的卷/PVC 驱动。普通 ext4 上 Docker local
不会因记录大小就有可靠配额。
监控每个 ai.libre-webui.managed=true 卷和 Docker 数据根，在文件系统满前告警并
测试故障。界面计数器或周期 du 只是警告，不是强制边界。
5. 验证已部署政策
每次镜像或 daemon 政策变化后创建临时任务，用 docker inspect 检查非 root、
只读根、能力移除、no-new-privileges、内存/swap/CPU/PID 限制、仅任务卷和预期网络。
还要检查主容器挂载，确认公共入口只经过认证代理，而不是误发布端口。
预览安全与可达性
Docker 将预览端口发布到后端 loopback 的动态端口；Kubernetes 后端直接针对 Pod IP。
模型和浏览器不能选择任意上游。Libre WebUI 为准确任务/端点签名能力 URL，每次请求
检查预览仍运行，并通过 /api/work/previews 代理 HTTP/WebSocket。停止或重启会
撤销旧 URL。
预览响应移除 Libre WebUI 凭据和上游 cookie。iframe 沙箱与响应 CSP 允许脚本、 表单、模态框和下载而不授予同源访问；CSP 也保护独立标签。生成代码仍不可信，可通过 网络传输其能读取的内容。将运行预览 URL 视为短期秘密，不要共享。
浏览器从 Libre WebUI 公共来源加载代理，因此远程浏览器和 HTTPS 代理无需暴露端口
或 Pod IP，也不会触发混合内容。反向代理必须保留 /api/work/previews/ WebSocket；
附带 Nginx 配置已处理。
主应用只允许自身和 Cloudflare Turnstile 作为 frame 来源。预览响应绕过主 Helmet 政策以流式传输正文并应用更窄沙箱政策；跨来源嵌入政策仍关闭。
部署矩阵
| 部署 | Work 运行与文件 | 内嵌预览 |
|---|---|---|
本地 npx libre-webui | Docker 已安装、运行且后端用户可调用时支持。 | 通过应用来源签名代理支持。 |
| 本地源代码开发 | 同样 Docker 和提供商要求下支持。 | 通过端口 3001 的开发 API 来源支持。 |
| Electron 桌面客户端 | 有条件支持；Electron 使用外部后端，不提供单独 Work 运行时。 | 通过该后端签名代理支持。 |
| 远程裸机或 VM 后端 | 该主机有 Docker 时运行、文件和提供商调用正常。 | 公共代理保留 HTTP/WebSocket 时支持。 |
| 标准仓库 Docker Compose | 在 Docker Desktop 上默认支持：镜像带 Docker CLI，Compose 挂载主机 socket，Work 端口经 host.docker.internal 路由。原生 Docker Engine 还需要一个可达的非公开 WORK_PREVIEW_BIND。 | 通过同一 Libre WebUI 公共来源支持。 |
| 当前 Kubernetes/Helm | 使用 --set work.enabled=true 支持：沙箱为带 PVC 的 Pods，提供运行、文件、命令、git、交互终端及 Pod IP 上 Work Computer 屏幕/音频，使用命名空间 Role 和默认拒绝 NetworkPolicies，完全无 Docker socket。见 Kubernetes 指南。 | 后端在集群内时签名代理直接针对沙箱 Pod IP。 |
Libre WebUI 本身在 Docker 中时运行 Work
所有仓库 Compose 文件都启用 Work：镜像含 Docker CLI，Compose 挂载
/var/run/docker.sock。Docker Desktop 使用随附的路由默认值即可；原生 Docker Engine
还需要把 WORK_PREVIEW_BIND 设为同级容器可达的非公开主机接口，详见下文。
Work 通过 socket 驱动主机
daemon，因此任务容器是 Libre WebUI 容器的同级，出现在主机 docker ps。
在 Web 应用挂载 Docker socket 给予等同 root 的主机控制。Work 没有它无法工作， 因此明确后果：**每位 Libre WebUI 管理员实际上都是 Docker 主机管理员。**删除 Compose 中 socket 行可关闭 Work。
要保留 Work 而不把 socket 交给应用，使用 docker-compose.socket-proxy.yml，代理
在内部持有，Libre WebUI 通过 DOCKER_HOST 访问。见
隔离 Docker 控制。
必须满足：
- **镜像有 Docker CLI。**官方镜像自带；自定义镜像需
docker-cli或WORK_DOCKER_COMMAND。否则：The "docker" CLI is not installed…。 - **挂载 socket。**否则：
No Docker daemon is reachable…。 - **后端用户在 socket 组。**镜像用
nodejs（uid 1001），socket 通常属于root或docker，Compose 传group_add: ['${DOCKER_GID:-0}']。Docker Desktop 默认 适用；Linux 需自己的组 ID。否则：The Docker socket is mounted but the Libre WebUI user cannot open it…。
# Read the socket's group as seen INSIDE a container. A macOS host reports a
# different value, because Docker Desktop proxies the socket through a VM.
echo "DOCKER_GID=$(docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
alpine stat -c '%g' /var/run/docker.sock)" >> .env
docker compose up -d --force-recreate
任务预览端口保持绑定主机 loopback，通过同源签名代理暴露 HTTP 和 WebSocket。
后端在 Docker 时保留 WORK_PREVIEW_BIND=127.0.0.1，把
WORK_DOCKER_PUBLISHED_HOST 设为容器可达主机地址（Docker Desktop 为
host.docker.internal）。随附的 Compose 配置会设置这两个值并映射该主机名。
原生 Linux 部署必须把 WORK_PREVIEW_BIND 覆盖为 Docker 网桥网关（或其他明确可达
的非公开主机接口）；只映射 host.docker.internal 并不能让主机 loopback 监听端口
变得可达。切勿把这些原始临时端口绑定到 0.0.0.0。
并发独立限制：WORK_MAX_ACTIVE_RUNTIMES_PER_USER 默认 2，
WORK_MAX_ACTIVE_RUNTIMES_GLOBAL 默认 3。能力响应报告限制和实时占用。
Kubernetes 应安装 work.enabled=true 而不是暴露节点运行时 socket；Helm 创建
相关 RBAC、命名空间、网络政策和 Pod/PVC，见 Kubernetes 指南。
运行时配置
| 变量 | 默认值 | 用途 |
|---|---|---|
WORK_RUNTIME_BACKEND | docker | 沙箱驱动：docker 或 kubernetes |
WORK_RUNTIME_IMAGE | node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3 | 任务沙箱镜像 |
WORK_DOCKER_COMMAND | docker | Docker 后端 CLI |
WORK_COMMAND_TIMEOUT_MS | 120000 | 默认命令超时 |
WORK_MAX_OUTPUT_CHARS | 50000 | 最大捕获输出 |
WORK_MAX_AGENT_ROUNDS | 48 | 每次运行模型/工具轮次预算 |
WORK_MEMORY_LIMIT | 2g | 每容器内存 |
WORK_CPU_LIMIT | 2 | 每容器 CPU |
WORK_PIDS_LIMIT | 256 | 每容器进程 |
WORK_PREVIEW_PORT | 4173 | 应用必须监听的容器端口 |
WORK_PREVIEW_BIND | 127.0.0.1 | 预览发布主机接口 |
WORK_DOCKER_PUBLISHED_HOST | 与 WORK_PREVIEW_BIND 相同 | 后端拨号 Docker 发布端口的主机/IP |
WORK_COMPUTER_SCREEN_PORT | 6080 | 屏幕桥 WebSocket 端口 |
WORK_COMPUTER_AUDIO_PORT | 6081 | 音频桥 WebSocket 端口 |
WORK_RUN_LEASE_WAIT_MS | 60000 | 运行等待临时租约的时长 |
WORK_MAX_ACTIVE_RUNTIMES_GLOBAL | 3 | 每实例并发容器任务 |
WORK_MAX_ACTIVE_RUNTIMES_PER_USER | 2 | 每管理员并发容器任务 |
WORK_MAX_TASKS_GLOBAL | 500 | 每实例持久任务上限 |
WORK_MAX_TASKS_PER_USER | 100 | 每管理员持久任务上限 |
WORK_NETWORK_NAME | libre-webui-work | 网络任务托管 bridge |
WORK_RUNTIME_DNS | 未设置 | 强制到网络任务的逗号分隔解析器 IP |
WORK_DOCKER_SOCKET | DOCKER_HOST 为 unix:// 或 tcp:// 时使用，否则 /var/run/docker.sock | 交互终端 Docker Engine 端点 |
WORK_TERMINAL_MAX_SESSIONS_PER_TASK | 2 | 每任务并发交互终端 |
WORK_TERMINAL_IDLE_TIMEOUT_MS | 900000 | 终端空闲超时 |
WORK_RUNTIME_IDLE_TIMEOUT_MS | 0（禁用） | 空闲后停止沙箱（含预览） |
WORK_K8S_NAMESPACE | libre-webui-work | Kubernetes 沙箱 Pod/PVC 命名空间 |
WORK_K8S_STORAGE_CLASS | 集群默认 | 工作区 PVC StorageClass |
WORK_K8S_WORKSPACE_SIZE | 5Gi | 每任务默认 PVC 大小 |
WORK_K8S_POD_READY_TIMEOUT_MS | 900000 | 等待 Pod 就绪最大时长 |
WORK_K8S_POD_GONE_TIMEOUT_MS | 60000 | 等待已删除 Pod 消失最大时长 |
生产使用固定镜像版本或 digest。运行、预览、文件、命令和沙箱重建共享进程内容量计数； 已计任务上的嵌套操作不另计。超限请求返回 HTTP 429。
固定协议和界面限制
| 项目 | 限制 |
|---|---|
| 新任务或运行消息 | 65,536 个字符和 UTF-8 字节 |
| 创建/更新任务的模型 ID | 500 个字符和 UTF-8 字节 |
| 插件提供商 ID | 200 个字符 |
| 每任务活动运行 | 1 |
| 命令文本 | 20,000 个字符 |
| 工具请求命令超时 | 1 到 600 秒 |
| 预览就绪 | 15 秒 |
| 文件读写 | 2,000,000 字节 UTF-8 文本 |
| 直接目录列表 | 前 1,000 项 |
| 消息页 | 最多 200 条消息和 1,000,000 字节 |
| 单条持久消息 | 100 KB |
| 发送给模型的上下文 | 最近 30 条用户/助手消息，最多 256 KB |
| 持久工具输出 | 约 20,000 个源字符及标记 |
| 实时编辑器高亮 | 8,000 个字符和 400 行 |
| 浏览器端格式化 | 100,000 个字符和 4,000 行 |
| Git 状态输出 | 2,000,000 个捕获字符 |
| Git diff 输出 | 600,000 个捕获字符 |
| Git 历史 | 20 个本地提交 |
| 单次 Git 暂存路径 | 200 |
| Git 提交消息 | 4,000 个字符 |
| 代理循环，所有提供商 | 默认 48 轮，由 WORK_MAX_AGENT_ROUNDS 配置 |
| 工具调用安全预算 | max(128, configured rounds × 8) 次调用 |
文件访问仅支持 UTF-8 文本；集成编辑器不编辑二进制文件，超过 2 MB 的文件无法通过 Work 文件 API 打开。
API 摘要
所有端点在 /api/work 下，要求认证和数据库中的当前 Work 权限。默认仅管理员；普通
任务操作可开放给活跃用户。主机文件夹和管理政策/权限端点仍仅管理员。
| 方法 | 路径 | 用途 |
|---|---|---|
GET | /capabilities | 所选运行时/提供商可用性和限制 |
GET | /tasks | 列出当前管理员任务 |
POST | /tasks | 创建任务和首次异步运行 |
GET | /tasks/:id | 加载任务状态和最近消息 |
GET | /tasks/:id/messages | 分页加载旧消息 |
PATCH | /tasks/:id | 重命名或更改明确模型路由 |
DELETE | /tasks/:id | 删除任务和持久工作区 |
POST | /tasks/:id/runs | 开始后续运行 |
POST | /tasks/:id/messages | 活动运行期间向代理发送消息 |
GET | /tasks/:taskId/runs/:runId/events | 通过 SSE 流式传输认证运行事件 |
POST | /tasks/:id/cancel | 取消活动运行 |
GET | /tasks/:id/approvals | 待处理审批以及任务的自动审查状态 |
PUT | /tasks/:id/approvals | 切换按任务的审批开关 |
POST | /tasks/:id/approvals/:approvalId | 决定一项待处理审批（允许一次/始终允许、拒绝） |
DELETE | /tasks/:id/approval-rules/:ruleId | 移除一条“始终允许”规则 |
GET | /computer/setup | Work Computer 设置状态 |
POST | /computer/setup | 构建 GUI 镜像并创建政策 |
POST | /tasks/:id/computer/start | 启动 Work Computer 会话 |
GET | /tasks/:id/computer/control | 当前控制者/代理接管请求 |
POST | /tasks/:id/computer/control | 接管或续租控制 |
DELETE | /tasks/:id/computer/control | 将屏幕还给代理 |
POST | /tasks/:id/computer/teach | 将录制演示保存为教学技能 |
POST | /tasks/:id/computer/anchor | 解析录制点击下的元素 |
POST | /computer/skills/:slug/trace | 向教学技能追加成功/失败行 |
GET | /tasks/:id/files | 列出工作区目录 |
GET | /tasks/:id/file | 读取工作区文本文件 |
PUT | /tasks/:id/file | 保存工作区文本文件 |
GET | /tasks/:id/git | 读取受保护 Git 状态和历史 |
GET | /tasks/:id/git/diff | 读取受限本地 diff |
POST | /tasks/:id/git/init | 初始化本地 Git |
POST | /tasks/:id/git/stage | 暂存明确工作区路径 |
POST | /tasks/:id/git/commit | 提交已暂存更改 |
POST | /tasks/:id/git/branches | 创建本地分支 |
POST | /tasks/:id/git/switch | 切换到现有干净本地分支 |
POST | /tasks/:id/preview/start | 启动托管预览 |
POST | /tasks/:id/preview/stop | 停止托管预览 |
任务 ID 始终与认证所有者核对。账户状态、角色和 Work 政策每次请求从数据库读取，旧 JWT
中的过时角色不会阻止撤权生效。更新架构保留 networkEnabled 供内部兼容，不作为独立
界面控件；创建时选择具有所需网络默认值的命名政策。
删除、账户更改与备份
删除任务
删除明确具有破坏性：
- 后端把任务标为正在退役，阻止新可变操作。
- 取消活动运行并停止任务沙箱。
- Libre WebUI 验证运行时资源的任务所有权标签。
- 删除容器/Pod 和命名卷/PVC。
- 删除数据库任务，并级联删除运行和消息。
- API 成功后清除浏览器草稿。
运行时清理失败时保留数据库记录并返回错误，让运维人员修复 Docker/Kubernetes 后端 后重试；不会静默删元数据留下未跟踪资源。停止运行或预览只停止执行，保留卷和对话。
管理员降级与用户删除
管理员降级时，Libre WebUI 先持久化角色撤销，再依赖运行时清理。后续请求检查当前 角色和访问模式。若新角色无权限，后端暂停其 Work 任务并尝试中止运行、停止沙箱。 清理失败不恢复访问，角色更新会报告错误供修复重试。
删除其他用户时先删除其托管 Work 资源。外部清理失败则保留用户记录，避免丢失安全 重试所需所有权元数据。
备份完整任务
完整 Work 备份需要：
- Libre WebUI 数据库，其中含任务所有权、Docker/Kubernetes 资源名、提供商路由、 运行、消息和活动；以及
- 所有带
ai.libre-webui.managed=true的 Docker 卷或 Kubernetes PVC，其中含文件。
临时容器和预览进程无需备份。为保持一致，停止新 Work 活动和后端，再捕获数据库和 工作区，遵循所用后端的卷或存储快照流程。
数据库与匹配工作区一起恢复。按数据库准确名称重建每个卷/PVC，并恢复任务所有权
元数据，包括 ai.libre-webui.task=<task UUID> 和
ai.libre-webui.managed=true。只复制文件不会保留标签；只恢复数据库会缺文件，
只恢复存储会丢失所有权和生成资源名。若还使用加密提供商凭据，请遵循主数据目录和
加密密钥备份指南。
本地化与阿拉伯语 RTL
Work 完整界面支持 25 种语言：英语、阿拉伯语、孟加拉语、捷克语、丹麦语、德语、 西班牙语、法语、印地语、印度尼西亚语、冰岛语、意大利语、日语、韩语、马来语、 荷兰语、波兰语、葡萄牙语、俄语、瑞典语、泰语、土耳其语、乌克兰语、越南语和中文。
阿拉伯语在 React 渲染前应用 lang="ar" 和 dir="rtl"。侧边栏移到右侧，对话在
桌面分栏右侧、工作区左侧，方向图标镜像，标签导航和拖动/键盘调整遵循 RTL。
影响准确性的技术内容保持 LTR：
- 代码和语法高亮；
- 文件系统路径；
- 模型 ID；
- 命令和预览日志；
- 工具输出和元数据；以及
- 代码块内容。
任务名、自然语言提示词、错误、文件名和预览命令按需使用自动文本方向。
故障排除
使用 npx 时运行时不可用
npx libre-webui 在主机运行后端，但不安装 Docker。以启动 Libre WebUI 的同一系统
用户运行 docker info。命令缺失或无法连接 daemon 时安装/启动 Docker 或修复权限，
然后重载 Work。还要确认 Ollama 健康，或至少一个活动聊天/补全插件为当前管理员
配置了模型和凭据。
Docker 或 Kubernetes 中运行时不可用
仓库 Compose 部署不应报告此错误：镜像带 Docker CLI，Compose 挂载主机 socket。
若发生，面板会说明自定义镜像缺 CLI、socket 挂载缺失或容器用户不在组。最后一种
设置 DOCKER_GID 并重建。见
Libre WebUI 本身在 Docker 中时运行 Work。
Kubernetes 使用 --set work.enabled=true 启用原生运行时。Libre 会报告
kubernetes，探测 API，并用 Pod/PVC 运行沙箱。不要挂载节点容器运行时 socket；
见 Kubernetes 指南。
没有兼容 Work 的模型
Ollama 请选择宣告 tools 的模型。插件需确认：
- 类型为补全或聊天；
- 已激活；
- 准确模型出现在模型映射；
- 当前管理员有可用 API 密钥；以及
- 远程模型实现提供商工具调用。
Work 绝不后备到其他提供商。
包安装或远程 Git 失败
确认所选命名政策启用网络；没有独立任务网络开关。检查 DNS、代理、防火墙/ NetworkPolicy、注册表、证书、运行时和上游服务，并确认镜像含命令。
Git 标签只在本地操作。只有网络和凭据政策明确允许时才通过终端或模型命令使用远程 Git。不要把长期令牌粘贴到任务工作区。
运行在代理限制处停止
模型可能耗尽轮次或工具安全预算。Work 结束前请求最终无工具交接，查看已完成内容和
剩余步骤。任务保持需要输入，不会声称完成。开始后续运行继续，或在资源和成本政策
允许时明确提高 WORK_MAX_AGENT_ROUNDS。
开始 Work 时 HTTP 429
实例或管理员达到活动运行时/持久任务准入限制。等待其他运行或预览停止，删除旧任务，
或在资源充足主机明确提高对应 WORK_MAX_*。
预览无法就绪
确认命令持续运行、绑定 0.0.0.0，并在 15 秒内监听 WORK_PREVIEW_PORT。命令为空
时自动检测 package.json dev 或 index.html，包括单个嵌套应用。多个或无入口时
输入明确命令。自定义命令从 /workspace 开始，嵌套应用使用
cd <app-directory> && ...。
服务器预览正常，远程浏览器不正常
确认部署含签名 Work 预览代理，并重启预览替换旧 loopback URL。普通页面加载但热
重载失败时，确认代理/隧道允许 /api/work/previews/ WebSocket。Docker 发布端口
应留在后端 loopback，无需防火墙开放。
文件保留但预览停止
取消、后端重启、明确停止或就绪检查失败后属预期。预览进程临时，命名卷持久。重新 打开任务并启动预览。
文件无法打开或保存
集成文件 API 接受最多 2 MB 的 UTF-8 文本。保存报告自打开后变化时，重新加载再编辑， 避免覆盖其他模型或浏览器更改。高亮超过 8,000 字符或 400 行改为纯文本；格式化另有 100,000 字符和 4,000 行限制，只支持文档中的文件系列。
Work 表示正在恢复沙箱
启动或拆除无法证明一个或多个沙箱已停止。Work 安全关闭并每 10 秒重试。恢复 Docker daemon 或 Kubernetes API 访问并检查后端日志。标记资源尚需协调时不要删数据库行。
任务删除失败
确认所选运行时可达。缺少预期 ai.libre-webui.task 标签的冲突资源会被拒绝而非删除。
谨慎解决名称/所有权冲突后重试。
安全摘要
- Work 默认仅管理员；向所有用户开放会让每个活跃账户成为沙箱运维人员。主机文件夹 始终仅管理员。
- 后端必须控制配置的 Docker daemon 或 Kubernetes 沙箱命名空间。
- 容器减少文件暴露，但不是虚拟机。
- 没有命名离线政策的任务有网络出站；目的地限制仍由运维人员负责。
- Work 卷没有独立磁盘配额。
- Git 标签仅本地；API 不挂载或接受远程凭据。
- 主机防火墙、daemon 隔离、出站限制和真实卷配额由运维人员强制。
- 远程提供商收到所请求工具结果，一次运行可多次调用。
- 预览端口留在后端 loopback，只通过签名可撤销代理 URL 暴露。
- 标准 Docker Compose 提供 Docker 运行时；
work.enabled=true时 Kubernetes/Helm 提供原生 Pod/PVC 运行时。 - 完整备份需要 Libre WebUI 数据库和 Work 卷。