跳转到主要内容
当智能体在沙箱中运行时,它的 exec 命令会被限制在沙箱环境内。提升权限模式让智能体可以改为跳出沙箱,在沙箱外运行命令,并带有可配置的审批门禁。
提升权限模式只会在智能体处于沙箱隔离状态时改变行为。对于未沙箱隔离的智能体,exec 已经在主机上运行。

指令

使用斜杠命令按会话控制提升权限模式:
指令作用
/elevated on在配置的主机路径上于沙箱外运行,保留审批
/elevated askon 相同(别名)
/elevated full在配置的主机路径上于沙箱外运行,并在模式/主机审批策略已经足够宽松时跳过审批
/elevated off返回受沙箱限制的执行
也可以使用 /elev on|off|ask|full 发送不带参数的 /elevated 可查看当前级别。

工作原理

1

检查可用性

必须在配置中启用提升权限,并且发送者必须在 allowlist 中:
{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        discord: ["user-id-123"],
        whatsapp: ["+15555550123"],
      },
    },
  },
}
2

设置级别

发送仅包含指令的消息来设置会话默认值:
/elevated full
或者内联使用(仅应用于该消息):
/elevated on run the deployment script
3

命令在沙箱外运行

启用提升权限后,exec 调用会离开沙箱。有效主机默认是 gateway,当配置的/会话的 exec 目标为 node 时则为 node。在 full 模式下,如果解析后的 exec 模式/主机审批策略已经完全宽松(security full、 ask off),则会跳过 exec 审批;否则仍会应用正常审批策略。在 on/ask 模式下,始终应用已配置的审批规则。

解析顺序

  1. 消息中的内联指令(仅应用于该消息)
  2. 会话覆盖(通过发送仅包含指令的消息设置)
  3. 全局默认值(配置中的 agents.defaults.elevatedDefault

可用性和 allowlist

  • 全局门禁tools.elevated.enabled(必须为 true
  • 发送者 allowlisttools.elevated.allowFrom,包含按渠道划分的列表
  • 按智能体门禁agents.list[].tools.elevated.enabled(只能进一步限制;全局门禁和按智能体门禁都必须为 true
  • 按智能体 allowlistagents.list[].tools.elevated.allowFrom(发送者必须同时匹配全局 + 按智能体)
  • 渠道提供的回退 allowlist:渠道插件可以选择通过 SDK 适配器钩子提供回退 allowlist,在未配置 tools.elevated.allowFrom.<provider> 时使用。目前没有内置渠道实现此钩子,因此实际使用中,每个提供商现在都需要显式的 tools.elevated.allowFrom.<provider> 条目。
  • 所有门禁都必须通过;否则提升权限会被视为不可用
Allowlist 条目格式:
前缀匹配内容
(无)发送者 ID、E.164 或 From 字段
name:发送者显示名称
username:发送者用户名
tag:发送者标签
id:, from:, e164:显式身份目标

提升权限不控制什么

  • 工具策略:如果 exec 被工具策略拒绝,提升权限无法覆盖它。
  • 主机选择策略:提升权限不会把 auto 变成任意跨主机覆盖。它使用配置的/会话的 exec 目标规则,仅在目标已经是 node 时选择 node
  • /exec 分离/exec 指令会为已授权发送者调整按会话的 exec 默认值(host、security、ask、node),并且不需要提升权限模式。
bash 聊天命令(! 前缀;/bash 别名)是一个独立门禁,除了自己的 tools.bash.enabled 标志外,还要求启用 tools.elevated。禁用提升权限也会锁定 ! shell 命令。

相关

Exec tool

从智能体执行 Shell 命令。

Exec approvals

exec 的审批和 allowlist 系统。

Sandboxing

Gateway 网关级沙箱配置。

Sandbox vs Tool Policy vs Elevated

三个门禁在工具调用期间如何组合。