1. 文档指引简述
AgentVis 可以让 Agent 读写文件、运行命令、调用技能、访问网络，在合适权限下进行浏览器或桌面自动化。沙箱权限用于决定这些操作的边界。
你可以把沙箱权限理解为给 Agent 选择一种工作方式：
- 像本机助手一样工作，但保留审计和危险操作防护。
- 可以联网，但让网络出口尽量经过 AgentVis 的审计链路。
- 在更严格的隔离环境中运行，适合不可信脚本和高风险任务。
沙箱为了让 Agent 高风险操作更可解释、可审计、可恢复。
2. 在哪里设置沙箱权限
- 打开某个 Agent。
- 进入「Agent 设置」。
- 点击顶部「基础」。
- 找到「沙箱权限」。
- 选择「本机审计」「受控联网」或「离线隔离」。
- 点击「保存」。
沙箱权限是按 Agent 配置的。不同 Agent 可以使用不同权限，可根据自身需求进行配置。
3. 三种沙箱权限怎么选
| 模式 | 适合什么时候用 | 你需要知道的边界 |
|---|---|---|
| 本机审计 | 日常办公任务、本地项目开发、需要使用本机文件和桌面能力 | 默认阻断危险命令、保护路径、危险脚本扫描、软删除和审计 |
| 受控联网 | 需要兼顾网络安全的任务，访问网页、GitHub、云 API、邮件、联网技能 | 重点是网络出口审计，非完整虚拟机隔离；普通任务仍可复用本机文件和凭据缓存 |
| 离线隔离 | 不可信第三方技能、高风险脚本、只处理本地工作区文件 | 禁网，限制文件边界，禁止桌面控制、截图、热键和外部 GUI 启动 |
如果不确定，建议这样选：
- 默认日常使用：选「本机审计」。
- 日常使用但希望联网任务更安全：选「受控联网」。
- 不信任脚本或技能来源：选「离线隔离」。
- 任务被阻断时：先看「安全审计」，再决定是否调整权限。
4. 本机审计模式
「本机审计」是最适合日常工作的默认模式。Agent 可以像本机助手一样操作文件、联网、运行命令、使用常见开发工具和桌面能力。
它适合：
- 处理日常办公任务。
- 在本地项目里读写代码。
- 运行测试、构建、脚本。
- 打开浏览器或进行桌面自动化。
- 使用本机已有 CLI、配置和缓存。
但它不是无限制模式。AgentVis 仍会保留多层防护：
- 危险命令检查并阻断。
- 系统保护路径和自定义保护目录拦截。
- 删除类操作走 Trash Bin 软删除。
- 可疑脚本执行前扫描。
- 关键执行事件写入审计。
如果你信任当前 Agent 和任务来源，本机审计通常体验最好。
5. 受控联网模式
「受控联网」适合需要访问外部网络，但又希望网络行为可审计的任务。
它适合：
- 处理日常办公任务。
- 调用云 API 或第三方 HTTP(S) 服务。
- 使用需要联网的 Script 技能。
- 使用 AgentVis 专用浏览器自动化能力访问网页。
你需要知道：
- 受控联网重点控制网络出口，而不是把整个本机文件系统隔离起来。
- HTTP(S) 流量会优先经过 AgentVis 的 broker/proxy 审计路径。
- Script 技能可以声明 broker-only，让脚本必须通过 AgentVis broker 代发请求。
- 非 HTTP(S) 直连需要更明确的目标和授权。
- 当前普通
exec/ Guide 技能不宣称所有直连都已被 OS 层完整捕获。
受控联网主要能防什么
受控联网不是简单地“允许联网”，而是把常见高风险网络行为变成可阻断、可确认、可审计的动作。
| 风险场景 | AgentVis 的处理方式 |
|---|---|
| 绕过代理联网 | 识别 NO_PROXY=*、curl --noproxy、清空代理、direct proxy、raw socket 等高置信绕过信号，并在执行前阻断。 |
| 访问本机、内网或云 metadata | broker/proxy 会拒绝 localhost、private、link-local、metadata 等目标；对编码在 hostname 里的内网或 metadata 地址也会做识别。 |
| 非 HTTP(S) 直连 | 不会给粗放放行。需要协议、主机、端口和来源足够明确后，才会进入 direct-audit 授权流程。 |
| 上传本地文件 | 对明确上传本地文件的命令触发一次性确认，确认只对本次重试生效。 |
| 敏感外传 | 对“读取 .env、环境变量等敏感来源，并把内容放入网络 body”的高置信组合触发确认。 |
| 远端破坏 | 对删除远端仓库、销毁云资源、删库、清空远端存储等高风险操作触发确认，真实账号和真实资源上默认建议取消。 |
| 凭据泄漏 | broker-managed credential 不进入命令行、环境变量、日志或 observation，并按 HTTPS 和精确 host 白名单注入。 |
| 任务失败难排查 | 安全审计会记录 reason code、目标主机、来源和防护模式，帮助判断是代理绕过、目标风险、授权缺失还是运行环境差异。 |
边界提示：受控联网不是完整虚拟机、全协议透明代理或泛化 DLP。它重点收口网络出口和高置信风险动作，不会把默认模式描述成全协议硬隔离。
如果任务提示代理绕过、上传、敏感外传或远端破坏被阻断，请先进入安全审计查看原因，不要直接切换到更宽松模式。
6. 离线隔离模式
「离线隔离」是最严格的常用模式，适合你不完全信任任务或技能时使用。
它适合：
- 第一次运行第三方不可信技能。
- 处理来源不明的脚本。
- 只需要读写当前工作区文件，不需要联网。
- 希望最大限度降低脚本访问本机环境的风险。
离线隔离会带来这些限制：
- 禁止联网。
- 文件访问限制在工作区和应用托管目录范围内。
- 禁止桌面控制、截图、热键、窗口激活。
- 禁止启动外部 GUI / detached 应用。
- 某些依赖本机 Home、AppData、CLI token cache 的技能可能无法正常工作。
如果任务确实需要网络或桌面能力，离线隔离可能不是合适模式。
7. 安全审计页面怎么看
打开 AgentVis，进入「设置」，点击左侧「安全审计」。安全审计页面用于查看最近的沙箱、broker/proxy 和网络防护事件。
7.1 顶部统计
- 最近事件：最近记录的安全相关事件总量。
- 审计：记录但不一定阻断的事件。
- 阻断：系统已经阻止执行的风险动作。
- 诊断：用于说明代理、broker、网络路径或运行环境状态的辅助信息。
诊断不一定代表任务失败。有些诊断只是告诉你“这次没有实际发出 broker 请求”或“可能命中了缓存”。
7.2 筛选器
你可以按这些条件筛选：
- 决策：查看全部、审计、阻断或诊断。
- 后端：例如 Broker、Sandbox、命令校验等来源。
- 来源：事件来自命令、技能、工具还是其他执行链路。
- 原因：按具体 reason code 查找。
- 防护模式：按本机审计、受控联网、离线隔离筛选。
- 目标主机：排查某个域名或地址的网络事件。
- Subject ID：按命令或 Skill ID 定位相关记录。
7.3 如何读一条事件
一条审计事件通常需要看这些信息：标签、标题、时间、来源、模式、原因和目标。如果你只是想解决“为什么任务失败”，优先看阻断事件。如果你在排查网络是否按预期走代理，再看诊断事件。
8. 常见阻断和处理方式
8.1 任务无法联网
- 检查当前 Agent 是否使用「离线隔离」。
- 检查是否是 Script 技能声明了禁网。
- 检查是否有代理绕过信号被阻断。
- 检查是否访问了 localhost、内网、metadata 等高风险目标。
- 判断是否需要切换到「受控联网」。
8.2 浏览器或桌面控制失败
- 检查当前 Agent 是否使用「离线隔离」。
- 检查当前 Agent 是否使用「受控联网」但任务需要通用桌面控制。
- 检查技能是否声明了桌面控制能力。
- 如果只是浏览网页，优先使用 AgentVis 专用的`agent-browser`浏览器自动化技能。
一般来说，任意桌面控制更适合「本机审计」。受控联网只对专用浏览器自动化能力开窄口。
8.3 第三方技能访问不到文件
- 检查当前 Agent 是否使用「离线隔离」。
- 检查文件是否位于当前工作区或应用允许的目录内。
- 检查 Script 技能是否声明了本次需要访问的文件或目录参数。
- 判断是否可以把任务文件移动到当前工作区后重试。
8.4 联网命令被提示代理绕过
受控联网会阻断一些明确绕过代理的行为，例如：
- 清空
HTTP_PROXY/HTTPS_PROXY。 - 设置
NO_PROXY=*。 - 使用
curl --noproxy。 - 使用 raw socket、SSH、FTP、数据库直连等非 HTTP(S) 网络能力。
- 浏览器启动参数中指定 direct proxy。
如果只是普通 HTTP(S) 请求，移除绕过代理参数后重试。如果确实需要非 HTTP(S) 直连，按界面提示进行明确目标授权。如果目标是内网、localhost 或 metadata 地址，要谨慎处理。
8.5 上传、敏感外传或远端破坏被确认拦截
| 风险类型 | 例子 | 建议 |
|---|---|---|
| 文件上传 | curl -F file=@...、上传本地文件 |
只有确认目标可信时才允许本次 |
| 敏感外传 | 读取 .env 或环境变量后发送到网络 body |
默认取消，除非你明确知道内容和目标 |
| 远端破坏 | 删除远端仓库、云资源、数据库 | 默认取消，真实账号和真实资源上尤其谨慎 |
确认只对本次重试生效，不会变成长期授权。
9. 技能和沙箱的关系
技能运行时也会受到当前 Agent 沙箱权限影响。
9.1 Guide 技能
Guide 技能主要是给 Agent 的能力说明。它通常跟随当前 Agent 的沙箱权限工作。
- 在本机审计下，Guide 技能可以引导 Agent 使用本机命令或文件能力。
- 在受控联网下，Guide 技能的 HTTP(S) 联网行为会优先进入 broker/proxy 审计路径。
- 在离线隔离下，Guide 技能不能依赖外网或通用桌面控制。
9.2 Script 技能
Script 技能可以在技能定义中声明更明确的执行要求，例如需要哪些参数、是否需要联网、是否要求 broker-only 网络出口、是否需要文件系统授权、是否需要桌面控制。
如果 Script 技能声明的能力和当前沙箱权限冲突，AgentVis 会优先保护用户安全，可能阻断执行或返回诊断。
- 一个需要联网的 Script 技能在离线隔离下可能失败。
- 一个声明桌面控制的 Script 技能在受控联网或离线隔离下可能被阻断。
- 一个 broker-only 技能如果 broker helper 不可用，会 fail closed，不会回退为直连。
10. 轻量技术说明
这一节面向希望理解机制边界的用户。日常使用可以跳过。
10.1 AgentVis 的防护不是只有一层
一次命令或技能执行大致会经过：
- Agent 规划和提示词约束或自定义Safety Footer锚定安全规则。
- TypeScript 工具层检查，例如路径边界、风险等级、用户确认。
- Rust 命令校验，例如危险命令、保护路径、脚本扫描。
- 进程和网络沙箱，例如 Job Object、AppContainer、broker/proxy、direct-audit。
- Trash Bin 软删除和审计记录。
10.2 受控联网不等于完整虚拟机
受控联网的主旨是可控且实用，并非无条件阻断Agent所有联网行为，日常安全任务行为不误拦，让网络出口更可控、更可审计，而不是把 Agent 放进一个完整虚拟机。当前语义可以概括为：
- 普通 HTTP(S) 尽量走 broker/proxy。
- Script
brokerOnly可以进入更强的代发请求路径。 - 非 HTTP(S) 直连需要更明确的目标和授权。
- 不默认承诺全协议透明代理、TUN、SOCKS 或完整 OS 层网络劫持。
- 不做泛化 DLP，不检查文件内容，只对高置信上传、敏感外传和远端破坏做确认。
10.3 离线隔离更像安全工作间
离线隔离会尽量把任务限制在工作区和应用托管目录内，并硬禁网。它更适合“先安全地试运行”，但不适合所有任务。
如果一个技能需要读取你本机已有 CLI token、浏览器配置、云服务缓存或联网 API，离线隔离可能会让它无法正常工作。
10.4 本机审计仍然有保护
本机审计不是“关闭沙箱”。它仍会保留命令防护、路径保护、脚本扫描、Trash Bin 和审计，只是文件和网络边界更贴近日常本机助手体验。
11. 常见使用建议
| 场景 | 推荐模式 |
|---|---|
| 日常办公，调研分析 | 本机审计/受控联网 |
| 修改本地项目代码、运行测试 | 本机审计 |
| 生成网页、启动本地预览服务 | 本机审计 |
| 运行新安装的未知技能 | 离线隔离或受控联网 |
| 处理不可信脚本、处理工作区文件任务 | 离线隔离 |
| 使用浏览器自动化访问网页 | 本机审计，或受控联网下的专用浏览器能力 |
| 需要上传文件到外部服务 | 受控联网，并确认目标可信 |
| 远端删除、销毁、删库等操作 | 受控联网默认取消确认 |
12. 推荐配置清单
日常使用前可以快速确认：
- 当前 Agent 的沙箱权限符合任务风险。
- 不可信技能优先使用更严格模式试运行。
- 需要联网的任务不要使用离线隔离。
- 需要桌面控制的任务优先使用本机审计。
- 任务被阻断后先查看「设置 -> 安全审计」。
- 对上传、敏感外传、远端破坏确认保持谨慎。
- 不要为了让任务继续而盲目切换到更宽松模式。