openai-agents-python 沙箱 R2 远程存储挂载实战:R2Mount 配置、rclone 策略与凭据安全
openai-agents-python 沙箱 R2 远程存储挂载实战:R2Mount 配置、rclone 策略与凭据安全
导读
R2Mount 是 openai-agents-python 沙箱(sandbox)体系中用于把 Cloudflare R2 对象存储桶挂载进 Agent 工作区的官方挂载条目。它面向"Agent 需要直接读写云端数据"的场景,例如让沙箱内的代码助手读取 R2 上的数据目录、把输出回写到 R2 桶。读完本文,你将掌握 R2Mount 的字段含义、两种挂载策略(容器内 rclone 与 Docker volume driver)的底层工作原理、rclone 配置的自动生成细节,以及凭据校验与安全边界的使用前提。
本文对应的官方参考文档为 docs/ref/sandbox/entries/mounts/providers/r2.md,其内容由 mkdocstrings 从 r2.py 自动提取,因此本文将以源码实现为主线展开。
R2Mount:一个面向 Cloudflare R2 的配置化挂载条目
R2Mount 定义在 src/agents/sandbox/entries/mounts/providers/r2.py,类型标识为 "r2_mount"。它继承自 providers/base.py 中的 _ConfiguredMount——这是一个"用同一模型同时驱动两种挂载策略形状"的抽象基类:既能生成容器内(in-container)rclone 运行时配置,也能生成 Docker volume driver 的驱动参数。
字段一览
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type |
Literal["r2_mount"] |
"r2_mount" |
挂载条目标识,由 Pydantic 判别字段使用 |
bucket |
str |
必填 | 要挂载的 R2 桶名称,同时充当 rclone 的 remote path |
account_id |
str |
必填 | Cloudflare 账号 ID,用于拼接默认 endpoint |
access_key_id |
str | None |
None |
R2 S3 API 访问密钥 ID |
secret_access_key |
str | None |
None |
R2 S3 API 密钥 |
custom_domain |
str | None |
None |
自定义 endpoint 域名,覆盖默认的 https://{account_id}.r2.cloudflarestorage.com |
此外,Mount 基类(src/agents/sandbox/entries/mounts/base.py)还为所有挂载条目提供了公共字段:
mount_path: Path | None:显式指定挂载到工作区的路径;不指定时由会话按条目 key 解析;read_only: bool:默认True,只读挂载;is_dir: bool:默认True;ephemeral: bool:默认True,挂载被视为运行时附加的外部文件系统,不进入工作区快照的持久化范围;mount_strategy:必须显式指定挂载策略(见下一节)。
需要特别注意的是,Mount.model_post_init 会校验 permissions 并发出告警:挂载级别的权限设置不会被强制生效,源码明确提示"请在云厂商侧配置访问权限,mount 级权限不可靠"(base.py),因此 R2 桶的读写权限应通过 Cloudflare R2 的桶策略与 Token 权限来控制。
凭据成对校验
_validate_credential_pair()(r2.py)强制 access_key_id 与 secret_access_key 要么同时提供、要么同时省略,否则抛出 MountConfigError:
r2 credentials must include both access_key_id and secret_access_key
该校验在容器内挂载配置构建与 Docker volume driver 配置构建两条路径上都会被调用,因此无论采用哪种策略都会生效。
挂载策略:容器内 rclone 与 Docker rclone volume
R2Mount 声明了自己支持的策略能力(r2.py):
def supported_in_container_patterns(self) -> tuple[builtins.type[MountPattern], ...]:
return (RcloneMountPattern,)
def supported_docker_volume_drivers(self) -> frozenset[str]:
return frozenset({"rclone"})
这决定了 R2 只有两种可行策略,且都以 rclone 为执行引擎:
- 容器内挂载(
InContainerMountStrategy(pattern=RcloneMountPattern(...))):在沙箱镜像里运行 rclone 命令完成挂载,这也是最通用的方式。按官方文档 docs/sandbox/clients.md 的说明,RcloneMountPattern同时支持 S3、GCS、R2、Azure Blob 与 Box,并可在fuse或nfs两种模式下运行。 - Docker volume 挂载(
DockerVolumeMountStrategy(driver="rclone")):容器启动前由 Docker 的 rclone volume driver 挂载,仅适用于 Docker 后端。
若策略与挂载类型不匹配(例如给 R2Mount 配了 MountpointMountPattern),适配器会在校验阶段抛出 MountConfigError: invalid mount_pattern type——这一点有测试用例直接验证(tests/sandbox/test_mounts.py)。
容器内策略:rclone 配置如何生成
在容器内策略下,R2Mount.build_in_container_mount_config() 调用基类的 _build_rclone_config()(base.py),产出 RcloneMountConfig(定义于 patterns.py),其中包含 remote_name、remote_path、remote_kind(固定为 "r2")、config_text 与 read_only。
_rclone_required_lines()(r2.py)负责生成 R2 专属的 rclone 配置片段:
[<remote_name>]
type = s3
provider = Cloudflare
endpoint = https://<account_id>.r2.cloudflarestorage.com # 或 custom_domain
acl = private
env_auth = false
access_key_id = <access_key_id> # 仅当提供成对凭据时出现
secret_access_key = <secret_access_key>
关键点:
- R2 走的是 S3 兼容协议,因此 rclone 侧
type = s3+provider = Cloudflare; endpoint默认由account_id推导为https://{account_id}.r2.cloudflarestorage.com,提供custom_domain时则完全替换(测试用例见 test_mounts.py);acl = private固定私有访问;- 无论是否提供凭据都会写入
env_auth = false;只有凭据成对提供时才写入access_key_id/secret_access_key。也就是说,R2 也支持无凭据(credentialless)挂载,此时依赖沙箱运行时的环境凭据——官方文档 docs/sandbox/clients.md 明确 credentialless 的 rclone 挂载限定为 S3、GCS、R2 与 Azure Blob 四种。
若 RcloneMountPattern 指定了 config_file_path(一个存在于沙箱工作区内的 rclone 配置文件),SDK 会先读取该文件中与 remote 同名的 <a href="https://link.gitcode.com/i/4199924908689509b77532a2194a3033" target="_blank">section],再用上述必填行做合并补充(_supplement_rclone_config_text,[patterns.py):保留原 section 已有内容,把 R2 的必填行追加进该 section。合并行为同样有单测覆盖(test_mounts.py)。
remote name 的确定性解析
RcloneMountPattern.resolve_remote_name()(patterns.py)决定 remote 标识:
- 若 pattern 显式设置了
remote_name,直接使用; - 否则生成按会话确定的名字
sandbox_r2_{session_id_hex},这样多个挂载可共存而不互相污染 rclone 配置 section。注意这里要求会话必须有session_id(uuid.UUID),否则抛MountConfigError。
挂载执行与卸载
RcloneMountPattern.apply()(patterns.py)的完整流程:
- 在沙箱内检查
rclone是否可用(command -v rclone || test -x /usr/local/bin/rclone),缺失则抛MountToolMissingError; - 在工作区内创建隔离配置文件
.sandbox-rclone-config/{session_id_hex}/{remote_name}.conf,并写入配置文本;写入后执行chmod 0600(见_write_sensitive_config_file,patterns.py),防止同容器其他用户读取凭据; - 注册该目录为"持久化跳过路径",避免快照时把临时凭据写进工作区状态;
- 按模式执行:
- fuse 模式(默认):
rclone mount <remote>:<bucket> <mount_path> --config <conf> --daemon,只读时追加--read-only,extra_args可透传附加参数; - nfs 模式:先在后台启动
rclone serve nfs --addr <nfs_addr> --config <conf>,再以mount -t nfs挂载本地 NFS 地址(默认127.0.0.1:2049,NFS 挂载选项默认vers=4.1,tcp,soft,timeo=50,retrans=1,最多重试 3 次)。
- fuse 模式(默认):
unapply() 则依次尝试 fusermount3 -u / umount 卸载,并用 pkill -f 'rclone (mount|serve nfs) <remote>:' 清理后台进程。
Docker volume 策略:driver 参数生成
build_docker_volume_driver_config()(r2.py)返回 (driver, options, read_only) 三元组,其中 options 为:
{
"type": "s3",
"path": self.bucket,
"s3-provider": "Cloudflare",
"s3-endpoint": self.custom_domain or f"https://{self.account_id}.r2.cloudflarestorage.com",
}
提供成对凭据时追加 s3-access-key-id 与 s3-secret-access-key;最终选项为 options | strategy.driver_options,允许策略层补充额外 driver 选项。DockerVolumeMountStrategy.activate() 在会话侧是 no-op——真正的挂载由后端在容器启动前完成(base.py),且要求会话后端 supports_docker_volume_mounts(),否则抛 MountConfigError。
生命周期与快照:挂载的挂载/卸载闭环
所有挂载通过 Mount.apply() / Mount.unmount() 进入策略适配器(base.py)。对于容器内策略,InContainerMountAdapter(base.py)实现了四个关键阶段:
activate:构建含配置文本的RcloneMountConfig并执行pattern.apply();deactivate:以include_config_text=False构建仅含 remote 身份的配置,供unapply()做卸载清理;teardown_for_snapshot/restore_after_snapshot:快照前卸载、快照后重挂,保证挂载始终是临时(ephemeral)状态、不进入持久化数据。
InContainerMountStrategy.activate 还会调用 _mount_security.py 的 validate_mount_activation_credential_boundary 做凭据暴露边界校验。官方指南 docs/sandbox/guide.md 指出:会话状态与 RunState 序列化时会剥离云挂载凭据;恢复挂载会话时需要通过 trusted_manifest.with_in_container_mount_credential_exposure_acknowledged("data")(或针对宽泛凭据域的 with_in_container_mount_broad_credential_exposure_acknowledged)显式确认凭据暴露范围。这是使用含内联凭据的容器内 R2 挂载时需要注意的恢复流程。
后端兼容矩阵
官方文档 docs/sandbox/clients.md 给出的后端支持情况:
| 后端 | R2 挂载方式 |
|---|---|
| Docker | InContainerMountStrategy(rclone)或 DockerVolumeMountStrategy(driver="rclone") |
ModalSandboxClient |
ModalCloudBucketMountStrategy + S3Mount / R2Mount(支持内联凭据或命名 Secret) |
CloudflareSandboxClient |
CloudflareBucketMountStrategy + S3Mount / R2Mount |
BlaxelSandboxClient |
BlaxelCloudBucketMountStrategy + S3Mount / R2Mount / GCSMount |
DaytonaSandboxClient |
DaytonaCloudBucketMountStrategy(rclone),支持 S3/GCS/R2/Azure Blob/Box |
E2BSandboxClient |
E2BCloudBucketMountStrategy(rclone),同上 |
RunloopSandboxClient |
RunloopCloudBucketMountStrategy(rclone),同上 |
需要说明的是,各扩展后端的策略类位于 src/agents/extensions/sandbox/ 下,本文不展开其内部实现。
实战示例:把 R2 桶挂进沙箱工作区
仓库中的 examples/sandbox/extensions/cloudflare_runner.py 给出了真实用法——当检测到环境变量 CLOUDFLARE_ACCOUNT_ID 时,将 R2 桶作为 manifest 条目加入:
manifest.entries["cloud-bucket"] = R2Mount(
bucket=native_cloud_bucket_name, # 桶名
account_id=os.environ.get("CLOUDFLARE_ACCOUNT_ID"),
access_key_id=os.environ.get("R2_ACCESS_KEY_ID"),
secret_access_key=os.environ.get("R2_SECRET_ACCESS_KEY"),
mount_path=Path(native_cloud_bucket_mount_path), # 挂载到工作区的位置
read_only=False, # 允许 Agent 写入
mount_strategy=CloudflareBucketMountStrategy(),
)
要点:bucket 与 account_id 为必填;access_key_id/secret_access_key 成对出现;mount_path 决定工作区内的挂载位置;read_only=False 表示允许写入。
测试辅助文件 tests/sandbox/integration_tests/_helpers.py 还展示了最朴素的容器内 rclone 配置方式:
"mounts/r2": R2Mount(
bucket="r2-bucket",
account_id="r2-account-id",
mount_strategy=InContainerMountStrategy(pattern=RcloneMountPattern()),
),
无凭据(credentialless)用法
R2Mount 允许省略密钥对。此时生成的 rclone 配置只包含 env_auth = false,不写密钥行,运行时依赖沙箱环境中的既有凭据(如 Cloudflare Workers 环境注入或挂载策略提供的身份)。这种用法常见于托管后端,因为凭据不需要出现在 manifest 里。
测试验证与错误排查
单元测试覆盖
tests/sandbox/test_mounts.py 围绕 R2Mount 提供了一组高价值回归测试:
- 成对凭据时生成完整 rclone 配置:断言生成的
config_text精确等于type = s3、provider = Cloudflare、默认 endpoint、acl = private、env_auth = false加密钥行的组合; - custom_domain 覆盖默认 endpoint;
- 已有 rclone 配置文件的 section 合并:
[remote]中已有的region = auto行被保留,R2 必填行追加其后,且不影响文件中的其他 section(如[other]); - 拒绝非 rclone 的 mount pattern(
MountpointMountPattern); - 两种策略下都拒绝残缺凭据:只给
access_key_id不给secret_access_key(反之亦然)时,容器内与 Docker volume 两条路径都抛同一错误。
常见报错与原因
| 报错 | 原因与处理 |
|---|---|
r2 credentials must include both access_key_id and secret_access_key |
密钥只提供了一半;补全成对凭据,或全部省略走 credentialless |
invalid mount_pattern type |
InContainerMountStrategy 使用了非 RcloneMountPattern 的 pattern(如 MountpointMountPattern);R2 只支持 rclone |
invalid Docker volume driver |
DockerVolumeMountStrategy 的 driver 不是 "rclone" |
mount session is missing session_id |
会话缺少 uuid.UUID 类型的 session_id,无法派生每会话 remote name |
rclone config missing required remote section |
config_file_path 指向的文件中不存在与 remote 同名的 [section],或文件为空 |
mount tool not found: rclone |
沙箱镜像未安装 rclone,需要选用预装 rclone 的镜像或预置 /usr/local/bin/rclone |
小结
R2Mount 是 openai-agents-python 沙箱体系中接入 Cloudflare R2 的标准入口,其设计核心是"一份字段模型同时驱动容器内 rclone 与 Docker volume 两种策略":容器内策略自动生成按会话隔离的 rclone 配置(S3 兼容协议、Cloudflare provider、默认或自定义 endpoint、acl = private),Docker 策略则生成 rclone volume driver 的 options。凭据必须成对出现,也支持完全省略以依赖环境身份。若你需要为 Agent 接入其他对象存储,可对比参考同目录下的 s3.py、gcs.py、azure_blob.py 与 box.py 实现,它们共享同一套 _ConfiguredMount 基础设施。