配置 RAM 角色为智能体沙箱持久化存储挂载授权-智能体沙箱(Agent Sandbox)-阿里云帮助中心

功能介绍

挂载持久化存储时，智能体沙箱（Agent Sandbox）通过扮演 RAM（Resource Access Management，访问控制）角色获取 STS（Security Token Service，安全令牌服务）临时凭证，以访问 OSS、AgenticFS、AgenticBucket 等存储资源，应用无需在挂载配置中提供长期 AccessKey。

RAM 角色需要配置信任策略和权限策略：

策略	作用
信任策略	允许函数计算服务扮演该角色。
权限策略	指定角色可访问的存储资源和允许执行的操作。

创建、查询和删除存储卷（Volume）所需的管理权限，请参见存储卷。

最小权限原则

RAM 角色的权限策略限定可访问的资源和可执行的操作。挂载时，智能体沙箱根据存储类型和挂载配置进一步限制 STS 临时凭证的权限，临时凭证的权限不会超过 RAM 角色的授权范围。实际访问还需满足存储服务自身的授权规则，参见AssumeRole 的 Policy 参数。

只授予业务所需的存储权限。多个 Volume 可共用同一个 RAM 角色，授权范围覆盖这些挂载所需的资源即可，无需按卷或数据路径分别维护策略。生产、测试或不同业务需要独立授权时，应分别配置角色。

操作步骤

步骤一：创建 RAM 角色

登录RAM 控制台，进入身份管理下的角色页面，单击创建角色。
选择信任主体类型为云服务，信任主体名称为函数计算/FC。
输入角色名称，例如 sandbox-storage-role，完成创建。
在角色详情页查看信任策略，确认允许函数计算服务扮演该角色。

信任策略示例（信任主体为函数计算服务）

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "fc.aliyuncs.com"
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

详细操作请参见创建可信实体为阿里云服务的RAM角色和使用函数角色授予函数计算访问其他云服务的权限。

步骤二：授予存储访问权限

在 RAM 控制台的权限策略页面创建自定义策略，选择脚本编辑。
根据下表中对应存储类型的权限配置文档填写策略，将资源范围限定为业务允许访问的存储资源，保存策略。
返回角色详情页，在权限管理中为该角色添加刚创建的权限策略。

存储类型	权限配置文档
OSS	创建 OSS Volume中的权限配置章节。
AgenticFS	创建 AgenticFS Volume中的权限配置章节。
AgenticBucket	创建 AgenticBucket Volume中的权限配置章节。

在同一 Sandbox 中挂载多个需要 RAM 角色的 Volume 时，应将这些挂载所需的存储访问权限授予同一个 RAM 角色，可以使用一份或多份权限策略。

授权完成后，在角色详情页复制角色 ARN（Alibaba Cloud Resource Name，资源名称），用于配置 Volume 或创建 Sandbox。

使用说明

角色选择规则

同一 Sandbox 中的所有存储挂载共用一个 RAM 角色，智能体沙箱不会合并不同角色的权限。创建 Sandbox 时，按以下优先级选择角色：metadata["fc.sandbox.auth.role"] 优先于 Volume 的 mountConfig.role。

配置情况	生效规则
metadata 显式指定角色。	使用 metadata 中指定的 RAM 角色，即使各 Volume 配置了不同的角色。
metadata 未指定角色，至少一个 Volume 配置了角色，且所有已配置的角色 ARN 一致。	使用该角色。未配置角色的 Volume 不参与比较，其挂载也使用该角色。
metadata 未指定角色，多个 Volume 配置了不同的角色 ARN。	Sandbox 创建失败，提示角色配置冲突。
metadata 和所有 Volume 都未指定角色。	挂载需要 RAM 角色的存储时，应先在 metadata 或 Volume 中配置有效角色。

角色按 ARN 比较。即使权限相同，不同 ARN 仍属于不同角色。

重要

不要将 fc.sandbox.auth.role 设置为空字符串。设置为空字符串时，系统不会改用 Volume 中配置的角色，挂载需要 RAM 角色的存储时，Sandbox 会因缺少有效角色而创建失败。需要使用 Volume 中的角色时，请省略该字段。

单个 Volume 与多个 Volume 的角色配置

以下仅展示角色配置字段，将 ARN 中的账号 UID 和角色名称替换为实际值，并按对应的存储卷操作文档补充创建和挂载参数。三种配置方式如下：

单个 Volume：在 Volume 的 mountConfig.role 中指定角色。
多个 Volume 使用同一角色：各 Volume 配置相同的角色 ARN。
多个 Volume 通过 metadata 统一指定：创建 Sandbox 时在 metadata 中指定角色。

单个 Volume

创建 Volume 时，将已授权的角色 ARN 填入 mountConfig.role：

{
  "mountConfig": {
    "role": "acs:ram::<ACCOUNT-UID>:role/sandbox-storage-role"
  }
}

创建 Sandbox 时，通过 volume_mounts 按名称引用该 Volume，省略 metadata["fc.sandbox.auth.role"]，即可使用 Volume 中配置的角色。

多个 Volume 使用同一角色

多个 Volume 需要挂载到同一 Sandbox 时，将它们的 mountConfig.role 设置为同一个角色 ARN，例如 acs:ram::<ACCOUNT-UID>:role/sandbox-storage-role。该角色应具备这些挂载所需的存储访问权限。

创建 Sandbox 时同时引用这些 Volume，无需在 metadata 中重复指定角色。

多个 Volume 通过 metadata 统一指定

多个 Volume 配置了不同角色时，可在创建 Sandbox 的 metadata 中设置 fc.sandbox.auth.role，统一指定本次使用的角色。该角色必须具备所有挂载所需的访问权限。

{
  "metadata": {
    "fc.sandbox.auth.role": "acs:ram::<ACCOUNT-UID>:role/sandbox-storage-role"
  }
}

通过 metadata 指定角色仅对本次创建的 Sandbox 生效，不会修改 Volume 中的角色配置。已有角色满足权限要求时，可直接使用，无需创建新角色。

直接提供挂载配置、未引用 Volume 时，若目标存储需要 RAM 角色，应通过 metadata["fc.sandbox.auth.role"] 指定。

创建后追加挂载

追加挂载继续使用 Sandbox 当前的 RAM 角色，该角色必须具备访问新增存储资源的权限。追加挂载不会改用 Volume 中配置的角色。

如果计划后续追加挂载，应在创建 Sandbox 时配置好 RAM 角色，并提前授予追加挂载所需的存储访问权限：

创建时挂载 Volume：可以使用 Volume 中配置的角色，也可以通过 metadata 指定角色。
创建时不挂载 Volume：通过 metadata 配置角色。

具体操作请参见追加挂载 Volume、追加挂载 OSS、追加挂载 AgenticFS和追加挂载 AgenticBucket。