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

在 **Bot 设置 → 环境与授权** 中由管理员统一配置。Hermes 继续运行主模型和会话。默认运行环境决定未指定目标时的执行位置；各环境开关与设备、Bot 授权独立决定可用能力，可以同时允许多个环境。

| 默认运行环境 | 未指定目标时的行为 |
| --- | --- |
| 不指定 | 按任务选择已允许的环境；目标不明确时澄清 |
| 服务器本机 | 优先在 Hermes 所属节点执行；虚拟机、其他电脑和浏览器仍可按授权使用 |
| 虚拟环境 | 脚本优先通过 `computer_*` 在 Bot 对应的虚拟机中执行；其他已允许的环境仍可使用 |

用户明确指定的目标优先于默认值。托管浏览器已开启且可用时，未指定浏览器或设备的“打开网页”“打开百度”“用浏览器”默认使用托管浏览器，也优先于默认运行环境；明确指定其他浏览器、使用该环境已有登录或继续操作已指定页面时沿用相应目标。未开放、未授权、离线及人工接管仍分别校验，不能借默认值绕过。

每轮绑定默认环境版本，更改从下一轮生效。旧版将默认环境当成独占限制的会话首次进入新逻辑时重建，保留对话记录，清除遗留的环境限制；后续正常复用。现有安装仍默认服务器本机，新安装不指定，但这些默认值不再关闭其他环境。原生工具和 Skill 沿用 Hermes Profile 已开放的权限，已授权 MCP（包括 stdio）与已连接应用不因默认位置被排除。

原生工具始终跟随 Hermes 节点。Yaoyao 的服务器桌面桥只在默认 Hermes 使用回环地址直连时挂载，并要求原有桌面授权；远程 Hermes 不会借用 Yaoyao 主机桌面。`server` 明确指服务器，`local`／“本机”及省略目标仍按本轮消息来源电脑解析；未知来源不能猜测。已授权电脑之间及电脑与虚拟机之间可显式传文件。

## 系统变量与授权

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

资源授权不依赖默认运行环境。API 服务通过获准的服务工具使用；系统变量和临时登录文件只在实际调用虚拟机脚本时注入，不注入 Hermes 或桌面宿主进程，也不自动复制其他设备的登录态。在服务器执行的原生工具继续使用该节点的原有配置和登录。

支持三类系统资源：

- **环境变量**：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 无网络管理权以及资源清理。