跳转到主要内容
当你需要云 Sandbox、OCI 镜像、域名出站限制或文件系统快照恢复时,可选择 Modal。应用继续使用相同 Session / Run API;底层镜像构建、资源创建和恢复由控制平面管理。

账户与配置

准备同一 Modal 工作区的 Token ID / Token Secret,账户需要列举、创建、执行、终止 Sandbox 以及相关镜像操作权限。验证只列举 Sandbox,不证明构建和分配权限全部可用。凭据作为 JSON 字符串提交并由控制平面保管,不放入 Agent 环境。 不要为这张表以外的资源字段猜测配置。首次创建可能触发云端镜像构建。下面是本地管理客户端示例;hosted 初始化见自托管。环境变量来自你的私有配置,重复运行会创建额外连接,保存 ID 后复用。
配置或凭据变更需要重新验证、启用。Token 必须属于目标账户与工作区;浏览器当前登录身份不会改变已保存 Token 的归属。

运行内置 Harness 或 OCI Harness

内置路线使用 connection.image 构建环境并增加 Node/npm、curl、git 和 CA。以返回的 connection ID 配合模型连接,按首个 Session执行固定小任务,检查实际回答、文件产物与关闭结果。 OCI 路线通过镜像注册选择固定 digest,Session 使用注册镜像而非 connection.image。可作为历史起点的一条路线是:
  • 镜像:docker.io/nousresearch/hermes-agent@sha256:2fd023efbb8d3d2b0ce1a73d028b07370cff34f567cfe0e999553e8c327ea283。
  • protocol:hermes-v1;command:["/opt/hermes/.venv/bin/hermes"]。
  • 历史组合:Modal、openai-compatible、deepseek-ai/DeepSeek-V4-Flash,Python 和 TypeScript 分别验证继续会话、远程 Tool、环境、产物和清理。
  • 记录日期:2026-11-18,见Harness 交付证据。这不是所有模型端点或后续版本的保证,也不是本轮新执行结果。
私有镜像使用注册时关联的 registry Secret,包含 username/password。镜像拉取凭据与 Modal Token 是不同用途,不能相互替代。 OCI 准备阶段以 root 安装 Python、Node、Bash 等 Runtime 依赖,支持 Alpine / Debian 系包管理器,并清空 Entrypoint / Cmd;Runtime 另行启动注册命令。当前代码将镜像记录的 USER 写回派生镜像,但仓库既有运行说明指出 Modal 实际执行为 root。不能将 USER 声明作为已验证的权限隔离保证;需要依赖执行身份时,应在精确组合中核对实际 uid。源镜像 digest 不代表依赖安装后的整个文件系统未变化。

私有访问与网络策略

连接器将域名 allowlist 映射到 Modal 原生出站限制。按网络策略覆盖任务与凭据通道所需访问,并测试允许和拒绝路径。控制平面访问模型与 Sandbox 直接访问外网属于不同路径。 预览使用服务端 Connect Token Cookie,由 Hexagon 代理处理。应用使用 Hexagon 预览授权,不向浏览器传递 Modal 账户 Token 或私有连接 Cookie。用户服务需要监听正确端口并保持存活。

空闲快照与下一轮

Modal 使用文件系统快照、终止旧 Sandbox、从快照创建新 Sandbox 的策略。Session ID 保持稳定,底层 resource ID 可能变化;应用持久保存 Session ID,不缓存 Provider URL 作为稳定应用入口。 下一次 submit 会触发恢复和 Runtime 准备。文件及受管理对话数据可以延续,任意进程、内存、网络连接不会因此保证延续;预览服务可能需要重新启动。一个 Run 等待授权或审批时仍属活动,不应被当作空闲任务。 快照、恢复有独立持久操作记录。快照结果不确定或恢复响应丢失时保留待对账状态,不能重复创建来猜测上一操作。按空闲与唤醒验证两轮、文件、对话、资源映射与清理;单轮 OCI 成功不证明恢复通过。

关闭与排查

close 终止当前 Session 计算资源并处理其跟踪的快照。共享 Modal App 和通用镜像缓存不是单个 Session 关闭时全部删除的对象。平台关闭结果也不等于 Provider 账户没有其他收费资源。 本页已核对连接器、注册证据和快照清理路径;未重新运行实云任务。历史失败记录不能被后续成功覆盖,精确恢复范围见Harness serverless 矩阵。 依据:Modal 连接器、快照操作、清理生命周期。下一步:OCI Harness、资源对账。

检查一次快照恢复

等待空闲前,记录 Session S、首个 Sandbox A 及 checkpoint 操作。完成 snapshot/recreate 后,重新查询 S 取得当前 Sandbox B,不继续把 A 当作执行目标。第二个 Run 仍属于 S;分别核对文件字节和原生对话身份。即使 B 执行成功,也应保留 snapshot ID,直到其清理得到确认。 使用 SQLite 保存 Harness 历史时,仅检查文件存在尤其不足。11 月 19 日 serverless 记录记录 Modal/OpenClaw 在文件系统恢复后最初出现的文件身份错误,以及限定范围的 copy-up 修复。最初失败仍保留为失败;后续接续通过不代表任意数据库或运行中进程都被保留。应查看矩阵中的精确 Harness/SDK 行,以及文件与原生会话检查。 该快照路径不承诺保留任意镜像的 UID、运行中的 HTTP 进程、活跃 socket 或任意内存。按实际 digest 检查执行身份;确认恢复的工作区和原 invocation 状态后再重建必要服务,不通过盲目启动另一个 Harness 掩盖恢复歧义。 补充依据:Modal 集成说明、镜像契约。下一步:OCI 注册、空闲与唤醒、资源对账。