# 系统运行环境、服务授权与虚拟机网络

在 **Bot 设置 → 环境与授权** 中由管理员统一配置。Hermes 继续运行主模型和会话；这些设置只决定工具在哪里执行、从哪里取得服务凭据。

| 运行环境 | 执行与授权 |
| --- | --- |
| 不指定 | 可使用获准的 Yaoyao 服务工具、HTTP MCP 和已连接应用；不能运行宿主终端、文件、浏览器或委派工具 |
| 服务器本机 | Hermes 所属节点的原生环境和登录；不注入系统共享变量，不借用 Yaoyao 系统服务凭据 |
| 虚拟环境 | 使用 Bot 已有的虚拟机归属；`computer_*` 在虚拟环境执行，脚本获得获准的系统变量和临时授权文件 |

每轮绑定环境版本。更改环境从下一轮生效，并重新建立 Hermes 会话，避免沿用旧环境上下文。现有安装迁移为服务器本机；新安装默认不指定。新版工具桥声明 `execution_policy_version: 1`；旧桥或旧 Runner 不能接受受限环境的任务。

环境限制在工具桥调用前执行；未识别的原生工具同样被拒绝，不能通过审批放行或委派绕过。Skill 发现和阅读继续可用，脚本必须走当前执行环境。受限环境不启动宿主 stdio MCP，也不在宿主后台维护 Skill。外接电脑、云电脑和独立托管浏览器的能力开关不覆盖系统选择。

服务器模式的原生工具跟随 Hermes 节点。Yaoyao 的服务器桌面桥只在默认 Hermes 使用回环地址直连时挂载，并要求原有桌面授权；远程 Hermes 不会借用 Yaoyao 主机桌面。文件工具中的 `local` 别名也固定指向该服务器，不解析为消息来源设备。

## 系统变量与授权

配置使用现有服务器加密密钥密封保存到系统空间；管理接口只回显名称、用途、变量名和 Bot 授权列表。新增 Bot 没有默认使用权限。账号级已连接应用保持原有归属，不自动升级为全系统共享凭据。

支持三类系统资源：

- **环境变量**：JSON 字符串映射，按资源授予 Bot。保留运行时内部变量、进程加载选项、HOME/PATH 和网络代理变量，防止覆盖执行边界。同一 Bot 的变量名不能重复。
- **API 服务**：管理员指定 HTTPS 根地址、Bearer 令牌，以及可选的脚本变量名。适用于服务本身发行的模型或生图 API 密钥；`yaoyao_service_request` 只接受该根路径下的请求，不跟随重定向。具体请求格式由 Skill 指定。返回体上限 8 MiB，超大的图像响应应通过虚拟机 SDK 写入文件再导出。
- **Codex CLI 登录**：显式导入 `auth.json`，仅在虚拟机命令期间生成临时 `CODEX_HOME`；CLI 必须已安装。登录文件采用临时副本，CLI 的续期结果不回写全系统授权；到期后由管理员重新导入。它不会被解释为通用生图 API 密钥。Grok Bot 云登录同样不能直接当作 xAI API 密钥。

普通接口、模型提示和工具参数不含凭据。Runner 在任务授权有效时通过专用接口读取任务环境；值不写入命令队列或全局进程环境。命令通过 stdin 收到变量和文件，临时文件结束后清理，常见输出中的凭据值被隐藏。授权变更或撤销使旧任务后续调用失效。

共享虚拟机内的程序属于同一个操作系统用户。为避免把一个 Bot 的凭据暴露给未获授权的同机成员，注入脚本变量前会检查共享成员均获准使用相应资源；否则应选择独立环境或使用后端服务工具。

## 虚拟机代理

启用后，所有受管虚拟环境使用独立网络网关的命名空间。网关只有 `lo` 与 `tun0`，没有可以直连公网的网卡；桌面容器没有 `NET_ADMIN` 权限。`tun2socks` 将所有 TCP 转交给 Runner 的受控连接代理，支持 HTTP CONNECT 和 SOCKS5 上游认证。上游密码留在 Runner 内存，不放进桌面或网关镜像。

DNS 在虚拟机内映射为临时地址，连接时还原域名；Runner 经同一上游代理查询 DNS over HTTPS，并检查实际目标地址。继续限制为公网 80/443，拒绝内网、宿主、元数据地址以及其他端口。UDP/QUIC、IPv6 直接出口不开放；无法代理的流量不会改为直连。关闭代理保留原有网络行为：动态环境使用原来的受控应用代理，旧 Compose 环境保持断网。

修改代理先关闭旧通道并结束相关虚拟机工具任务，之后使用新配置。节点状态区分离线、旧版本、待更新、未生效与已同步，并提示缺少网络网关等具体原因；已同步后仍会在实例启动时检查出口隔离。代理测试从执行节点发起，先检查网络网关，再测试已保存的代理连接，不代表某个服务的账号授权有效。服务器本机命令、Hermes 模型请求、托管浏览器及 Yaoyao 后端代发的 HTTP 服务/MCP 请求使用各自的网络配置。

### 更新部署

1. 更新 Web、Runner 和 Hermes 工具桥。工具桥改动需要重新加载 Hermes，不能只复制文件。
2. 动态 Docker/Podman：重新准备一次虚拟机镜像，会同时构建 `localhost/yaoyao/network:1`。需容器运行时支持 `/dev/net/tun` 和隔离网关的 `NET_ADMIN`；业务容器不会获得它们。
3. Compose：使用重新生成的 `compose.desktops.yaml` 或 `compose.desktops.cursor.yaml` 构建并更新部署。每个桌面新增一个网络网关和独立 IPC 卷，Web 只读挂载该卷；桌面不挂载网关 IPC。自定义清单须增加 `networkSocketPath`，缺失时明确拒绝启用。
4. 在设置页保存代理并测试。旧实例的工作目录保留，网络模式变化由现有资源池在释放后重建容器。

网关基于 [tun2socks 官方 Linux 配置](https://github.com/xjasonlyu/tun2socks/wiki/Examples)，固定使用 v2.6.0 源码构建；与示例不同，本实现没有备用直连网卡。

## 接口与验证

管理员接口前缀 `/api/app/admin/execution`：`GET /`、`PUT /environment`、`PUT /proxy`、`POST /proxy/test`，以及 `/resources` 的新增、按 ID 更新和删除。更新使用配置版本防止覆盖并发编辑；密钥字段省略表示保留，代理密码传空字符串表示清除。

Runner 新增 `execution-context-v1` 和 `vm-egress-v1` 能力、仅机器认证可访问的任务环境/网络配置接口，以及 `network.configure`、`network.test` 指令。任务上下文回调仍绑定原连接、Bot、账号和本轮授权。

自动测试覆盖管理员边界、环境来源、迁移、加密存储、Bot 授权撤销与共享成员检查、服务请求范围、命令临时文件清理、HTTP/SOCKS5 握手与经代理的 TLS DNS 请求、代理并发切换与失效连接回收、强制工具限制、表单行为；`tests/live/managedNetwork.live.test.ts` 使用真实 Docker 验证无代理变量的 TCP 程序、DNS、代理故障无直连、业务 root 无网络管理权以及资源清理。