企业官网建设流程全解析

如何为 claude-quickstarts 自主编码 Agent 配置 Bash 命令白名单以限制可执行命令？

【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts

在 claude-quickstarts 仓库的autonomous-coding示例中，自主编码 Agent 会跨多个会话长时间自动写代码，期间它会调用 Bash 工具执行命令。为了防止 Agent 运行出格的命令（如删除文件、重启系统），该项目用了一个「白名单 + PreToolUse 钩子」的方案：只有ALLOWED_COMMANDS里显式列出的命令才允许执行，其余一律拦截。这篇文章讲清楚这套白名单在哪里配置、怎么增删命令，以及修改后如何用测试脚本和真实会话验证拦截行为。

适用对象：已在本机准备运行autonomous-codingdemo（需要最新版 Claude Code CLI、Claude Agent SDK 和ANTHROPIC_API_KEY）的开发者。

白名单如何生效

理解配置前先看清楚拦截链路，三处代码共同完成限制：

1. 钩子注册——client.py 的create_client()在创建 Claude SDK 客户端时，把bash_security_hook注册为 Bash 工具的 PreToolUse 钩子：

hooks={ "PreToolUse": [ HookMatcher(matcher="Bash", hooks=[bash_security_hook]), ], },

Agent 每次调用 Bash 工具前都会先经过这个钩子。钩子返回空字典表示放行，返回{"decision": "block", "reason": "..."}表示拦截。

2. 权限与沙箱——同一函数会向项目目录写入.claude_settings.json，其中 Bash 权限被写成Bash(*)（即权限层不限制命令内容），真正的命令过滤交给上面的钩子；同时sandbox开启 OS 级隔离，文件类工具（Read/Write/Edit/Glob/Grep）通过Read(./**)、Write(./**)等相对路径规则限定在项目目录内（客户端的cwd设为project_dir）：

security_settings = { "sandbox": {"enabled": True, "autoAllowBashIfSandboxed": True}, "permissions": { "defaultMode": "acceptEdits", "allow": [ "Read(./**)", "Write(./**)", "Edit(./**)", "Glob(./**)", "Grep(./**)", "Bash(*)", # 另有 Puppeteer MCP 工具，此处省略 ], }, }

3. 白名单判定——security.py 中的bash_security_hook()是核心。它先调用extract_commands()从完整命令串中解析出所有命令名（支持管道、&&、||、;链接、带路径的命令——路径会取basename，如/usr/bin/node识别为node），然后逐个检查是否在下表中：

ALLOWED_COMMANDS = { # File inspection "ls", "cat", "head", "tail", "wc", "grep", # File operations (agent uses SDK tools for most file ops, but cp/mkdir needed occasionally) "cp", "mkdir", "chmod", # For making scripts executable; validated separately # Directory "pwd", # Node.js development "npm", "node", # Version control "git", # Process management "ps", "lsof", "sleep", "pkill", # For killing dev servers; validated separately # Script execution "init.sh", # Init scripts; validated separately } # Commands that need additional validation even when in the allowlist COMMANDS_NEEDING_EXTRA_VALIDATION = {"pkill", "chmod", "init.sh"}

任何一段命令里出现白名单外的命令，钩子返回拦截，reason 为Command '<cmd>' is not in the allowed commands list。命令串无法解析（例如引号不闭合）时同样按失败安全原则拦截，reason 为Could not parse command for security validation: ...。

注意：README.md 的 Security Model 一节列出的白名单是摘要（ls、cat、head、tail、wc、grep、npm、node、git、ps、lsof、sleep、pkill），完整集合以 security.py 为准，代码里还包括cp、mkdir、chmod、pwd、init.sh。

准备条件

按 README.md 的 Prerequisites，先装好依赖并验证：

# 获取项目源码（如果本地还没有） git clone https://gitcode.com/GitHub_Trending/an/claude-quickstarts cd claude-quickstarts/autonomous-coding # 安装最新版 Claude Code CLI npm install -g @anthropic-ai/claude-code # 安装 Python 依赖 pip install -r requirements.txt # 验证安装 claude --version # 应为最新版本 pip show claude-code-sdk # 确认 SDK 已安装

再设置 API key（your-api-key-here替换为你自己的 Anthropic API key）：

export ANTHROPIC_API_KEY='your-api-key-here'

修改命令白名单

配置入口就是 security.py 顶部的ALLOWED_COMMANDS集合。README.md 的 Customization 一节明确给出修改方式：编辑security.py，向ALLOWED_COMMANDS中添加或移除命令名即可。命令名按裸名填写（如npm、git），不带参数、不带路径。

如果你新增的命令需要按参数进一步限制，可以参照现有三个特例的做法，它们通过COMMANDS_NEEDING_EXTRA_VALIDATION = {"pkill", "chmod", "init.sh"}被标记，并在bash_security_hook()里各有一个专用校验函数：

• pkill——validate_pkill_command()只允许终止开发进程，目标进程名必须在{node, npm, npx, vite, next}内；使用-f全命令行匹配时取第一个词作为进程名。其他目标（如pkill bash）会被拦截。
• chmod——validate_chmod_command()只允许授予可执行权限：模式参数必须匹配^[ugoa]*\+x$（即+x、u+x、a+x、ug+x这类形式），且不允许任何旗标（-R等直接拦截），chmod 777、chmod +w均会被拒。
• init.sh——validate_init_script()只允许执行./init.sh或以/init.sh结尾的路径，其他脚本名（如./setup.sh）一律拦截。

因此，为一个新的敏感命令增加参数级限制时的完整改动是：把它加进ALLOWED_COMMANDS，加进COMMANDS_NEEDING_EXTRA_VALIDATION，再仿照上面三个函数写一个validate_xxx()并在bash_security_hook()中对应分支调用——这套结构在 security.py 中可以直接对照。

用测试脚本验证白名单逻辑

修改白名单后，先在跑真实 Agent 之前用自带测试脚本检查判定逻辑。脚本头部注明了运行方式：

cd autonomous-coding python test_security.py

test_security.py 覆盖四类检查：

• extract_commands()的命令解析（链接命令、管道、全路径、变量赋值等用例）；
• chmod各模式/旗标的通过与拦截用例；
• init.sh脚本名校验的用例；
• 一批应当被拦截的命令（如rm -rf /、curl、pkill bash、chmod 777等）和一批应当放行的命令（如npm install && npm run build、pkill -f 'node server.js'、chmod +x init.sh && ./init.sh）。

每条用例打印一行PASS或FAIL（FAIL 时附期望值、实际值和拦截 reason），最后汇总：

Results: N passed, M failed

全部通过时打印ALL TESTS PASSED并以退出码 0 结束；只要有一条 FAIL，退出码为 1。有 FAIL 时，对照该行输出的Reason定位是白名单集合本身的问题，还是新增命令漏了参数级校验。需要留意的是：脚本里的用例是写死的固定清单，你新加入ALLOWED_COMMANDS的命令不会自动出现在用例中，脚本通过只能说明既有判定逻辑没被改坏，新命令的实际拦截效果要在真实会话中确认（见下一节）。

在真实会话中确认拦截行为

修改白名单后，用一个短迭代会话观察实际拦截。README.md 的 Quick Start 给出带--max-iterations的测试跑法：

python autonomous_agent_demo.py --project-dir ./my_project --max-iterations 3

--max-iterations 3限制 Agent 只跑 3 个迭代就退出，避免完整 demo 运行数小时（README 提醒该 demo 耗时长：首个会话生成 200 个测试用例需要 10 分钟以上，之后每个编码迭代约 5-15 分钟）。相对路径的--project-dir会被脚本自动放到generations/目录下。

运行中判断白名单是否按预期工作，看会话输出里每个工具调用后的状态标记（来自 agent.py）：

• 每次工具调用打印[Tool: <工具名>]，成功则显示[Done]；
• 工具结果内容中包含 "blocked" 时显示[BLOCKED] <内容>，这里的<内容>就是钩子返回的拦截 reason，例如Command 'rm' is not in the allowed commands list——看到这一行即说明白名单拦截生效。

启动阶段还有两个可核对的信号：客户端创建时会打印Created security settings at <项目目录>/.claude_settings.json及沙箱、文件系统、Bash 白名单、MCP 四行说明；会话结束后检查项目目录，应存在.claude_settings.json（README 的 Generated Project Structure 一节也把它列为生成物之一）。

如果 Agent 触发了拦截，README 的 Troubleshooting 对此给出定性：「Command blocked by security hook」属于安全系统按预期工作；确有必要时把该命令加入security.py的ALLOWED_COMMANDS，再按上面「验证白名单逻辑」一节回归。

限制与边界

• 钩子只拦截 Bash 工具：bash_security_hook()首先检查tool_name是否为Bash，不是则直接放行。文件类工具（Read/Write/Edit/Glob/Grep）不受白名单管，它们由.claude_settings.json里的./**相对路径权限规则限制在项目目录内。
• .claude_settings.json由代码自动写入：每次创建客户端时由 client.py 覆盖写入项目目录，并以绝对路径传给 SDK，不需要也不建议手工维护这个文件。
• 白名单外命令与不可解析命令都拦截：链接命令中只要有一段含白名单外命令，整条命令被拦（如./init.sh; rm -rf /在测试用例中属于应拦截项）；引号不闭合等无法解析的命令按失败安全原则拦截。
• 命令路径会被归一：extract_commands()对带路径的命令取basename，所以/usr/local/bin/node app.js按node判定，测试用例中也把它列为放行项。
• README 白名单是摘要：以 security.py 中ALLOWED_COMMANDS的完整集合为准，两者差异（cp、mkdir、chmod、pwd、init.sh）见上文对照。

【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts