什么是 Shell Gate？
Shell Gate 是 Alius 的人在环安全层。它对 Agent 请求的所有 shell 和文件操作进行风险分析和范围检查，确保你在敏感操作中保持控制。
Shell Gate 不是一个简单的”允许/拒绝”开关。它会分析命令字符串、参数、路径、重定向目标、当前工作目录、来源、工作空间根目录和授权策略，做出细粒度的决策。
工作原理
当 Agent 想要执行操作（Shell 命令、文件写入等）时，Shell Gate 会：
- 拦截操作
- 分析命令风险和范围
- 决策：Allow / Deny / ApprovalRequired
- 记录决策用于审计
Shell Gate 决策
| 决策 | Plan 模式行为 | Bypass 模式行为 |
|---|---|---|
| Allow | 直接执行 | 直接执行 |
| Deny | 拒绝执行 | 拒绝执行 |
| ApprovalRequired | 暂停等待用户确认 | 直接执行并返回结果 |
在 Bypass 模式中，
ApprovalRequired的 Shell 决策会直接执行而非等待确认。被 Deny 的操作仍然不会执行。
Git 命令风险分级
Shell Gate 对 Git 子命令进行分类：
| 风险级别 | 命令 | 说明 |
|---|---|---|
| 低风险 | git status, git log, git diff, git show, git branch | 只读操作 |
| 中风险 | git clone, git fetch, git pull, git submodule | 写入工作空间和/或使用网络 |
| 中风险 | git push, git checkout, git switch, git merge, git rebase, git restore, git add, git commit | 修改操作 |
| 高风险 | git clean, git reset --hard | 可能导致数据丢失 |
工作空间边界检查
所有文件操作通过 resolve_within_workspace(path, workspace, must_exist) 进行边界检查：
- 阻止绝对路径访问（如
/etc/passwd） - 阻止父目录遍历（如
../secret） - 阻止符号链接逃逸
- 检查选项值中的路径（如
--output=/tmp/file） - 检查重定向目标（如
> /tmp/file、2>/tmp/error） - 忽略 URL 类值（不作为路径处理）
内置工具权限
| 工具 | 权限级别 | 说明 |
|---|---|---|
shell | Execute | 执行 shell 命令，120 秒超时，输出截断 20,000 字符 |
read_file | Read | 读取文件，工作空间边界检查 |
write_file | Write | 写入文件，Plan 模式需要确认 |
list_dir | Read | 列出目录内容 |
edit_file | Write | 替换文件内容，Plan 模式需要确认 |
Shell 工具
Shell 工具的完整执行流程：
- 解析参数
- 解析 cwd 在工作空间范围内
- 调用
shell_gate::authorize进行风险分析 Deny→ 拒绝执行Allow→ 执行命令ApprovalRequired→ Plan 模式暂停等确认，Bypass 模式直接执行- 输出格式：
[exit:N]\n<stdout>\n<stderr>，截断 20,000 字符
配置权限
在 .alius/config/permissions.toml 中配置：
[shell]
default = "ask"
auto_approve = ["ls", "cat", "git status", "git log", "git diff"]
deny = ["rm -rf /", "format", "mkfs"]
[file_write]
default = "ask"
deny_patterns = [".env", "credentials", "*.key"]
[network]
default = "ask"最佳实践
- 从严格开始 — 所有操作类型使用
ask作为默认 - 逐步添加自动审批 — 仅用于你经常运行且信任的命令
- 审查 Trace — 定期检查审计日志
- 不要自动审批写入 — 保持文件修改需要审批
- 关注 Bypass 模式 — Bypass 模式下 ApprovalRequired 会直接执行，确保你信任当前任务
审计
所有工具调用都会产生 ToolCallStarted 和 ToolCallCompleted 事件，记录在 Session 的 Trace 中。Shell 调用在会话区以 shell: <command> 格式显示，完成块包含简短的输出摘要。