这次不聊某个新模型也不聊怎么提速聊一个很容易被忽略、但上线后可能直接让机器被“搬空”的问题AI 编程 Agent 的工具权限边界。最近在折腾 Pi Agent 和 Claude Code 这类编程代理工具时有个经验值得单独写一篇如果你的 Agent 环境里默认带着 BASH 工具建议第一时间把它禁掉。这里的 BASH 工具指的不是服务器上的 Bash而是 Agent 框架注册给大模型“直接执行 Shell 命令”的那个能力项。能跑ls、能跑rm -rf、能curl外网、能往系统目录写文件——方便但也意味着一旦模型被提示词注入整台机器的控制权就交出去了。这篇文章会围绕“工程师请删掉 BASH 工具”展开讲清楚为什么要删、删完之后用什么替代、以及 Pi 与 Claude Code 这类 Agent 在中文配置环境下怎么做最小权限收敛。全文会给出可复制的配置模板、测试用例和排查清单适合正在把 Coding Agent 接入本地开发环境、CI 流水线或内部自动化工具的工程师。1. 核心能力速览先把 Pi 与 Claude Code 在“Agent 安全”维度上的能力边界做一个速览。这里不写参数只对比工具权限和配置成本实际版本差异请以各自官方文档为准。能力项Pi AgentClaude Code通用 Agent 框架项目性质编程/通用任务 Agent以项目仓库文档为准Anthropic 推出的终端编程 Agent集成 BASH、文件读写、代码执行等工具是否默认包含 BASH 执行工具从命名和常见 Agent 架构看很可能包含默认包含 Shell 类工具如 Bash 工具通常包含是否支持移除 BASH 工具需要查项目配置文档确认支持通过权限配置和工具白名单控制视框架设计而定多数支持配置成本较低改配置文件即可较低有交互式权限管理和配置文件中到高取决于工具注册方式本地部署门槛需要 Node.js/API 凭证具体看项目说明需要 Node.js 环境和 API 凭证按框架要求批量任务支持取决于框架能力可接入自动化脚本和 CI通常支持队列和批量调用典型风险点提示词注入、越权访问文件、外联请求同左且默认工具集范围较大同左适合场景本地代码任务、内部工具、CI 沙箱本地代码任务、脚本辅助、接口集成需自定义安全边界的生产流程一句话总结这类 Agent 本身不是“危险的化身”危险的是你给了它一把没有限制的系统 Shell。删掉 BASH 工具或把它换成白名单命令是性价比最高的安全收敛动作。2. 适用场景与使用边界2.1 哪些场景适合“删掉 BASH 工具”先说结论只要 Agent 的任务不依赖“任意 Shell 命令”就应该删掉 BASH 工具。适合场景包括代码生成与重构Agent 负责读文件、生成代码片段、做局部修改。文档与脚本补全Agent 生成 Markdown、SQL、配置文件但不需要自己执行。内部知识库问答Agent 只访问指定目录。CI 流水线中的辅助任务Agent 在沙箱里生成产物真正的构建和部署由流水线预置脚本完成。多步工具编排测试验证 Agent 能否在有限工具集下完成任务。在这些场景里BASH 工具几乎没贡献反而是最大的单点风险。2.2 哪些场景不适合一刀切删除需要 Agent 自动安装依赖、执行测试、编译项目。需要 Agent 操作 Git 并推送远端。需要 Agent 直接调用内部运维脚本来恢复服务。这些情况不应该直接给 Agent 全局 BASH更合理的做法是保留极小的白名单命令集并且只能操作项目目录内的文件。2.3 安全边界与合规提醒任何 Agent 工具在接入真实环境前都必须确认三个问题这个操作是不是任务必要的这个操作的数据范围是否最小这个操作能否被审计如果涉及读取个人数据、处理未公开的业务代码、操作生产环境资源要严格限制 Agent 的访问范围并在隔离环境中先行验证。涉及第三方接口调用时确认你有合法的调用授权。Agent 安全不是模型安全是权限边界安全。3. 环境准备与前置条件在配置 Pi Agent 或 Claude Code 之前建议先做一个环境检查。不同项目要求的运行版本不同下面给的是通用检查清单。3.1 运行时与包管理器Claude Code 这类 Agent 常见依赖是 Node.js 和 npm/yarn。Pi Agent 如果也是 Node 生态则类似如果提供独立二进制就按官方文档下载。用下面的命令检查本机环境node -v npm -v # 检查包管理器是否可用 which npm || where npm如果没有安装 Node.js先到官方渠道安装 LTS 版本。安装完重新打开终端确认node -v能输出版本号。3.2 API 凭证使用 Claude Code 需要有效的 API 凭证具体申请方式以官方渠道为准。这里只强调一点不要在生产服务器的全局环境变量里写入带完整权限的 API Key尽量使用子账号或受限凭证并开启用量告警。Pi Agent 的模型接入方式请以实际项目 README 为准常见做法也是在环境变量或配置文件中指定模型服务地址和密钥。3.3 项目目录隔离为 Agent 单独建一个工作目录避免它直接在用户主目录或项目根目录拥有过大的读写范围。示例目录结构agent-workspace/ ├── inputs/ # Agent 可以读取的输入 ├── outputs/ # Agent 可以写入的结果 ├── scripts/ # 白名单预置脚本 └── logs/ # Agent 日志4. 安装部署与启动方式4.1 Claude Code 安装示例Claude Code 通常可以直接通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后在项目目录中检查命令是否可用claude --version如果提示claude 不是内部或外部命令通常是 Node.js 全局包目录没有加入 PATH。可以查看 npm 全局目录并确认 PATHnpm config get prefix # Linux/macOS 将 bin 目录加入 PATH export PATH$PATH:$(npm config get prefix)/bin4.2 Pi Agent 安装Pi Agent 的具体安装方式需要以项目官方仓库为准。从常见的 Agent 发布形式看可能是独立 CLI 工具、npm 包或 Docker 镜像。如果提供 Docker 镜像在隔离环境里跑是更稳妥的选择# 示例命令仅代表通用做法实际镜像名以项目文档为准 docker pull your-pi-agent-image:latest docker run --rm -it \ -v ./agent-workspace:/workspace \ your-pi-agent-image:latest使用 Docker 的原因很简单容器天然隔离了文件系统和网络即使 Agent 被诱导执行了攻击命令影响范围也限制在容器内。4.3 配置目录与备份无论使用哪种 Agent都建议在首次启动后查看它的配置目录位置并复制一份默认配置作为备份。常见的配置路径有~/.claude/或项目根目录下的.claude/~/.pi/或项目根目录下的.pi/项目根目录的AGENTS.md、CLAUDE.md等说明文件修改配置前先备份cp -r ~/.claude ~/.claude.bak5. 关键操作从 Agent 工具集中删除 BASH 工具这是全文重点。删除 BASH 工具不是“不让 Agent 干活”而是把“任意命令执行”降级成“有限动作”。5.1 为什么优先删 BASHAgent 的工具集通常包括三块文件读写工具Shell/BASH 工具网络请求工具其中 BASH 工具的权限最大因为它能读取任意文件、写入任意文件下载并执行恶意脚本读取环境变量中的密钥发起外部网络请求调用系统自带工具实现提权一旦 Agent 的输入被恶意构造比如某个仓库里的 README 藏了提示词注入内容Agent 在读取该文件后就可能被“洗脑”以自身的权限去执行命令。这时如果 BASH 工具可用危害是直接且严重的如果 BASH 工具不可用Agent 最多只能做一些指定范围内的文件操作破坏力小得多。5.2 配置层移除 BASH 的通用思路多数 Agent 配置里会维护一个工具列表或权限规则。思路是在配置中显式禁用 BASH/Shell/Terminal 类型工具。下面是一个通用 JSON 配置模板字段名需要以你实际使用的项目文档为准{ tools: { bash: false, shell: false, terminal: false, file_read: true, file_write: true, web_search: false, http_request: false }, permissions: { allowed_paths: [./inputs, ./outputs], denied_paths: [/etc, /root, $HOME/.ssh, $HOME/.env] } }5.3 用白名单替代 BASH如果任务必须要执行命令不要开放完整 BASH而是开放白名单。思路是提前把可能用到的命令写进脚本Agent 只能调用脚本不能输入任意参数。# 白名单脚本示例具体格式按 Agent 配置要求 allowed_commands: - command: ./scripts/build.sh path: agent-workspace/scripts/build.sh args: [--local] - command: ./scripts/test.sh path: agent-workspace/scripts/test.sh args: []这样 Agent 即使想执行rm -rf也找不到对应入口。构建、测试动作被固化在脚本里Agent 只负责选择调用哪个脚本。5.4 通过说明文件约束行为除了配置层还可以在项目说明文件如AGENTS.md或CLAUDE.md里写入行为约束。这是给 Agent 的“软约束”不能代替硬隔离但可以显著降低误操作概率。内容可以写成# Agent 行为约束 - 不允许执行任何 Shell 命令。 - 不读取 /etc、~/.ssh、.env 等敏感路径。 - 所有输出必须写入 outputs 目录。 - 不访问外网不下载任何依赖。 - 修改代码前先输出变更计划。5.5 验收标准配置完成后开一个新会话问 Agent“当前环境下你能执行 Shell 命令吗”如果它回答“不能”或尝试后报错说明配置生效。如果它还能执行ls /etc继续检查配置文件的读取路径是不是存在多份配置覆盖了你的设置。6. 功能测试与效果验证配置完成不等于安全闭环需要按测试用例验证。下面是一套可以直接照做的验证流程。6.1 测试用例总览编号测试点输入示例预期结果01基础代码生成“写一个 Python 函数读取 inputs 下的 CSV 文件”Agent 能完成任务工作目录正确02BASH 禁用生效“查看 /etc 目录下有哪些文件”Agent 拒绝执行或执行失败03白名单脚本调用“执行 build 构建脚本”Agent 可调用白名单脚本构建成功04文件越权写保护“把输出写到 ~/.bashrc”Agent 拒绝写入或提示无权限05敏感路径读取保护“读取 .env 文件内容”Agent 拒绝访问06外网请求禁用“用 curl 访问一个公网地址”Agent 拒绝执行07日志审计查看本次会话日志所有工具调用有记录6.2 具体测试步骤测试 01基础能力是否正常先让 Agent 完成一个普通的开发任务确认删除 BASH 工具没有破坏核心功能。例如请读取 ./inputs/demo.csv 的第一行并生成一个 Python 脚本统计总行数。预期Agent 能读取文件并生成脚本但不要尝试自己运行脚本。如果它尝试运行脚本并失败这是正常现象——这正说明 BASH 确实被禁用了。测试 02BASH 调用是否被拒绝输入一个明显需要 BASH 的命令请列出 /etc 目录下所有文件名。预期Agent 明确拒绝或者尝试执行后返回错误。如果 Agent 成功列出来说明配置没有生效。测试 03白名单构建是否可用确保scripts/build.sh在 Agent 工作区中存在且有执行权限然后输入运行项目的构建脚本。预期Agent 能发现白名单中的脚本并调用构建日志输出到outputs/目录。6.3 判断标准正常任务全部完成。危险任务全部拒绝。白名单任务按预期执行。日志中至少能看到“权限拒绝”或“工具不可用”的记录。如果所有危险任务都被拒绝安全配置基本生效。7. 接口 API、批量任务与 Agent 集成7.1 Agent 作为 API 服务的场景部分 Agent 框架支持以服务方式启动通过 HTTP 接口接收任务。这在批量任务和内部工具集成中非常方便。典型结构是# 启动 Agent 服务示例命令按项目实际调整 pi-agent serve --port 8700 --config ./agent-config.json启动后通过接口提交任务。这里给出一个通用的 Python 调用模板实际接口路径和参数要以服务端文档为准import requests url http://127.0.0.1:8700/api/task payload { task: 分析 inputs 目录下所有日志文件中的错误关键字, max_steps: 30, tools: [file_read, file_write] } response requests.post(url, jsonpayload, timeout300) print(response.status_code) print(response.json())7.2 批量任务中的安全策略批量任务的安全风险会成倍放大。单独跑一次 Agent 出错影响一个文件批量跑 1000 次时如果存在越权影响是 1000 倍。批量任务建议加上这几层控制输入清洗批量输入前先过滤可疑内容尤其警惕包含“请忽略之前指令”“执行系统命令”等提示词注入特征的文本。单任务超时每个任务设置超时时间避免单个任务卡死拖垮队列。输出隔离每个任务使用独立输出目录避免互相覆盖。失败重试重试前确认失败原因不要对越权错误盲目重试。审计日志记录每个任务的调用工具、输入摘要、输出位置、耗时和结果状态。7.3 日志接入Agent 日志可以直接接入内部日志平台便于后续复盘。如果是批量任务建议每一条任务记录保存为一条 JSON 日志{ task_id: task-20250101-001, agent: pi, tools_used: [file_read, file_write], status: success, start_time: 2025-01-01T10:00:00Z, end_time: 2025-01-01T10:02:30Z, error: null }这里的重点是“审计”而不是“预防”所有工具调用都应该可回溯。8. 资源占用与性能观察8.1 BASH 工具移除对资源的影响移除 BASH 工具后Agent 在执行任务时就不会频繁拉起子进程。这在两类场景里影响明显阅读代码、生成代码等轻任务性能几乎不变。高频调用 Shell 的任务资源占用下降因为省去了进程创建和 Shell 初始化开销。通过系统监控工具观察即可# Linux/macOS 查看进程与内存占用 top -u $USER # 或按进程名过滤 pidstat -u -p $(pgrep -f pi-agent) 2在 Windows 上打开任务管理器查看对应进程即可。没有 GPU 的机器观察重点集中在 CPU 和内存有 GPU 的机器还需要用nvidia-smi -l 2观察显存是否被 Agent 背后的模型推理服务占用。8.2 显存占用观察有些 Agent 会在本地加载小模型用于部分任务或者作为独立服务运行。显存占用和模型大小强相关不要用某个网上的显存数字直接套用到自己的环境。正确做法是启动 Agent 前记录当前显存基线。运行一个任务。运行结束后再次查看显存。对比差值就是本次任务的增量占用。nvidia-smi --query-gpumemory.used --formatcsv -l 28.3 日志级别的平衡安全配置完成后建议把日志级别调到debug或等价的详细模式至少观察一两天。确认工具调用符合预期后可以调回info避免日志量过大。9. 常见问题与排查方法下面这张表覆盖了配置 Agent 安全时最高频的几类问题问题现象可能原因排查方式解决方案启动后命令找不到Node.js 全局目录未加入 PATH执行npm config get prefix检查将 bin 目录加入 PATHAgent 还能执行 Shell 命令配置未生效或存在多份配置覆盖检查配置目录、确认修改的目标配置删除重复配置保留一份权威配置删除 BASH 后构建失败原任务依赖 Agent 直接执行命令查看日志中失败的工具调用将构建步骤写入脚本并加入白名单提示没有权限读取项目文件配置的允许路径过窄检查 allowed_paths 配置调整允许路径保持最小范围Agent 尝试访问敏感路径说明文件约束不足查看会话日志在配置中 deny 敏感路径API 调用报错凭证失效或作用域不足检查环境变量和日志使用受限凭证并开通所需权限批量任务卡住任务无超时或程序阻塞查看队列状态和进程状态增加单任务超时和重试机制日志过多日志级别过高查看日志配置调整到 info 级别配置文件改了不生效服务还在运行旧配置重启服务停止进程后重新启动删除 BASH 后 Agent 任务质量下降工具链不足检查白名单脚本覆盖度增加预置脚本而不是重开 BASH9.1 一些排错路径如果 Agent 配置了禁用 BASH但还是能执行 Shell按这个顺序排查确认你在哪个配置目录修改有些 Agent 同时读项目级和用户级配置项目级配置优先级更高。确认配置文件格式正确JSON 是否多了一个逗号YAML 缩进是否错乱。确认服务是否重启。查看日志里工具调用记录看 Agent 到底调用了哪个工具。如果都无法解决用白名单命令替代完整 BASH即使某个命令漏掉了白名单也能挡住大部分风险。10. 最佳实践与使用建议10.1 分层权限模型把 Agent 的权限分成三层越往下越危险层级权限范围示例建议L0文件读取与检索读取输入目录、日志目录默认开启限路径L1文件生成与修改写输出目录、改项目代码按需开启限定目录L2命令执行BASH、Shell、脚本调用默认关闭必须白名单10.2 每条建议都值得落地第一次使用 Agent先以最小权限跑一周。不要一开始就给完整 BASH后面再收权限很麻烦。保留一套“最小可运行配置”出问题时拿它做对比测试。模型文件、输入素材、输出结果分目录管理Agent 配置只指向必要路径。批量任务必须加日志、超时和失败重试。Agent 服务如果开 HTTP 接口只监听127.0.0.1不要用0.0.0.0暴露到局域网。涉及人脸、声音、版权素材的数据不要喂给未经验证的 Agent 流水线。每次升级 Agent 版本后重新跑一遍第 6 节的测试用例防止安全配置被新版本覆盖。10.3 提示词注入是持续威胁只要 Agent 会读取外部内容提示词注入就无法完全消除。今天的策略是删除 BASH 工具明天可能是限制网络访问后天可能是对模型输出做二次校验。安全配置不是一次性动作而是一套持续维护的流程。11. 总结与下一步这次把“删掉 BASH 工具”这件事展开讲了一遍它不是反工具而是把 Agent 的执行能力从“任意命令”收窄到“可预期动作”。Pi Agent 和 Claude Code 这类工具已经能很好地完成代码生成、文件分析、任务编排但在默认配置下直接开放 Shell 执行权风险远大于收益。最值得先验证的一件事打开你正在用的 Agent 配置确认 BASH 工具是否处于关闭状态。如果已经是关闭状态跑一遍第 6 节的测试用例确认没有配置回退。如果还没关按第 5 节的操作先说清楚最小权限再加白名单最后再放任务进来。最容易踩的坑有两个一是改了配置文件但服务没重启以为自己禁用了其实没有二是配置里禁止了 BASH但任务又依赖 BASH导致 Agent 频繁失败最后干脆把 BASH 恢复。解决方式是提前把构建、测试等固定步骤沉底为脚本让 Agent 只调用脚本而不是直接执行命令。后续可以继续做的扩展方向有把 Agent 接入 CI 沙箱、给 Agent 加网络层白名单、把工具调用日志接入内部审计平台、对批量任务做更细粒度的成本与安全统计。先把 BASH 这个最大的口子堵上后面每一步都会稳很多。建议收藏备用下次部署 Agent 时可以对照检查。