第11章 Omnigent 第11章：云沙箱主机详解

Cloud Sandbox Host

云沙箱主机将 Omnigent 运行器从你的笔记本电脑迁移到远程容器中。即使你关闭笔记本电脑，智能体依然能在拥有云算力的隔离环境中持续工作。

如果你希望限制智能体在文件系统和网络上的访问权限，可以看看 Omnibox。

| | 本地运行器 | 云沙箱主机 | | :--- | :--- | :--- | | 可用性 | 关闭笔记本即停止 | 独立运行 | | 算力 | 你的 CPU 和内存 | 云算力 | | 环境 | 本地文件 | 隔离且可复现 | | 适用场景 | 交互式工作 | 长时任务 |

Omnigent 目前支持 Modal、Daytona、Blaxel、Islo、Gensee、NVIDIA OpenShell 和 Boxlite 作为云沙箱主机。

下方的托管平台对比涵盖了 Modal、Daytona、Blaxel 和 Islo。OpenShell 连接到你选定的网关；Boxlite 可以使用本地 micro-VM 运行时或远程 boxlite serve 池。Gensee 仅提供托管主机服务：其控制平面通过 HTTPS 启动主机，因此只支持服务器托管流程，不支持 CLI 引导命令。

| | Modal | Daytona | Blaxel | Islo | | :--- | :--- | :--- | :--- | :--- | | 运行器寿命 | 24 小时（平台上限） | 无上限（直到删除） | 默认 24h 最大龄（可通过 ttl 调整） | 无上限（托管模式下闲置 15 分钟自动暂停） | | 凭据注入 | 命名密钥（Modal 密钥存储） | 从服务器复制环境变量 | 从服务器复制环境变量 | 从服务器/网关配置文件复制环境变量 | | 免费额度出口流量 | 全量出口 | 全量出口 | 仅限白名单域名 | 全出口，网关配置文件控制出口 |

服务器托管（推荐）

配置一次服务器，团队成员即可从 Web UI 启动云沙箱主机。

1. 安装

pip install 'omnigent[modal]' # 适用于 Modal pip install 'omnigent[daytona]' # 适用于 Daytona pip install 'omnigent[blaxel]' # 适用于 Blaxel pip install 'omnigent[islo]' # 适用于 Islo pip install 'omnigent[openshell]' # 适用于 OpenShell pip install 'omnigent[boxlite]' # 适用于 Boxlite

Gensee 无需额外安装：它通过 HTTPS 与 Gensee 控制平面通信，且不安装 Omnigent 内的提供商 SDK。

Islo 启动器使用 Islo Python SDK，该 SDK 包含在 omnigent[islo] 附加包中并采用延迟导入，因此仅 Islo 提供商用户需要安装。omnigent[blaxel] 附加包同样以延迟导入方式提供 Blaxel Python SDK。若要从 CLI 启动 Blaxel 沙箱，还需安装 Blaxel CLI (brew tap blaxel-ai/blaxel && brew install blaxel)。

2. 设置提供商凭据

Modal：运行 modal setup 进行身份验证，或在服务器上设置 MODAL_TOKEN_ID 和 MODAL_TOKEN_SECRET。

Daytona：在 Daytona 仪表盘中创建 API 密钥（Dashboard > Keys）并设置在服务器上： export DAYTONA_API_KEY=dtn_…

Islo：使用 Islo CLI 创建 API 密钥（islo login，然后 islo api-key create omnigent --show）并设置在服务器上。SDK 会用密钥交换短期会话令牌并自动刷新，因此 API 密钥是唯一的必需运行时凭据： export ISLO_API_KEY=islo_key_…

Blaxel：使用 Blaxel CLI 登录到你的工作区 (bl login your-workspace)，或为无交互进程在服务器上设置控制凭据： export BL_WORKSPACE=your-workspace export BL_API_KEY=your-api-key

OpenShell：使用 openshell gateway select 选择网关，或在服务器上设置 OPENSHELL_GATEWAY。启动器使用该网关连接，不需要单独的 API 密钥。

Gensee：在服务器上设置由 sandbox.gensee.api_token_env 命名的 API 令牌变量（默认为 GENSEE_CONTROLLER_API_TOKEN）。Gensee 目前仅为签约组织配置端点和令牌；请将该令牌保存在服务器进程环境中，而非 config.yaml。 export GENSEE_CONTROLLER_API_TOKEN=…

Boxlite：本地模式需要 Linux 上的 KVM，且无需提供商凭据。对于远程 boxlite serve 池，需在服务器上设置 BOXLITE_API_KEY，并在 Boxlite 设置中配置池端点。

提供商控制凭据保留在启动进程中，绝不进入沙箱。Web 用户登录的是 Omnigent，而非沙箱提供商。

3. 配置提供商

在你的服务器配置 YAML（笔记本上是 ~/.omnigent/config.yaml，Docker 中是 /data/config.yaml）中添加 sandbox 部分。典型的 Modal 配置如下： sandbox: provider: modal server_url: https://your-server.example.com modal: image: ghcr.io/omnigent-ai/omnigent-host:latest # 可选，默认使用官方镜像 secrets: [omnigent-llm] # 包含 LLM API 密钥的 Modal 密钥

关于顶级字段参见常见设置，提供商块参见 Modal 设置，host_config 参见主机配置。完整的云沙箱配置参考还涵盖了其他提供商和生命周期设置。

4. 从 Web UI 启动

开始新会话并在主机选择器中选中 New Sandbox。服务器将配置云主机，启动运行器并自动建立连接。

可选地将沙箱指向一个 git 仓库进行克隆。使用 composition 区域的 Repository 控件从已连接的 GitHub 账户选择仓库，或粘贴克隆 URL，并固定分支；留空则创建一个带有服务器创建的工作区的裸沙箱。

仓库在沙箱内克隆，并成为会话的工作目录。管理员可以使用可选的 sandbox.git_clone 块加快这些克隆速度，该块限制了新检出时的历史深度、分支选择和 blob 获取（仅限支持的提供商）。

某些提供商可以将多个仓库克隆到一个沙箱中。当所选提供商支持时，可在 Repository 控件中继续添加条目（最多 10 个仓库）。Omnigent 会并行克隆这些仓库，作为沙箱工作区下的同级目录：单个仓库时智能体在其中启动；多个仓库时智能体在包含它们的父目录启动。如果两个仓库落入同名目录（例如 org-a/api 和 org-b/api），将通过所有者进行区分。多仓库是各提供商的特性——Kubernetes 托管沙箱支持此功能，而单仓库提供商仅接受一个仓库，拒绝多仓库请求。选择器会根据所选提供商调整，仅在该提供商支持时才提供多仓库列表。

直接调用 REST API 时，通过 POST /v1/sessions 在 workspace 中传递单个仓库，或在 workspaces 中传递多个（一个克隆 URL 列表，每个可选附带 #）。两者互斥，workspaces 需要托管会话 (host_type: "managed")，且最多接受 10 个仓库。

5. 在沙箱中运行自动化（可选）

计划任务可以使用相同的启动路径：创建带有 execution_target: managed_sandbox 的任务（或在自动化对话框的主机选择器中选择 New Sandbox），每次触发都会配置一个带有干净工作区的新沙箱。现有的托管沙箱主机不能被固定为自动化的主机，且仅当此服务器配置了托管沙箱提供商时才提供该选项。

自动化的沙箱完全遵循服务器的沙箱配置，就像为聊天启动的一样——自动化不会覆盖超时设置，也不会在运行结束时终止沙箱。根据你的自动化频率和资源预算选择合适的提供商寿命、闲置和清理设置（包括下方的回收器）；仅启用托管沙箱并不保证短停机时间。

CLI

从命令行创建和管理云沙箱主机。支持 CLI 的提供商使用相同的命令；只需切换 --provider 标志： omni sandbox create --provider modal # 或 --provider daytona / blaxel / islo / openshell omni sandbox connect --provider modal \ --sandbox-id --server

Boxlite 和 Gensee 支持服务器托管流程，但不支持这些 CLI 引导命令。

对于 Blaxel CLI 启动，需在创建前将主机或智能体所需的所有凭据列在 OMNIGENT_BLAXEL_SANDBOX_ENV 中。切勿包含 BL_API_KEY 或 BL_CLIENT_CREDENTIALS。由于 Blaxel 不提供本地回调端口转发，沙箱内的浏览器登录会自动跳过。

停止 connect 不会终止沙箱，它仍在运行。当你不再需要时，使用提供商的 CLI 或控制台将其删除。

回收过期沙箱（可选）

默认情况下，托管沙箱在其会话被删除前一直存在（或由提供商自身的寿命上限回收）。若要自动终止主机已离线且持续离线的沙箱，请在 sandbox: 中添加一个可选的回收器块。这是部署范围的设置——配置在提供商（或提供商们）旁边，切勿放在单个提供商条目内部： sandbox: provider: modal server_url: https://your-server.example.com reaper: # 可选；默认禁用 enabled: true # 默认：false terminate_after_offline_days: 30 # 默认：30 天 sweep_interval_s: 86400 # 默认：1 天

enabled — 服务器是否启动回收器循环。默认为 false，因为终止用户算力具有破坏性；需显式开启。

terminate_after_offline_days — 在终止托管主机的当前沙箱代之前，自其最后心跳以来的最少天数。默认为 30。

sweep_interval_s — 完整扫描之间的秒数。默认为 86400（一天）。

terminate_after_offline_days 和 sweep_interval_s 均必须为正整数。在提供商列表条目内部设置回收器会在启动时拒绝——一个循环覆盖整个部署，并通过记录在待回收托管主机上的提供商分派每次终止。

回收仅分离过期的沙箱代：会话记录和持久主机绑定保留，因此发往该会话的下一条消息可在相同主机身份下启动新沙箱。失败的提供商终止保持待定状态，并在随后的扫描中重试。

回收器需要配置主机存储。如果回收器启用但未配置主机存储，服务器将记录警告且回收器不运行。

社区沙箱提供商

上述提供商随 Omnigent 一起发布。除此之外，服务器在启动时通过插件注册表发现额外的沙箱提供商，因此新的托管平台可以作为单独的包添加，而无需修改核心 Omnigent 包。

已安装提供商的名称在 sandbox.provider 中被接受，其提供商特定的块在服务器启动时若声明了配置模型则会被验证。已配置的社区提供商作为托管启动选项在 Web UI 中提供，因此它们必须实现该生命周期。在服务器的 Python 环境中安装插件并重启以发现它。缺失或被拒绝的插件会使其提供商名称在服务器配置中无效。

配置贡献的提供商

将 sandbox.provider 设置为贡献名称，如果该提供商声明了配置模型，添加匹配的 sandbox.<提供商> 块： sandbox: provider: acme server_url: https://your-server.example.com acme: namespace: sandboxes

服务器启动时，该块根据提供商声明的配置模型进行验证。是否拒绝未知键取决于该模型。未声明配置模型的提供商不接受提供商特定的配置参数。

构建提供商插件

遵循社区沙箱提供商中的实施指南：选择执行模型或提供商控制的启动器，定义经过验证的配置，注册包入口点，并测试托管启动和清理。指南还涵盖了可选的 CLI 引导、恢复和多仓库支持。