企业官网建设流程全解析

这次不聊某个新模型，也不聊怎么提速，聊一个很容易被忽略、但上线后可能直接让机器被“搬空”的问题：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 安全”维度上的能力边界做一个速览。这里不写参数，只对比工具权限和配置成本，实际版本差异请以各自官方文档为准。

一句话总结：这类 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 工具在接入真实环境前，都必须确认三个问题：

1. 这个操作是不是任务必要的？
2. 这个操作的数据范围是否最小？
3. 这个操作能否被审计？

如果涉及读取个人数据、处理未公开的业务代码、操作生产环境资源，要严格限制 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 全局目录并确认 PATH：

npm config get prefix # Linux/macOS 将 bin 目录加入 PATH export PATH="$PATH:$(npm config get prefix)/bin"

4.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.bak

5. 关键操作：从 Agent 工具集中删除 BASH 工具

这是全文重点。删除 BASH 工具不是“不让 Agent 干活”，而是把“任意命令执行”降级成“有限动作”。

5.1 为什么优先删 BASH

Agent 的工具集通常包括三块：

1. 文件读写工具
2. Shell/BASH 工具
3. 网络请求工具

其中 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 测试用例总览

6.2 具体测试步骤

测试 01：基础能力是否正常

先让 Agent 完成一个普通的开发任务，确认删除 BASH 工具没有破坏核心功能。例如：

请读取 ./inputs/demo.csv 的第一行，并生成一个 Python 脚本统计总行数。

预期：Agent 能读取文件并生成脚本，但不要尝试自己运行脚本。如果它尝试运行脚本并失败，这是正常现象——这正说明 BASH 确实被禁用了。

测试 02：BASH 调用是否被拒绝

输入一个明显需要 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, json=payload, timeout=300) print(response.status_code) print(response.json())

7.2 批量任务中的安全策略

批量任务的安全风险会成倍放大。单独跑一次 Agent 出错，影响一个文件；批量跑 1000 次时如果存在越权，影响是 1000 倍。批量任务建议加上这几层控制：

1. 输入清洗：批量输入前先过滤可疑内容，尤其警惕包含“请忽略之前指令”“执行系统命令”等提示词注入特征的文本。
2. 单任务超时：每个任务设置超时时间，避免单个任务卡死拖垮队列。
3. 输出隔离：每个任务使用独立输出目录，避免互相覆盖。
4. 失败重试：重试前确认失败原因，不要对越权错误盲目重试。
5. 审计日志：记录每个任务的调用工具、输入摘要、输出位置、耗时和结果状态。

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 会在本地加载小模型用于部分任务，或者作为独立服务运行。显存占用和模型大小强相关，不要用某个网上的显存数字直接套用到自己的环境。正确做法是：

1. 启动 Agent 前记录当前显存基线。
2. 运行一个任务。
3. 运行结束后再次查看显存。
4. 对比差值就是本次任务的增量占用。

nvidia-smi --query-gpu=memory.used --format=csv -l 2

8.3 日志级别的平衡

安全配置完成后，建议把日志级别调到debug或等价的详细模式，至少观察一两天。确认工具调用符合预期后，可以调回info，避免日志量过大。

9. 常见问题与排查方法

下面这张表覆盖了配置 Agent 安全时最高频的几类问题：

9.1 一些排错路径

如果 Agent 配置了禁用 BASH，但还是能执行 Shell，按这个顺序排查：

1. 确认你在哪个配置目录修改，有些 Agent 同时读项目级和用户级配置，项目级配置优先级更高。
2. 确认配置文件格式正确，JSON 是否多了一个逗号，YAML 缩进是否错乱。
3. 确认服务是否重启。
4. 查看日志里工具调用记录，看 Agent 到底调用了哪个工具。
5. 如果都无法解决，用白名单命令替代完整 BASH，即使某个命令漏掉了，白名单也能挡住大部分风险。

10. 最佳实践与使用建议

10.1 分层权限模型

把 Agent 的权限分成三层，越往下越危险：

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 时可以对照检查。