系统级 Agent 命令白名单：让模型先申请，再执行

系统级 Agent 命令白名单：让模型先申请，再执行

一、Agent 自动执行命令最需要刹车

AI Agent 能读取文件、运行测试、修改代码和调用工具，效率很高，也很危险。模型生成一条命令时，可能并不知道它会删除文件、上传密钥、修改系统配置或跑很久。系统级 Agent 的第一条原则应该是：模型只能申请执行，宿主决定是否允许。

命令白名单不是为了让工具变笨，而是把高风险动作挡在边界外。允许cargo test、rg、ls这类只读或低风险命令，限制rm -rf、网络上传、系统权限修改和不可控脚本。初学者写 Agent 时尤其要克制，别把本机交给一个会猜命令的模型。

二、执行链路：解析、审查、确认、记录

flowchart TD A[模型提出命令] --> B[命令解析] B --> C[白名单匹配] C --> D{风险等级} D -->|低风险| E[执行] D -->|高风险| F[用户确认] E --> G[记录审计] F --> G

白名单应基于命令和参数一起判断。只允许git status不等于允许全部git命令；允许cargo test不等于允许执行任意cargo run。很多危险都藏在参数里，例如输出重定向、管道、子 shell、通配符和路径逃逸。

更稳的做法是不用 shell 拼字符串，而是把命令拆成程序名和参数数组。这样可以减少注入风险，也更容易审查。模型生成自然语言或 JSON 请求，宿主解析后决定是否转换成真实进程。

三、规则示例：命令策略要可读

下面是一份简化的命令策略配置。真实项目还要处理路径、超时和环境变量。

commands: allow: - program: "cargo" args_prefix: ["test"] risk: "low" - program: "rg" args_prefix: [] risk: "low" - program: "git" args_prefix: ["status"] risk: "low" deny: - program: "rm" - program: "curl" - program: "chmod"

策略要默认拒绝。没有匹配到允许规则的命令，一律需要人工确认或直接拒绝。这样新风险不会自动进入执行范围。白名单可以随着使用场景逐步扩展，不要一开始就放开所有命令。

路径也要限制。Agent 如果被允许读写工作区，就不应该访问家目录、SSH 密钥、系统配置和浏览器数据。可以把所有文件操作限制在 workspace root 下，并拒绝..路径逃逸。路径校验最好使用规范化后的绝对路径。

四、执行细节：超时、输出和审计不能少

每个命令都要设置超时。模型可能请求运行长时间服务或卡住的测试，如果没有超时，Agent 就会挂住。输出也要限制大小，防止命令刷出大量日志把上下文撑爆。终端工具最怕无限输出。

审计记录应包含模型请求、最终命令、工作目录、开始时间、退出码、耗时和输出摘要。这样用户可以回看 Agent 做了什么。出现问题时，审计日志比“模型刚才好像运行了什么”可靠得多。

最后，高风险命令需要用户确认，而且确认页面要展示真实命令和影响范围。不要只写"是否继续执行操作"。用户需要知道将在哪个目录执行、会修改哪些文件、是否访问网络。确认要具体，才有意义。

有一次同事的 Agent 在 CI 里跑了整整 40 分钟的脚本循环，因为白名单只检查了命令名，没限制参数和子命令。后来加上参数白名单和超时上限，问题就没再出现。少一个限制，就可能多一个事故。

超时设置还要注意：同一命令在开发机和 CI 容器里的执行时间可能差 10 倍。建议超时值做成环境变量，方便不同环境调参。

五、总结

系统级 Agent 执行命令时，模型应该先申请，宿主再审查。白名单、参数解析、路径限制、超时、输出限制和审计日志，是最小安全边界。让 Agent 能做事之前，先让它不能乱做事。