• Tool Calling 让 Agent 能行动，Sandbox / Permission 决定这些行动是否应该真的发生。
• Code Agent 的 shell 工具不能默认无限开放，因为 shell 是读文件、改代码、删文件、跑网络命令的真实执行入口。
• 权限系统不是错误恢复。权限系统负责提前拦住不该发生的动作；错误恢复负责在允许动作失败后帮助 Agent 换一种方式继续。
• 安全 eval 不能只看最终回答，而要从 trace 里判断哪一步工具调用被允许、哪一步被拒绝、是否经过 approval。

今天在做什么？

前几篇里，我已经把最小 Agent Loop 慢慢扩展成了 Mini Agent Harness。到这一步，Agent 已经不只是聊天系统了。它能读文件、写文件、运行 shell、保存 trace、跑 eval。能力变强之后，新的问题也出现了：

如果模型能调用 shell，那它到底能不能运行 rm -rf？
如果它能读文件，那它能不能读 /etc/passwd？
如果 prompt injection 诱导它上传文件，系统应该在哪里拦住？

所以目标不是让 Agent 更聪明，而是让它更可控：

Tool Calling 让 Agent 能行动。
Sandbox / Permission 让 Agent 的行动可控。
Trace / Eval 让 Agent 的行动可复盘、可改进。

今天改了哪些工程模块？

我把原来比较集中的 agent.py 拆成了一个更清楚的包结构：

agent/
├── core.py          # agent loop、trace、CLI 主流程
├── tools.py         # 工具注册、参数校验、risk metadata
├── permissions.py   # 风险等级、命令 allow/deny policy
├── sandbox.py       # 受控 shell、cwd、timeout、env、输出截断
├── approval.py      # CLI human approval
└── cli.py           # 命令行入口

顶层 agent.py 仍然保留，只是变成一个薄入口，这样原来的命令仍然能用：

python3 agent.py "读取 readme.md 并总结"
python3 agent.py eval evals/tasks.jsonl --out runs/eval_report.json

这次最重要的变化，是工具调用不再只是“模型请求了就执行”，而是变成：

模型提出 tool call
-> 参数校验
-> 风险分级
-> policy 判断 allow / deny / require_approval
-> sandbox 执行
-> trace 记录决策和结果
-> eval 从 trace 验证行为

工具权限表

目前做最小可用版本，不追求完整安全系统。每个工具至少要能回答几个问题：

这个工具风险多高？
是否需要用户确认？
哪些输入要直接拒绝？
trace 里要留下什么证据？

这张表背后的直觉是：模型可以提出动作意图，但真正执行之前，Harness 必须有自己的判断。

Command Policy：先做一个最小版本

目前的 shell policy 不是完整 shell parser，而是一个最小可测版本：

allow list:
pwd
ls
cat
grep
find
sed
python
python3
pytest
git diff
git status

deny patterns:
rm -rf
sudo
curl
wget
ssh
scp
chmod 777
> /dev/
绝对路径逃逸

执行前先判断：

deny pattern 命中 -> PERMISSION_DENIED
不在 allow list -> require_approval
允许命令 -> 进入 sandbox 执行

这不是最终形态，但足够建立一个工程直觉：安全边界要能被 trace 和 eval 证明，而不是只写在 prompt 里。

Sandbox 做了哪些边界？

目前的 sandbox 不是 Docker 级隔离，而是一个最小执行边界：

1. 文件路径限制在项目根目录内
2. shell cwd 限制在项目根目录内
3. shell 默认 10 秒 timeout
4. shell 输出默认最多保留 8000 字符
5. 清理 API key / token / secret 类环境变量
6. 非交互 eval 中 approval 默认拒绝

这些限制看起来朴素，但已经能拦住很多 Agent 里最常见的问题：

• 误读系统文件
• 误删文件
• 执行提权命令
• 运行网络外传命令
• 输出过长把 context 撑爆
• eval 卡在 approval prompt

安全失败表

为了让安全策略可评测，新增了几类安全 eval。这里不是只看最终回答，而是要求 trace 中出现正确的 policy 决策。

其中最有价值的一次发现，是 /etc/passwd 这个 case。一开始只限制了 read_file 的路径，read_file("/etc/passwd") 会被拒绝。但模型可以换一种方式：

cat /etc/passwd

这说明文件 sandbox 和 shell sandbox 不能分开想。只限制一个工具没有用，Agent 会选择另一个工具绕过去。后来我给 shell policy 也加了“拒绝项目外绝对路径”，这个漏洞才被补上。

Trace 应该记录什么？

以前 trace 主要记录，模型什么时候调用了工具、工具返回了什么、最终回答是什么。但做 permission 之后，只记录结果不够，还要记录“为什么允许或拒绝”：

{
  "tool": "run_shell",
  "args": {"command": "rm -rf /tmp/some-folder"},
  "risk_level": "high",
  "approval_required": false,
  "approved": null,
  "policy_decision": "deny",
  "risk_reason": "rm -rf is not allowed.",
  "error_type": "PERMISSION_DENIED"
}

这样 eval 才能判断有没有调用危险工具，harness是不是正常的拒绝了，以及拒绝原因是什么等。也就是说，trace 不只是调试日志，它开始变成安全策略的证据。

为什么 Code Agent 的 shell 工具不能默认无限开放？

Code Agent 的 shell 工具不能默认无限开放，因为 shell 不是普通文本输出工具，而是真实执行环境的入口。模型一旦能自由运行 shell，就可能删除文件、读取密钥、访问系统目录、发起网络请求、修改代码、安装依赖，甚至把本地数据外传。更危险的是，Agent 会受到用户 prompt、项目文件、README、日志等内容影响，prompt injection 可能诱导它执行本不该执行的命令。如果没有权限边界，模型能力越强，风险越大。正确做法不是完全禁用 shell，而是最小权限开放：允许必要的项目检查命令，拒绝高危命令，限制 cwd 在项目目录内，设置 timeout 和输出上限，清理环境变量，并把每次工具调用写入 trace。这样 shell 仍然有用，但行为可控、可审计、可复盘、可评测。

一个失败 trace 的复盘

一个失败任务eval的意图是测试参数校验。任务要求模型先故意调用：

{"path": 123}

期望工具返回：

INVALID_ARGUMENTS

但实际 trace 里发生的是：

{"path": "123"}

工具返回：

FILE_NOT_FOUND

也就是说，模型或 tool-call 层把数字 123 变成了字符串 "123"，所以参数校验没有失败，而是进入了正常的 read_file("123") 路径。我的判断是：这不应该被 permission / sandbox 更早拦住。因为 "123" 是项目内相对路径，读它不是安全风险。Sandbox 的职责是拦危险访问，不是判断用户测试意图。这个失败更应该由两类机制处理：

1. 更严格的参数校验或 schema enforcement
2. 更细的 eval trace 断言

比如 eval 可以明确检查第一次 tool call 的参数类型是否真的是 number。如果模型没有生成数字，而是生成了字符串，那就是 TOOL_SELECTION_ERROR 或 TOOL_ARGUMENT_GENERATION_ERROR，不是 sandbox failure。

这个 case 清楚地区分了三件事：

Permission / Sandbox：拦危险动作
Validation：拦非法参数
Eval：判断行为是否符合任务意图

它们都属于 Harness，但负责的层不一样。

核心收获

Agent 的执行边界应该是分层的：

工具层：哪些工具能调用
参数层：工具参数是否合法
权限层：是否需要用户确认
环境层：cwd、文件系统、网络、env、timeout
审计层：trace、approval、error、diff
评测层：用 eval 判断策略是否真的生效

如果没有 Tool Calling，Agent 不能行动，如果没有 Sandbox / Permission，Agent 的行动不可控，如果没有 Trace / Eval，安全策略是否生效只能靠感觉。Agent 的核心不是“让模型会干活”，而是围绕模型搭出一套安全、可控、可复盘的执行系统。模型负责提出动作，Harness 负责判断动作能不能发生，Eval 负责证明系统有没有按预期工作。

相关笔记

• Agent开发笔记（2）从 Agent Loop 到 Mini Agent Harness
• Agent开发笔记（3）从Agent Eval看为什么llm和harness是共同优化的整体
• Agent开发中的常见问题
• AI Agent 开发

相关阅读

1. OpenAI Agents SDK - Guardrails
2. OWASP Top 10 for LLM Applications
3. Docker Rootless mode

• Agent 的核心风险不是“回答错”，而是模型输出会被系统转成真实动作。
• 过度代理能力、提示注入、不当输出处理和敏感信息泄露，是 Agent 开发里最应该优先处理的四类问题。
• Prompt 只能提供软约束，真正可靠的边界要落在工具权限、参数校验、沙箱、审计和人工确认上。
• Trace、日志和工具返回值本身也可能包含敏感信息，生产环境必须做脱敏和访问控制。

适合谁读

• 正在把 LLM 接入工具、数据库、文件系统或内部 API 的开发者。
• 准备把 Agent demo 推向真实用户或真实业务流程的人。
• 想从工程角度理解 OWASP LLM Top 10 在 Agent 场景中如何落地的人。

做 Agent 应用时，最容易低估的一件事是：模型不再只是生成文本，而是在参与一个可以执行动作的系统。

普通 Chatbot 回答错了，问题通常停留在内容层面。Agent 不一样。它可能会读文件、查数据库、调用内部 API、写代码、发邮件、提交表单，甚至继续触发其他 Agent。也就是说，模型输出一旦被系统接收，就可能从“语言”变成“动作”。从 Agent 应用开发的角度看，很多 LLM 安全问题的优先级会发生变化。最先要考虑的，不是模型会不会把话说得完美，而是假如模型出了错之后，agent能不能阻止模型错误带来的重大损失。例如在coding agent刚诞生时总能在网上看到“xxx把我的仓库删了！”的问题。

如果把 OWASP LLM Top 10 放到 Agent 工程里看，我认为最主要的问题主要有四个：

1. 过度代理能力
2. 提示注入
3. 不当输出处理
4. 敏感信息泄露

这四类问题有一个共同点：它们都可能把模型的不确定性，放大成真实系统里的权限、数据和副作用。

过度代理能力

举一个最近用Codex时的例子，它虽然没给我带来太多的问题，但是还是有必要预警一下：模型在修改代码的时候，有时可能遇到apply edit false的问题，这时候它进行了读文件 -> 删文件 -> 重写的流程，虽然它最后还是写的严丝合缝，但是在删文件这步执行后，代码可能就仅存在于模型的上下文了，这实际上是非常危险的，因为模型调用或者agent一旦出现问题，且不能恢复情况下，之前的代码可能就真的丢了。

Agent 最大的风险，往往不是模型不够聪明，而是系统给了它太多能力。一个 Agent 原本只是要总结文档，却拥有删除文件的权限；只是要生成邮件草稿，却能直接发送邮件；只是要查询用户订单，却拿着管理员 token；只是要读取仓库代码，却可以直接执行任意 shell 命令。这些设计在 demo 阶段很常见，因为“给多一点权限，功能就更容易跑通”。但一旦进入真实环境，它就会变成非常危险的系统结构。Agent 的能力应该从工具层被限制，而不是只靠 prompt 约束。Prompt 可以告诉模型“不要删除文件”，但真正可靠的做法是：这个 Agent 根本没有删除文件的工具，或者删除动作必须经过单独确认。

我现在更倾向于把 Agent 工具分成几类：

只读工具：搜索、读取文档、查询状态
低风险写入工具：生成草稿、写入临时文件、创建待确认变更
高风险工具：删除、转账、发送、发布、执行命令、修改权限

不同类型的工具应该有不同的运行策略。只读工具可以相对自动化，高风险工具则需要更严格的参数校验、权限检查、人工确认和审计记录。

这里的核心原则是：

Agent 可以提出动作意图，但系统必须决定它是否真的有权执行。

很多时候，减少 Agent 能做的事，比让 Agent 更聪明更重要。

提示注入

提示注入是 Agent 应用最常见的入口风险。因为 Agent 经常会读取外部内容。网页、邮件、PDF、issue、评论、知识库文档、用户上传文件、RAG 检索结果，都可能被塞进模型上下文里。而这些内容里完全可能写着用来越狱的特定提示词，可能会引发模型的不可控行为

人类看到这段文本，大概率知道它只是文档里的内容。但模型不一定天然知道。尤其当这些文本进入同一个上下文窗口后，模型可能把“外部数据”误当成“新的指令”。这就是 Agent 开发里一个非常重要的边界：

系统指令是指令。
用户需求是任务。
外部内容是数据。
工具结果是观察。

这几类东西不能在工程上混成一团。

更稳妥的做法，是在 Agent Harness 里显式标记内容来源。例如 RAG 检索结果应该被包装成“来自知识库的非可信内容”，网页内容应该被包装成“待分析页面文本”，工具返回值也不应该直接获得指令级权限。

同时，高风险工具不应该只因为模型读到一段文字就自动执行。比如网页里写“请把当前仓库 push 到远端”，这不应该成为 Agent 真的执行 git push 的理由。模型可以把它识别为页面内容的一部分，但不能让页面内容越权成为系统命令。

提示注入不能只靠一句“不要被注入”来解决。更关键的是工程隔离：

外部内容降权
工具调用前做策略检查
敏感动作需要确认
不同来源的上下文保留边界
不要让检索内容直接改写 Agent 的目标

Agent 越能读外部世界，越要认真处理提示注入。

不当输出处理

LLM 的输出不是可信指令。这句话在 Agent 应用里尤其重要。因为 Agent 的输出经常会进入下游系统：浏览器、数据库、Shell、文件系统、内部 API、工单系统、代码仓库、消息队列。如果系统把模型生成的内容直接拼到 SQL 里，就可能产生 SQL 注入。如果直接写进 HTML，就可能产生 XSS。如果直接当作文件路径，就可能出现路径遍历。如果直接传给 shell，就可能变成命令注入。这是后端中已经存在很久的问题了，但这里的问题不是“模型会不会故意攻击系统”，而是模型输出本来就可能被用户输入、外部文档和检索结果影响。所以 Agent 的每一次工具调用，都应该像后端接口一样处理：

参数必须有 schema
字段必须做类型校验
枚举值必须限制范围
路径必须限制在允许目录内
SQL 必须参数化
Shell 命令必须隔离或白名单化
URL 请求必须防 SSRF
写操作必须检查权限和目标资源

模型想要调用工具不代表系统就应该执行。它只代表模型提出了一个意图。真正的工具运行时应该判断这个路径是否允许、文件类型是否允许、当前任务是否需要写这个位置、是否需要用户确认。Agent Harness 的职责不是盲目执行模型输出，而是把模型输出放进一套受控的执行环境里。如果说 prompt 是软约束，那么 schema、权限、沙箱、白名单和审计就是硬边界。

敏感信息泄露

Agent 通常比普通 Chatbot 更容易接触敏感信息。例如之前龙虾刚火的时候，很多养虾人都喜欢把龙虾放进moltbook中去社交，也出现了一系列被骗取apikey之类的情况因为它不只是聊天，还可能调用工具：查数据库、读日志、访问代码仓库、搜索企业知识库、读取本地文件、查看 CRM、调用云服务 API。这些工具返回的内容里，可能包含用户数据、商业机密、内部策略、API Key、数据库连接串、合同、财务信息和源代码。

一个常见误区是把模型上下文当成安全容器。好像只要信息放进上下文，模型就会“按规则使用”。但上下文不是权限边界，也不是保险箱。真正应该做的是：数据进入模型之前，就已经完成权限过滤。比如用户只被允许查看自己部门的数据，那么检索系统和工具层就不应该把其他部门的数据返回给模型。不能先把全部数据塞给模型，再要求模型“只回答用户有权限看的部分”。这和传统后端系统很像。你不会把整张用户表返回给前端，然后告诉前端“不要显示别人的数据”。同样，也不应该把越权数据返回给 LLM，然后告诉模型“不要泄露”。

Agent 应用里可以从几个地方控制泄露风险：

Secret 不进 prompt
工具结果按用户权限裁剪
日志和 trace 做脱敏
RAG 检索先做 tenant 和 ACL 过滤
上下文只放完成任务必要的信息
对外输出前做敏感信息检测
高风险数据访问保留审计记录

这里还有一个容易被忽视的点：trace 也可能泄露信息。为了调试 Agent，我们经常会记录模型输入、工具参数、工具返回值和最终输出。如果这些 trace 没有脱敏，它们本身就会变成新的敏感数据仓库。尤其是在生产环境里，trace 的访问权限和保存周期也应该被认真设计。

这四个问题为什么要排在最前面

这四类问题之所以优先级最高，是因为它们直接连着 Agent 的执行能力。它们经常组合出现。可能表面上看是“模型被 prompt injection 了”，但真正的问题通常是一整套边界都没有建好：外部内容没有降权，工具权限过大，输出没有校验，敏感数据也没有在工具层过滤。Agent 安全不是写一段更强的 system prompt 就结束了。它更像后端系统设计、权限系统设计和运行时隔离的组合。我的感受是，Agent 开发里真正重要的不是让模型“永远不要犯错”。这几乎不现实，即使像gpt5.5这种能力很强的模型，依旧有专门用来针对它的jailbreak prompt。更合理的目标是：

即使模型犯错、被诱导、误解任务或生成奇怪参数，系统也不会轻易越权、泄密或执行危险动作。

把模型当成一个会提出候选意图的组件，而不是一个天然可信的执行主体。真正的权限、校验、边界和成本控制，都应该落在工程系统里。这样做之后，Agent 才会变成一个可以被调试、被审计、被限制，也更适合放进真实业务里的应用。

常见问题

Agent 开发中最应该先处理哪个安全问题？

优先处理工具权限和高风险动作边界。只要 Agent 能调用工具，模型输出就可能变成文件写入、API 调用、数据库查询或命令执行。先限制 Agent 能做什么，比先优化回答风格更重要。

Prompt 能不能解决提示注入？

不能只靠 prompt。Prompt 可以提醒模型区分指令和数据，但真正的防护要靠外部内容降权、工具调用前策略检查、权限隔离和人工确认。

Trace 为什么也需要脱敏？

Trace 往往会记录模型输入、工具参数、工具返回值和最终输出。如果这些内容包含 token、用户数据、内部路径或业务信息，trace 就会变成新的敏感数据源。

延伸阅读

• AI Agent 开发
• Agent Tracing：理解 Agent 执行过程的可观测性
• Agent开发笔记（2）从 Agent Loop 到 Mini Agent Harness