权限与访问控制

CrabCode 的工具权限模型：5 种模式 + 工作目录白名单 + allow/deny/ask 规则。

是什么

每次 CrabCode 想读文件、写文件、跑命令、访问网络时，都要过一次工具权限检查。决定结果的两件事：

1. 当前权限模式（5 种之一）
2. settings.json 的 permissions 字段里的 allow / deny / ask 规则

这里说的"权限"是单机本地工具粒度的拦截器，不是企业 SSO/RBAC 那种身份认证体系。账户登录与计费由 Acosmi 网关负责，详见 getting-started。

何时会看到这个文档

• settings.json 里 permissions.defaultMode 值非法时
• additionalDirectories 路径配错时
• 终端里 /permissions 命令的"了解更多"
• 模型尝试调用工具被拒，提示链接到这里

五种权限模式

切换方式：

crabcode --permission-mode plan        # 启动时指定

crabcode --permission-mode plan        # 启动时指定

或写进 settings.json：

{ "permissions": { "defaultMode": "acceptEdits" } }

{ "permissions": { "defaultMode": "acceptEdits" } }

或在 TUI 里按 Shift+Tab 循环切换（default → acceptEdits → plan → bypassPermissions → 回到 default）。

工具 × 模式行为矩阵

下表展示常用工具在 5 种模式下的默认行为（仍可被 allow / deny / ask 规则改写）。

说明：

• "自动"代表无提示直接通过；"询问"代表弹确认对话框；"拒绝"代表静默拦截
• 子代理 (Task) 的工具集是父调用方工具集的子集，模式继承
• plan 模式只允许调用只读工具（Read / Glob / Grep / LS / WebSearch 视配置），任何写或副作用工具一律拒绝

工作目录白名单

CrabCode 默认只能读写启动时 cwd 及其子目录。要扩大：

crabcode --add-dir ~/code/sibling-repo

crabcode --add-dir ~/code/sibling-repo

或 settings.json：

{ "permissions": { "additionalDirectories": ["~/code/sibling-repo"] } }

{ "permissions": { "additionalDirectories": ["~/code/sibling-repo"] } }

启动时会请求你确认信任新加入的目录。

规则：allow / deny / ask

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",          // 任何 npm test 子命令直接通过
      "Read(/etc/hosts)"           // 允许读这个特定文件
    ],
    "deny": [
      "Bash(rm -rf:*)",            // 永远禁掉
      "WebFetch"                   // 整个工具禁掉
    ],
    "ask": [
      "Bash(git push:*)"           // 即使 acceptEdits 也要弹框
    ]
  }
}

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",          // 任何 npm test 子命令直接通过
      "Read(/etc/hosts)"           // 允许读这个特定文件
    ],
    "deny": [
      "Bash(rm -rf:*)",            // 永远禁掉
      "WebFetch"                   // 整个工具禁掉
    ],
    "ask": [
      "Bash(git push:*)"           // 即使 acceptEdits 也要弹框
    ]
  }
}

规则语法

• 形如 <ToolName> 或 &lt;ToolName&gt;(<匹配模式>)
• :* 匹配子命令前缀（如 Bash(git push:*) 涵盖 git push origin main、git push --force 等）
• 多段命令通过管道、&&、分号串联时，CrabCode 会按子命令逐段检查；任一段触发 deny 即整条拒绝
• 路径类工具（Read / Edit / Write / NotebookEdit）的括号内填绝对路径或 glob（如 Read(~/secrets/**)）
• WebFetch(domain:*) 可按域名做白/黑名单

冲突优先级

deny > ask > allow。即：

• 若同一调用同时命中 deny 与 allow → 拒绝
• 若同时命中 ask 与 allow → 弹询问
• 多层 settings 合并后规则按并集去重；任一层 deny 即生效

TUI 命令

企业 / 团队加固

托管/策略 settings.json 可以下发以下字段（高于个人 settings.json，组员无法覆盖）：

限制与注意

• bypassPermissions 模式风险高：CrabCode 启动时会要求显式确认；切换到此模式后，仍可通过 Shift+Tab 或 --permission-mode 切回 default，但已经执行的操作不可撤销
• --dangerously-skip-permissions CLI 标志等价于 bypassPermissions，建议只用在沙箱或无网环境
• 托管设置覆盖最高：组员无法绕过企业策略
• 规则按工具识别，不是按命令文本：Bash(rm -rf:*) 拒的是 rm -rf 这类调用本身；改名走别名（如 unalias rm; alias rm="rm -rf"）依然会被识别为 rm 调用并触发规则
• plan 模式不仅拒写：还拒绝任何会产生副作用的工具（Bash / WebFetch / NotebookEdit 等），是讨论方案的安全档

相关

• security
• settings
• sandboxing
• hooks