面向 AI 编码代理的智能 Shell 命令安全过滤器，通过 AST 解析与分层规则引擎实现 allow/deny/ask 决策，消除不必要的权限弹窗同时拦截危险操作。
Claude Warden 是一款专为 AI 编码代理设计的智能命令安全过滤器，支持 Claude Code、OpenAI Codex CLI、GitHub Copilot CLI 及任何支持 PreToolUse hook 的 AI 编码代理。当前版本 2.10.0，使用 TypeScript 编写，基于 Node.js 跨平台运行。
核心机制#
项目通过 @banyudu/bash-parser（bash-parser fork, v0.5.2）将 Shell 命令解析为 AST，不依赖字符串匹配，对以下复杂结构进行递归拆解与逐条评估：
- 管道与链式命令：
cat file | grep pattern | wc -l被拆解为三条独立命令分别评估，全部安全则放行，任一危险则拒绝整条管道 - Shell 包装器解包：
sh -c "npm run build && npm test"提取内部命令递归解析 - 环境变量前缀处理：
NODE_ENV=production npm run build正确忽略前缀，评估实际命令 - 子 Shell 递归评估：
$()和反引号内容被提取解析；不可解析结构（heredoc 等）在askOnSubshell启用时回退为 prompt - 远程命令递归评估：识别
ssh、docker exec、kubectl exec、sprite exec、fly exec等上下文，提取远程命令并递归解析评估
规则引擎#
评估引擎按 alwaysDeny → alwaysAllow → rules → defaultDecision 的层叠顺序匹配规则：
- 参数感知匹配：
git status放行但git push --force触发 prompt，基于参数模式而非仅命令名 - 目标策略（targetPolicies）：基于路径（
{{cwd}}、/etc）、数据库 host、endpoint URL 等维度进行策略覆盖 - Skill 过滤：拦截 Claude Code 的 Skill（斜杠命令）工具调用，支持白名单/黑名单/参数感知匹配
用户体验#
- 内置 100+ 常用命令自动放行规则，自动拒绝
sudo rm -rf /、shutdown等危险命令 - YOLO 模式：
/warden:yolo 5m临时跳过所有 prompt，但仍阻止 always-deny 命令 - SessionStart hook：注入引导信息，在工具选择前引导 Claude Code 遵循安全策略
- OS 桌面通知：macOS（terminal-notifier / osascript）、Linux（notify-send）在 prompt 或 deny 时发送通知
- 阻止反馈：命令被阻止时提供系统消息解释原因及 YAML 配置片段说明如何放行
配置体系#
采用分层配置：项目级 (.claude/warden.yaml) > 用户级 (~/.claude/warden.yaml) > 内置默认值。项目级配置可提交到仓库实现团队共享统一策略。
关键配置项：
| 配置键 | 说明 | 默认值 |
|---|---|---|
defaultDecision | 未匹配规则的命令默认决策 | ask |
askOnSubshell | 含 $() 或反引号的命令是否触发 ask | true |
notifyOnAsk | prompt 时发送 OS 通知 | true |
notifyOnDeny | deny 时发送 OS 通知 | true |
alwaysAllow | 始终放行的命令列表 | — |
alwaysDeny | 始终拒绝的命令列表 | — |
trustedRemotes | 可信远程上下文 | — |
targetPolicies | 基于路径/数据库/endpoint 的策略覆盖 | — |
rules | 按命令名细粒度规则 | — |
skills | Skill 过滤规则 | — |
安装与使用#
Claude Code 插件方式（推荐）：
/plugin marketplace add banyudu/claude-warden
/plugin install warden@claude-warden
重启 Claude Code 即生效。
npm 全局安装：
npm install -g claude-warden
claude --plugin-dir $(npm root -g)/claude-warden
独立 CLI 测试：
npx claude-warden eval "ls -la" # → allow (exit 0)
npx claude-warden eval "shutdown -h now" # → deny (exit 2)
npx claude-warden eval --json "git push --force" # → JSON 输出
架构要点#
- 入口：
dist/index.cjs（hook 入口，接收 stdin JSON）、dist/cli.cjs（独立 CLI） - 构建：tsup 打包 TypeScript → CJS，使用 pnpm 管理，Vitest 测试
- Hook 协议：兼容 Claude Code PreToolUse 协议（stdin JSON → stdout
hookSpecificOutput.permissionDecision）；Codex CLI 和 Copilot CLI 通过适配器转换 - Claude Code 插件结构：
.claude-plugin/目录 +marketplace.json
与 Claude Code Auto Mode 的关系#
Warden 负责快速确定性 Shell 命令过滤，Auto Mode 覆盖文件编辑、网络请求等非 Shell 操作，两者互补。
待确认信息#
- 仓库含
docs-src/目录并有构建脚本，但 README 未提供已部署的文档站 URL - npm 发布状态未在调查中验证
@banyudu/bash-parserfork 的具体改动未详查- Codex CLI deny 语义适用的具体版本未标注
- Copilot CLI 适配兼容性版本矩阵未提供
- package.json 中 Copyright 标注为 2026，年份待确认