hanafubuki-agent

权限与审批

三种权限模式、命令的沙箱、哪些操作需要审批、如何回答审批,以及 Agent 没有提供的保护。

模型想要执行有副作用的操作(运行命令、修改文件、调用 MCP 工具)时,Agent 先根据权限模式决定是否需要你的同意。

权限模式

模式--permission-modeconfig.toml 中的值行为
手动(默认)manual"manual"需要审批的操作都等你回答
自动审查auto-review"auto_review"由模型审查需要审批的操作,判断是否允许,不再询问你
完全访问full-access"full_access"需要审批的操作直接允许

设置方式:

hanafubuki-agent config set permissionMode auto_review   # 以后都使用
hanafubuki-agent --permission-mode full-access exec "..." # 只对这次运行

也可以写在配置档中,例如 [profiles.review] permissionMode = "auto_review",再用 -p review 选择。权限模式在每个回合开始时确定。在终端界面中,/permissions 可以为本会话修改它(见下文),/status 会显示生效的模式。

单个会话的模式

一个会话可以使用与配置不同的模式,恢复会话后仍保留,不改变 permissionMode。在终端界面中用 /permissions 设置:和会话的沙箱一起作为预设设置,或用 /permissions 模式 单独设置(终端界面)。嵌入的宿主用 set_session_permission_mode 设置它(嵌入 Agent)。

  • 随时可以修改。正在运行的回合保持开始时的模式,会话的下一个回合使用新模式。
  • 只属于这个会话:其他会话,以及从它分叉出的会话,仍使用配置的模式。
  • 随会话保存,恢复时还原,重启 Agent 后恢复也一样。在 TUI 中,/new 和 /clear 继承当前会话的选择;退出 Agent 后重新以空对话启动时使用配置默认值。

沙箱

权限模式决定由谁批准一个命令;沙箱决定获得批准的命令能触及什么。两者互相独立:完全访问模式下不经询问就运行的命令,仍在沙箱中运行。

sandboxMode模型运行的命令可以
"read-only"读取你的用户能读的所有文件;除 /dev/null 和 /dev/tty 外不能写入;不能使用网络
"workspace-write"(Linux 和 macOS 上的默认值)读取所有文件;只能写入工作区根目录、/tmp、Agent 的临时目录(TMPDIR,Windows 上为 TEMP)和 sandboxWorkspaceWrite.writableRoots 之下;只有 sandboxWorkspaceWrite.networkAccess = true 时才能使用网络
"full-access"(Windows 上的默认值)你的用户能做的一切:没有沙箱
hanafubuki-agent config set sandboxMode read-only
hanafubuki-agent config set sandboxWorkspaceWrite.networkAccess true

它们就是 Codex 的 sandbox_mode 和 [sandbox_workspace_write];Codex 的默认预设是不带网络的 workspace-write。这些键见配置参考。和权限模式一样,一个回合的沙箱在回合开始时确定。

平台

  • Linux:内置 bubblewrap 创建用户、挂载和 PID 命名空间,seccomp 强制执行网络策略。只读挂载保护已存在的 .git、.agents 和 .hanafubuki-agent,包括可写根目录重叠的情况。宿主必须允许用户命名空间;AppArmor 或容器限制可能阻止启动,此时命令不会运行。启动 Agent 前设置 HANAFUBUKI_AGENT_USE_LEGACY_LANDLOCK=1 可使用旧 Landlock 后端(Linux 5.13+ 且启用 Landlock),但兼容后端无法保护可写根目录中的元数据。
  • macOS:Seatbelt。沙箱中的命令在 /usr/bin/sandbox-exec 下运行(只用这个路径,绝不用在 PATH 中找到的):它施加一个拒绝该模式所不允许的一切的策略,然后变成那个命令。这个策略是 Codex 的。可写根目录会先被解析,所以 /tmp 即 /private/tmp,符号链接形式的根目录授予的是它的目标;不存在的根目录保持不可写。在可写根目录之下,已存在的 .git(如果 .git 是文件,还有它指向的仓库)、.agents 和 .hanafubuki-agent 保持只读,就像 Codex 保护 .git、.agents 和 .codex 那样:否则命令可以添加 Git 钩子,或修改项目的 sandboxMode。
  • Windows:先运行 /setup-default-sandbox 并批准 UAC 提示。初始化会为联网和离线命令分别创建标准沙箱账户,以 DPAPI 和仅所有者/管理员可访问的 ACL 保护凭据,并安装持久 Windows Filtering Platform 规则,阻断离线账户的网络(含回环)。成功后保存 windows.sandbox = "elevated" 和 sandboxMode = "workspace-write";更高优先级配置可能覆盖这些值。命令以沙箱账户、受限令牌、独立桌面和关闭即终止的作业运行,不以管理员身份运行。可写根目录上的 ACL 条目会保留。任何你的账户无权修改其 ACL 的路径都保持原 ACE 给予的访问权限,而不是拒绝执行命令;启动时为工作目录和可写根目录所做的授权同样如此:工作目录或可写根目录属于其他账户(例如旧安装遗留的、已无法解析的 SID)时命令照常运行,写入则受这些 ACE 约束。已存在的仓库/配置元数据也一样保持只读:若某个 .git(例如位于其他账户所有的目录下的工作区)无法由你的 ACL 改写,它保持自身 ACE 给予的权限,命令仍按这些权限受约束地运行。若 DACL 本可由你的账户修改、修改却失败,命令仍然会被拒绝。初始化状态位于 %LOCALAPPDATA%/hanafubuki-agent/sandbox,可重新运行初始化修复。无需初始化也可使用 windows.sandbox = "unelevated":它以当前身份限制写入,但只设置离线环境变量,不阻断网络。未配置 Windows 沙箱时仍默认完全访问。

Windows 初始化会给发起 UAC 的用户授予本次安装的 WFP 规则读取权,只有管理员和 SYSTEM 能管理规则,因此 Agent 无需以管理员身份运行即可检查沙箱状态。如果旧安装提示 read sandbox network block ... Windows error 5,请更新 Agent 后,从普通用户会话重新运行 /setup-default-sandbox,批准一次 UAC 以修复规则权限。

hanafubuki-agent doctor 会报告当前生效的沙箱模式,以及这台机器能否提供它。

沙箱不可用时

需要沙箱、而这台机器无法提供的命令不会运行:Agent 绝不会改为不受限地运行它。这个工具调用在请求任何人审批之前就失败,模型会读到原因:

the command was not run: it needs the workspace-write sandbox, which is unavailable (this kernel has no Landlock (Linux 5.13 or later, with Landlock enabled)); set sandboxMode to "full-access" to run commands without a sandbox

/permissions 会显示后端不可用的具体原因,并在 Windows 上提供初始化入口。缺少辅助进程、Windows 初始化不完整、缺少 sandbox-exec 或 Agent 已处于 Seatbelt 内时,沙箱预设不可用。Linux 命名空间初始化也可能在命令启动时失败;此时返回原生错误,不会在沙箱外重试。嵌入宿主须注册辅助进程(嵌入 Agent)。

在沙箱之外运行一条命令

和 Codex 一样,模型可以请求在沙箱之外运行一条命令:调用 exec_command 时把 sandbox_permissions 设为 "require_escalated",并给出 justification,即向你提出的一个简短问题(工具)。命令需要的超出沙箱允许的范围(写入可写根目录之外、在网络关闭时使用网络),或者因为沙箱而失败时,模型会这样做。这样的命令需要单独的审批,审批会说明它在沙箱之外运行,并给出理由:

Run Posix command outside the sandbox in /home/me/project: npm install (reason: Do you want to download the project's dependencies?)
权限模式在沙箱之外运行的命令
手动等你回答
自动审查交给审查;审查者能看到它要离开沙箱,以及理由
完全访问被拒绝,模型会读到原因:不询问任何人的模式不能让命令离开沙箱

这与 Codex 的审批策略一致:on-request 询问你,auto_review 的审查者审查提升请求,never 拒绝它。获得批准后,命令不经沙箱、以你的用户权限运行;同一命令在沙箱内获得的批准不能让它在沙箱外运行,反之亦然。对沙箱外命令选择本会话内允许,只允许同一条命令(命令文本和目录)以后在沙箱外运行,不允许其他任何操作;工具本身的会话允许也不涵盖沙箱外的命令。会话的沙箱是 full-access 时,这个请求只改变审批,因为命令本来就不受限制。

被沙箱拒绝的命令,会以操作系统报告的错误失败(Permission denied、Operation not permitted、DNS 查询失败);和 Codex 一样,输出中没有提示:模型从工具的说明和下面的上下文中知道何时请求。

模型被告知的内容

每个回合的世界状态中,在权限模式旁边有一个 sandbox 部分,包含沙箱模式、是否允许网络、可写根目录(workspace-write 时),以及在回合的权限模式下命令如何离开沙箱,如同 Codex 的权限说明告诉它的模型的那样:

{
  "escalation": "A command that needs more than the sandbox allows runs outside it with sandbox_permissions \"require_escalated\" and a justification question; the user approves or denies it.",
  "mode": "workspace-write",
  "networkAccess": false,
  "writableRoots": ["/home/me/project", "/tmp"]
}

在自动审查模式下,提升说明会写明由审查者决定,并要求模型在被拒绝后只采用明显更安全的替代做法;在完全访问模式下,它说明不要请求;没有沙箱时,它说明没有沙箱。网络关闭、但生效的沙箱并不阻断网络时(Windows 的非提升沙箱,见平台),这一部分会加上 "networkEnforced": false,这样模型不会被告知网络不可达,而实际上它可达。只有其中之一改变时,这一部分才会改变并重新发送:沙箱模式、权限模式、工作区根目录或配置的根目录。

它不涵盖的内容

  • 只有模型运行的命令(exec_command,以及它们留在后台运行的终端)在沙箱中。文件工具受工作区根目录和审批约束;你配置的 MCP 服务器和钩子在沙箱之外运行。
  • 读取不受限制。
  • 写入受保护的元数据(包括 git commit)需要批准在沙箱外运行或使用完全访问。旧 Landlock 无法执行这些只读例外。
  • 在 macOS 上,命令启动时尚不存在的 .git、.agents 或 .hanafubuki-agent 不受保护:命令可以创建它。
  • 没有网络访问时,在 Linux 上除 Unix 套接字外的所有套接字都会被拒绝,连接任何套接字也会被拒绝,包括 Unix 套接字(SSH agent、Docker 的套接字);有网络访问时,只有虚拟机套接字仍被拒绝;两种情况下,可以绕过过滤器打开套接字的 io_uring 都会被拒绝。在 macOS 上,没有网络访问时任何套接字都无法连接,包括 Unix 套接字;有网络访问时都可以。
  • Windows 受限令牌限制写入而非读取;登录会话或 Everyone 可写的位置仍可写。只有提升后端强制隔离网络。命令的后台子进程随其作业结束。
  • Windows 提升运行器目前桥接管道输入输出。内部 ConPTY、终端尺寸调整和交互式 MSYS 程序仍需原生验收,不能视为与 Codex 终端运行器等价。
  • 在 x86_64 Windows 上,Git for Windows Bash 和 MSYS2 Bash 使用提升后端的登录会话级 IPC 兼容处理。非提升模式及其他 Windows 架构仍可能报 couldn't create signal pipe, Win32 error 5。
  • 在 Linux 的终端(PTY)命令中,/dev/stdout 和 /dev/stderr 指向终端的 /dev/pts 设备,它不可写:请直接写到输出,或写到可写的 /dev/tty(命令自己的终端)。
  • 使用旧 Landlock 且 Linux 早于 6.2 时,可写根目录外的文件截断不受限制(ABI 版本低于 3)。

MSYS2 兼容及剩余限制

写入旧工作区文件的权限回归已修复。 受限令牌不再包含可复用的沙箱账户 SID。在 x86_64 Windows 上,提升运行器通过 Windows 调试事件观察其作业拥有的进程,把已加载 MSYS 运行时创建 IPC ACL 时使用的账户 SID 改为本次命令的新登录会话 SID。这样允许创建信号管道,同时不会授予该账户在旧工作区中拥有的文件写权限。安装的 Git/MSYS2 运行时文件不会被修改。兼容处理也覆盖间接启动的子进程,但不用于其他 Windows 架构或非提升模式。不支持的运行时不会回退到原来账户范围的限制 SID。

沙箱专用原生 CI 已在 Windows、Linux 和 macOS 全部通过。Windows 覆盖 Git for Windows Bash 和 MSYS2 Bash 的启动、管道/fork、CMD 间接启动 Bash、可写根写入、只读读取、根外与受保护元数据写入拒绝、网络开关,以及旧工作区文件覆盖拒绝。CMD 和 PowerShell 也通过旧工作区和只读权限回归检查。这不等于完整工作区 CI,也不代表所有 MSYS 运行时版本均已验收。内部 ConPTY、终端尺寸调整、交互式 MSYS 程序和嵌套调试器尚未验证。

从最初的提升后端更新后,请重新运行 /setup-default-sandbox 并批准 UAC。初始化会创建新的沙箱组和账户,使用 secrets/group-accounts.json;旧的 accounts.json、账户及规则保留但不再使用。普通用户读取 WFP 规则的权限修复仍然保留。

单个会话的沙箱

和权限模式一样,一个会话可以有自己保存的沙箱模式,不改变 sandboxMode(set_session_sandbox_mode,见嵌入 Agent)。会话的下一个回合使用它;恢复会话时还原,同一次 TUI 运行中的 /new 和 /clear 也会继承;分叉出的会话不带它,子代理沿用父会话的。sandboxWorkspaceWrite 仍取自配置。

预设

终端界面的 /permissions 提供 Codex 的预设,每个预设是一个权限模式加一个沙箱模式,一起为本会话设置(终端界面):

预设权限模式沙箱模式
Read only手动read-only
Default手动workspace-write
Auto-review自动审查workspace-write
Full access完全访问full-access

这台机器没有沙箱时,需要沙箱的预设不能选择。

哪些操作需要审批

操作是否需要审批风险等级
运行命令(exec_command)每次都需要严重(critical)
向运行中的命令输入、调整终端大小不需要
修改文件(apply_patch)需要高;修改工作区目录以外的文件时为严重
移动、删除文件(move_path、delete_path)需要高;递归删除为严重
读取文件、列出目录、搜索文本不需要
网页搜索和抓取不需要
MCP 工具取决于服务器的审批策略,见 MCP高;工具声明有破坏性时为严重
代码插件的工具需要,与需要审批的 MCP 工具一样高
MCP 资源、记忆工具、Skill 列表和读取、查看图片不需要
启用或停用 Skill总是询问你严重
git clone总是询问你严重
  • 没有“安全命令”白名单:即使是 ls 或 git status 也需要审批。
  • 读取文件不受工作区目录限制,模型可以读取你的用户能读取的任何文件。
  • 总是询问你的操作(启用或停用 Skill、git clone)即使在自动审查和完全访问模式下也会询问,并且只能允许一次。
  • 你在终端界面中 ! 之后亲自输入的命令,在任何模式下都以你的输入作为批准:它在会话的沙箱中运行,不会弹出询问,除非有总是要求由人决定的批准规则适用。

回答审批

审批框显示操作类型、摘要和风险等级。按 y 允许一次,按 a 在本会话内允许(可用时),按 n 或 Esc 拒绝。Ctrl-C 拒绝当前请求及排在后面的所有请求。见终端界面。

  • 允许一次只允许这一个操作。
  • 本会话内允许(a)在会话剩下的时间里,同一个工具的请求不再询问,不论是什么命令或路径;对沙箱之外的命令,只对同一条沙箱外的命令生效。这个允许只保存在内存中:重启、或者工具发生变化(例如 MCP 服务器的设置或凭据改变了)后会重新询问;只是重新连接的 MCP 服务器会保留它。总是询问你的操作不提供这个选项。
  • 拒绝后,模型会收到“被拒绝”的结果,通常会换一种做法,或者向你说明为什么需要这个操作。
  • 审批最多等待 15 分钟,超时视为拒绝。

自动审查

自动审查模式下,需要审批的操作交给会话自己的模型和 Provider 审查。审查请求不带工具,只包含操作本身和对话的摘录,模型要给出风险等级、你是否授权过这个操作、允许或拒绝,以及理由。

  • 允许时直接执行;拒绝时模型会收到理由。
  • 连续三次拒绝会停止回合,避免模型反复尝试。
  • 审查超时(90 秒)或失败时不执行操作。这是审查过程故障,不是权限拒绝或沙箱执行失败。工具错误会给出本地诊断,不暴露 Provider 的原始响应,并要求模型报告故障,不要通过 require_escalated 或其他变通方式重试。
  • 审查过程记录在会话历史中,exec --json 中是 permission_review_* 事件。
  • 审查拒绝的操作可以由你批准,见下文。

自动审查会增加模型请求,也依赖模型的判断。它适合日常的、可以撤销的工作。

批准被拒绝的操作

审查拒绝了一个你确实需要的操作时,可以批准它:在终端界面中,/approve 列出本会话的拒绝供你选择(终端界面);嵌入的宿主调用 approve_denied_action(嵌入 Agent)。只能批准会话最近十次拒绝中的一次,回合或压缩运行期间不能批准。

批准不会执行这个操作,也不会开始回合。它在会话历史中加入一条说明,模型从下一次请求起读到它:

The user has manually approved a specific action that automatic permission review previously denied.

Treat this as approval to perform that exact action in the same context in which it was originally requested.
Do not assume this also authorizes similar operations with different payloads.

Approved action:
<操作的摘要>
  • 模型把这条说明视为可信的上下文,你让它继续时,它可以再次尝试这个操作。
  • 重试仍然要经过审查。审查模型在你自己的消息中看到这条说明,标记为 user approval,并被告知它只授权这个确切的操作。其他操作,或参数不同的同一操作,照常判断。
  • 这条说明保存在会话历史中,重启后仍在。压缩既不保留这条说明,也不保留拒绝记录:压缩之后,这次批准就不再有效。

完全访问

完全访问模式下,需要审批的操作直接允许,不再询问。仍然有效的限制:

  • 沙箱:命令按 sandboxMode 的规定受限运行,请求在沙箱之外运行命令会被拒绝。
  • 总是询问你的操作(启用或停用 Skill、git clone)。
  • 被直接拒绝的调用,例如 MCP 服务器设置为 deny 的工具、无法解析的命令或路径。
  • 计划模式仍然只提供只读工具。

评审中

评审会话是只读的,代替 Codex 评审时所用的只读沙箱:

  • 只读的工具(文件、目录、文本搜索、网页、图片、MCP 资源)和其他地方一样运行。
  • 命令只有在是 git --no-pager 加 status、diff、show、log、blame、rev-parse、merge-base、ls-files 之一和普通参数时才运行:没有引号、变量、重定向、管道或第二个命令,也没有 --output 或 --ext-diff。它通过 POSIX shell 或 PowerShell 运行,从不经过 cmd.exe(后者会先运行工作目录中的 git.cmd)。必须带 --no-pager,这样不会有分页器在终端上等待输入。
  • 其他需要审批的操作(其他命令、修改文件、需要审批的 MCP 工具、Skill)都不经询问直接拒绝,原因作为工具的错误。不需要审批的照常运行:服务器策略不经询问允许的 MCP 工具(allow 且不是破坏性的),以及计划、目标等 Agent 自己的工具。
  • 评审的回合以完全访问模式运行,所以允许的操作不经询问直接运行(Codex 的“从不询问”)。之后你在评审会话上开始的回合按你的模式运行,仍然是只读的。
  • 这条规则属于 review 插件:插件关闭时不能开始评审,之前的评审会话也不再保持只读。

其他控制

  • 沙箱限制获得允许的命令能写入和访问的内容。
  • 计划模式让模型只能使用只读工具,与权限模式无关。
  • MCP 服务器有自己的审批策略(allow、ask、deny),见 MCP。
  • disabledPlugins 可以整个去掉某类工具,例如 ["execution"] 让模型无法运行命令,见配置参考。
  • 模型会被告知当前的权限模式和沙箱,以便据此规划。

本页目录