权限

配置权限

通过细粒度的权限规则、模式和管理策略来控制 Hawa Code 可以访问的内容和执行的操作。

Hawa Code 支持细粒度权限，让您可以精确指定代理允许执行的操作和禁止执行的操作。权限设置可以纳入版本控制并分发给组织中的所有开发人员，同时也可以由个人开发人员进行自定义。

权限系统

Hawa Code 使用分层权限系统来平衡功能和安全性：

工具类型	示例	是否需要审批	“是，不再询问” 作用
只读	文件读取、Grep	否	不适用
Bash 命令	Shell 执行	是	按项目目录和命令永久生效，会持久化保存到项目的 setting 配置文件中
文件修改	编辑/写入文件	是	会话结束前有效，在内存中保存，重启 Hawa Code 会失效

管理权限

settings.json 文件可以配置相关权限。

• Allow：允许 Hawa Code 无需手动审批即可使用指定工具。
• Deny：阻止 Hawa Code 使用指定工具。

规则按顺序评估：拒绝 -> 允许。第一个匹配的规则生效，因此拒绝规则始终优先。

权限模式

Hawa Code 支持多种权限模式来控制工具的审批方式。有关何时使用每种模式，请参阅权限模式。在设置文件中设置 defaultMode：

模式	描述
default	标准行为：首次使用每个工具时提示权限
acceptEdits	自动接受会话的文件编辑权限
plan	计划模式：Hawa 可以分析但不能修改文件或执行命令
auto	自动批准工具调用，并进行后台安全检查以验证操作是否符合您的请求。目前为研究预览版
dontAsk	除非通过 /permissions 或 permissions.allow 规则预先批准，否则自动拒绝工具
bypassPermissions	跳过权限提示，除非写入受保护目录（见下方警告）

bypassPermissions 模式会跳过权限提示。写入 .git、.hcode、.vscode 和 .idea 目录时仍会提示确认，以防止意外损坏仓库状态和本地配置。写入 .hcode/commands、.hcode/agents 和 .hcode/skills 目录不受限制，不会提示，因为 Hawa Code 在创建技能、子代理和命令时会频繁写入这些目录。仅在隔离环境（如容器或虚拟机）中使用此模式，以避免 Hawa Code 造成损害。管理员可以通过在托管设置中将 disableBypassPermissionsMode 设置为 “disable” 来禁用此模式。

权限规则语法

权限规则遵循 工具 或 工具(限定符) 的格式。

匹配工具的所有使用

要匹配工具的所有使用，只需使用工具名称，不带括号：

规则	效果
Bash	匹配所有 Bash 命令
WebFetch	匹配所有网络获取请求
Read	匹配所有文件读取

Bash(*) 等同于 Bash，匹配所有 Bash 命令。

使用限定符进行细粒度控制

在括号中添加限定符以匹配特定的工具使用：

规则	效果
Bash(npm run build)	匹配确切的命令 npm run build
Read(./.env)	匹配读取当前目录中的 .env 文件
WebFetch(domain:example.com)	匹配对 example.com 的获取请求

通配符模式

Bash 规则支持使用 * 的 glob 模式。通配符可以出现在命令的任意位置。以下配置允许 npm 和 git commit 命令，同时阻止 git push：

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git * main)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

• 前的空格很重要：Bash(ls *) 匹配 ls -la 但不匹配 lsof，而 Bash(ls*) 则两者都匹配。

工具特定的权限规则

Bash

Bash 权限规则支持使用 * 的通配符匹配。通配符可以出现在命令的任意位置，包括开头、中间或结尾：

• Bash(npm run build) 匹配确切的 Bash 命令 npm run build
• Bash(npm run test *) 匹配以 npm run test 开头的 Bash 命令
• Bash(npm *) 匹配任何以 npm 开头的命令
• Bash(* install) 匹配任何以 install 结尾的命令
• Bash(git * main) 匹配像 git checkout main、git merge main 这样的命令

当 * 出现在末尾且前面有空格时（如 Bash(ls *)），它会强制执行单词边界，要求前缀后面必须跟着空格或字符串结尾。例如，Bash(ls *) 匹配 ls -la 但不匹配 lsof。相比之下，不带空格的 Bash(ls*) 同时匹配 ls -la 和 lsof，因为没有单词边界限制。

Hawa Code 能够识别 shell 操作符（如 &&），因此像 Bash(safe-cmd *) 这样的前缀匹配规则不会赋予其运行 safe-cmd && other-cmd 命令的权限。

当您使用”是，不再询问”批准复合命令时，Hawa Code 会为每个需要批准的子命令保存单独的规则，而不是为整个复合字符串保存单个规则。例如，批准 git status && npm test 会保存一个 npm test 的规则，因此未来的 npm test 调用无论 && 前面是什么都会被识别。像 cd 进入子目录这样的子命令会为该路径生成自己的 Read 规则。单个复合命令最多可保存 5 条规则。

读取和编辑

编辑规则适用于所有编辑文件的内置工具。Hawa Code 会尽力将读取规则应用于所有读取文件的内置工具，如 Grep 和 Glob。

读取和编辑拒绝规则适用于 Hawa Code 的内置文件工具，而不适用于 Bash 子进程。Read(./.env) 拒绝规则会阻止 Read 工具，但不会阻止 Bash 中的 cat .env。要启用阻止所有进程访问路径的操作系统级强制执行，请启用沙盒。

模式	含义	示例	匹配
/path	从文件系统根目录开始的绝对路径	Read(/Users/alice/secrets/**)	/Users/alice/secrets/**
~/path	从主目录开始的路径	Read(~/Documents/*.pdf)	/Users/alice/Documents/*.pdf
path 或 ./path	相对于项目根目录的路径	Edit(/src/**/*.ts)	<项目根目录>/src/**/*.ts

MCP

• mcp__test 匹配 test 服务器提供的任何工具（名称在 Hawa Code 中配置）
• mcp__test__* 通配符语法，同样匹配 test 服务器的所有工具
• mcp__test__call 匹配 test 服务器提供的 call 工具

WebFetch

WebFetch(domain:test.com) 匹配对 test.com 的获取请求

Agent (子代理)

使用 Agent(AgentName) 规则来控制 Hawa Code 可以使用哪些子代理：

• Agent(Explore) 匹配 Explore 子代理
• Agent(Plan) 匹配 Plan 子代理
• Agent(my-custom-agent) 匹配名为 my-custom-agent 的自定义子代理