权限与安全¶
权限、认证、隔离分别回答:动作可否执行、调用者是谁、进程能访问什么。 三者都需要配置。已认证的 A2A 请求和沙箱都不能替代 Permission Gate(权限门)。
决策顺序¶
工具注册表在分发调用前检查权限门:
- 内置规则拒绝高破坏性命令,例如递归删除根目录或用户主目录。
permissions.tools中的用户规则选择deny、allow或ask。- 未命中规则的调用采用工具的默认权限等级。
- 对于
ask等级,由当前权限模式决定如何处理。
只读工具和已识别的只读本地命令通常默认 allow;修改操作和未知 MCP 工具通常默认 ask。
也有显式默认允许的例外,例如把文件交给请求用户的 deliver_files。用户规则仍优先于
默认值。不要因为工具未出现在配置中,就认为它已被禁止。
模式¶
permissions.mode |
ask-tier 调用的处理 |
|---|---|
ask |
询问交互式用户 |
smart(默认) |
模型审查后允许,或升级给用户 |
full |
不询问,直接执行 |
所有模式都遵守内置拒绝规则和用户配置的 deny。Smart 模型审查不能替代明确的禁止规则。
审查失败或超时会转交用户确认,不会自动批准。没有可用的审批响应端时,需要确认的调用会被拒绝。
raven agent -m 始终没有审批响应端:回复之后会列出所有被拒绝的调用;只要其中有需要确认的调用,
进程以状态码 3 退出,便于无人值守的调用方区分"跳过了修改"与"完成了修改"。没人能回答的提问也会列在回复之后,
但不改变退出状态,因为这一回合是按自己的判断继续的。单次任务确需修改时,
请传入 --permission-mode full。
全局配置决定起始模式;会话可通过会话级 config.set 覆盖,并把模式保存在会话记录中。
排障时应同时检查会话模式与全局值。
配置工具与命令前缀¶
可将以下片段合并进已有配置:
{
"permissions": {
"mode": "ask",
"tools": {
"exec": {
"*": "ask",
"git status *": "allow",
"git diff *": "allow",
"git push *": "deny"
},
"write_file": "ask",
"edit_file": "ask",
"a2a_send": "ask"
}
}
}
只有 exec 使用命令前缀表,其他项按工具名配置权限等级;不能用它配置任意文件路径的访问控制。
示例禁止普通的直接 git push,并不能阻止 Shell 程序发布数据的所有可能方式。
Shell 匹配遵循以下规则:
- 具体模式按 token 前缀匹配(
git status *也匹配git status)。多个具体模式 命中时取最严格值:deny > ask > allow,与顺序无关。 - 只有没有具体模式适用时才使用
*。因此* = ask不会阻止具体的git status * = allow生效。 - 复合命令只有每个 segment 都允许才允许;任一 segment 拒绝会拒绝整个调用。
git *不会隐式授权sudo git ...。 - 命令/进程替换、反引号、heredoc 或越界重定向可能导致
allow和ask模式只使用 fallback 规则。这是保守解析,不能证明命令启动的每个程序都安全。 deny模式会先于上述处理,针对命令实际运行的每个程序进行判断:包装命令之后 (sudo、env、bash -c、xargs、doas、watch)、替换内部、shell 关键字之后,或带路径时(/usr/bin/curl)。因此curl * = deny也会拒绝bash -c "curl ..."和curl ... > /tmp/out。程序自己拼出来的命令 (python -c、脚本文件、alias)仍然看不到。
与 OpenCode 的有序规则不同,Raven 不采用最后匹配优先。不要直接粘贴另一产品的
权限 schema 或优先级。除非明确需要宽泛的无人值守执行,否则避免 "*": "allow"。
审批范围¶
| 选择 | 范围 |
|---|---|
| 允许一次 | 当前等待的动作 |
| 本会话允许 | 该会话中仍需询问的动作键 |
| 不再询问 | 用户确认且通过校验的 exec 前缀,写入配置 |
| 拒绝 | 拒绝动作,通常轮次仍可继续 |
| 拒绝并停止 | 拒绝并结束当前轮次 |
WebUI 审批卡上的 Esc 等同于“拒绝”,轮次会继续,让 Agent 能回应拒绝原因。 再按 Esc 时才会进入页面通常的关闭顺序;没有其他打开的层时会停止当前轮次。
Shell 会话授权包含命令 segment、机器和工作目录;内置文件写工具按路径和工作目录 记忆;浏览器操作工具共享站点级授权键。其他工具通常按精确调用记忆。会话授权保存在 内存中,不等于持久化全局前缀规则;两者都不能覆盖 deny。过期或被拒绝的动作在同一 轮次内不会原样再次询问。
网络¶
沙箱里的命令能访问哪些地址,也属于同一套权限,写在 permissions.network 下。Raven
启动的每个沙箱都读它:主智能体的、子智能体的、DAG 节点的,以及在沙箱里运行的 MCP
服务。改动会在运行中的沙箱执行下一条命令之前生效,也会在沙箱里的 MCP 服务下一次工具调用
之前生效。
{
"permissions": {
"network": {
"default": "open",
"rules": [
{ "host": "git.internal.example.com", "ports": [443] },
{ "host": "pastebin.com", "tier": "deny" }
]
}
}
}
| 键 | 含义 |
|---|---|
default |
open(默认):三段及以上的主机名放行所有端口,另外常见的包仓库、代码托管和模型服务域名放行常用端口。closed:只放行规则允许的。 |
rules[].host |
主机名。*.example.com 匹配一段,**.example.com 匹配任意多段。通配符只能占整段。 |
rules[].ports |
端口。不填时,允许规则取 22、80、443、8080、8443 和 9418,拒绝规则拒绝所有端口。 |
rules[].binary |
程序,写它在沙箱里的绝对路径,比如 /usr/bin/curl。不填表示任何程序。 |
rules[].tier |
allow(默认)或 deny。 |
配置里还写着 tools.sandbox.allowNet 的,首次加载时会自动搬到这里,并给出提示:true
对应开放默认,false 对应关闭,主机列表表示默认关闭、只在 80 和 443 端口放行这些主机,
带 "*" 的列表表示保持开放默认,再加上其余主机。写成 host:port 的条目会变成只放行该端口
的规则;规则表达不了的条目(比如地址段)会被跳过,提示里会列出来。
连接被拦截时¶
命令运行时,沙箱会拦下没有规则放行的连接。Raven 从网关读到拦截记录后,按处理工具调用 的同一套办法处理:
- 命中你的拒绝规则的目标,直接拒绝,不询问。
ask模式下会问你,卡片上写明程序、地址和命令。smart模式下先交给审核模型。命令明显需要的目标(比如安装用的包仓库、克隆用的仓库 主机)由它放行,其余转给你。full模式下,该目标在本会话内放行。- 没人可问时(比如定时任务或
raven agent -m),目标保持拦截,工具结果里会写明,-m以退出码 3 结束。
以 IP 形式给出的地址,以及 localhost、metadata.google.internal 这类内部名称,模式和
审核模型都不会放行,只能由你决定。一个 Raven 把另一个 Raven 当子智能体运行时,子智能体
对这类目标的请求会被拒绝,因为那里没有人能回答。放行之后 Raven 不会自动重跑命令,而是告诉
智能体可以再跑一次。同一会话的几个智能体同时碰到同一个地址时,只问你一次。
| 选择 | 在哪里放行 |
|---|---|
| 本次允许 | 被拦截的那个沙箱,直到它结束 |
| 本会话允许 | 这个会话的所有沙箱,直到 Raven 重启 |
在 permissions.network 里加规则 |
之后的所有沙箱 |
拒绝规则优先于同一目标的允许规则,也优先于这个会话其他沙箱里的本会话放行;之后新加的拒绝 规则,会在每个沙箱运行下一条命令之前生效。在被拦截的那个沙箱里直接放开的地址(本次允许或 本会话允许),会一直有效到那个沙箱结束;对主智能体的沙箱来说,就是到 Raven 重启。
在开放默认下,针对常见域名的拒绝规则会从该域名上拿掉它列出的端口,对所有程序都生效;没列 端口时拿掉整个域名。其他程序需要这些端口时,会单独询问。
主智能体的沙箱由网关服务的所有会话共用,所以在它里面放行的地址,在 Raven 重启之前对
所有会话都有效。遇到这种情况,确认提示里会写明。在这个沙箱里,只有 permissions.mode
设定的模式能免询问放行目标;某个会话单独切到更宽松的模式时,仍会询问。
在沙箱里运行的 MCP 服务也一样处理,针对的是它的工具运行期间被拦下的连接。卡片上写的是 “沙箱里的某个进程”,因为网关不会说明是哪个进程发起的连接。
网关按沙箱记录拦截,不区分是哪条命令。命令运行期间,同一沙箱里的其他进程(比如在沙箱里 运行的 MCP 服务,或者留在后台运行的任务)发起的连接,也会和这条命令一起询问。卡片上写明了 每个连接是哪个程序发起的。
限制¶
- 在
open默认下,拒绝规则能把pastebin.com这类两段主机名移出开放集合,但拦不住 三段及以上的主机名:OpenShell 无法在放行它们的那条规则里开例外。这样的规则仍然能阻止 Raven 放行该主机,加载时 Raven 也会给出警告。必须访问不到的主机,请用default: closed。 - 允许规则只部分覆盖被拒绝的目标时(比如主机名用了通配符,或者允许所有程序而拒绝规则只 点名了一个程序),出于同样的原因也无法单独拦下这个目标。Raven 会保留这条允许规则,并在 加载时给出警告。
- 设计引擎的渲染器运行的是 Raven 自己的渲染任务,不执行智能体给的命令,始终断网,也没有 单独的网络开关。
- 网关默认的投递方式下,放行的地址大约 10 秒后才在运行中的沙箱生效。改成约 1 秒的网关 设置见沙箱。
委派是独立信任边界¶
Raven 的权限门管理自身注册表调用,不是外部 Agent 进程内每一条命令。
- 入站 ACP: Raven 可通过
session/request_permission请求编辑器或宿主审批。 - 出站 ACP: Raven 无人值守客户端自动优先选择子 Agent 的
allow_always或allow_once;启用 Agent 不代表每个内部操作都有人审阅。拒绝规则会传过去:请求中的 shell 命令命中你的deny规则或tools.exec.extraDenyPatterns时,Raven 选择子 Agent 的拒绝选项。Raven 自家智能体(Raven-Code 等)按你的整套权限运行,包括模式以及 询问、允许、拒绝和网络规则;你的沙箱是 Linux 或 macOS 上的 OpenShell 时,它们也在同样 的沙箱里运行。第三方 Agent 只在它发出请求的调用上受约束;新增的规则要等正在运行的 Raven Agent 下次启动才生效。 - CLI 和其他后端: 检查启动命令、环境、工作目录及原生权限策略。宿主规则不会 自动跨所有后端继承。
- A2A: 共享 bearer token 接纳远程操作者。宿主工具门仍有效,但当前入站 A2A 轮次没有工具审批 responder;问题 broker 不是权限 UI。
- DAG:
confirm: true请求用户确认已声明的任务图,不会逐一审批运行期间新增的动作。 未接入确认通道时,当前实现会记录提示并继续执行,因此不能用这个开关保证“未审批就不执行”。 技能/MCP 选择依赖后端能力,降级通知意味着不能在那里把它当作可靠执行边界。
允许无人值守子 Agent 时,优先使用窄范围凭据、隔离账户或容器,并明确划分工作文件。
沙箱、文件与不可信内容¶
沙箱控制执行位置。OpenShell 沙箱以读写方式挂载真实工作区,在挂载中删除就会删除真实文件。 所以权限门不会仅因存在沙箱就自动允许命令。第三方后端可能不使用 Raven 的执行器。 详见沙箱。
工作目录保护、DAG 引用边界、渠道发送者白名单和网络限制是作用范围不同的附加控制。 Prompt injection 标签把工具结果和子 Agent 输出标为不可信数据,但不能使模型判断 永不出错。凭据与网络可达范围应独立于 prompt 指令检查。
ACP 会脱敏出站参数、权限描述,以及 Raven 自己拼出的错误中可识别的秘密。由其他 Agent 返回的内容——子 Agent 的答复、Mirasim 的一轮回复、A2A 对端的回复——按发送方 Agent 的原文保留,脱敏与否由产生该内容的 Agent 决定;因此这类回复里回显的凭据会 原样保留。A2A 轮次失败只暴露固定消息,详细异常留在本地日志。两者都不保证每份日志和 transcript 可安全公开。尽量 不要把秘密放进任务 prompt,分享诊断导出前应审阅并脱敏。
排查拒绝或停滞的动作¶
| 现象 | 检查 |
|---|---|
full 仍拒绝命令 |
内置或用户 deny,切换模式不会覆盖它 |
| Smart 意外询问 | 审查升级、超时或服务商不可用 |
| 无界面任务拒绝修改 | 没有审批 responder,启动前应配置必要的窄权限 |
| 复合命令要求确认 | 每个 segment 和重定向都需要覆盖 |
| 之前的授权不适用 | 目录、机器、站点、会话变化,或进程已重启 |
| 子 Agent 未询问就执行 | 检查出站 ACP/子 Agent 原生策略,不只是宿主权限门 |
可检查工具调用 trace span 上的 permission.decision、permission.source 和 smart
reviewer 字段。实现入口为 raven/permissions/gate.py、raven/permissions/rules.py、
raven/permissions/session.py 和 raven/acp_client/permissions.py。