AI Agent 怎么限制工具参数避免越权访问文件

AI Agent 能不能读写文件，安全边界不应该交给模型“自觉遵守”。更稳妥的做法是把工具设计成一个很窄的接口：模型只能提交动作、相对路径和必要内容；服务端固定工作区根目录，解析路径后再次检查边界，并把读、写、审批分成不同策略。这样即使提示词被诱导，../../etc/passwd、绝对路径或符号链接也会在文件 API 执行前被拒绝。

先把工具参数设计成最小权限接口

工具 Schema 是第一道边界，但它不是最终安全控制。以文件读取为例，参数可以只有 path；写入再增加 content，不要增加 root、is_admin、shell 之类由模型决定权限的字段。模型负责选择任务参数，服务端负责决定它能触碰哪些资源。

如果工具同时接受“读取文件”和“执行命令”，后续很难证明一次调用只影响了目标文件。更好的拆分是把工具能力做成独立函数，并在每个函数入口执行同一套参数规范化。OpenAI Agents SDK 的工具输入校验和工具级 guardrail 也体现了这个方向：检查应绑定到具体工具调用，而不能只依赖首轮输入或最后输出。

from pathlib import Path

class ToolDenied(Exception):
    """文件工具拒绝执行时使用的领域异常。"""

def safe_path(workspace: Path, raw_path: str) -> Path:
    """只返回工作区内的规范化路径。"""
    if not raw_path or Path(raw_path).is_absolute():
        raise ToolDenied("path 必须是非空相对路径")

    root = workspace.resolve()
    candidate = (root / raw_path).resolve()
    # resolve 后再判断，覆盖 .. 穿越和已存在符号链接。
    if candidate != root and root not in candidate.parents:
        raise ToolDenied("path 超出允许的工作区")
    return candidate

def read_file(workspace: Path, path: str) -> dict:
    """文件读取工具：只允许访问固定工作区。"""
    target = safe_path(workspace, path)
    if not target.is_file():
        return {"ok": False, "reason": "not-a-file"}
    # 限制读取大小，避免把大文件一次塞回上下文。
    content = target.read_text(encoding="utf-8")
    return {"ok": True, "path": str(target.relative_to(workspace.resolve())), "content": content[:200_000]}

def write_file(workspace: Path, path: str, content: str, approved: bool = False) -> dict:
    """文件写入工具：没有独立授权时只返回待审批状态。"""
    target = safe_path(workspace, path)
    if not approved:
        return {"ok": False, "reason": "approval-required", "path": path}
    # 写入前再次确认父目录仍在工作区内，并创建缺失目录。
    target.parent.mkdir(parents=True, exist_ok=True)
    target.write_text(content, encoding="utf-8")
    return {"ok": True, "path": str(target.relative_to(workspace.resolve()))}

这段示例的关键不是异常类名，而是“固定根目录、规范化后判断、工具内再次执行”。生产代码还应限制单文件大小、允许的扩展名和写入目录；若工作区中的链接目标可能在并发期间变化，则要把临时文件、打开方式和部署权限一起纳入设计。

边界校验要放在真正执行文件之前

只做 raw_path.startswith(str(workspace)) 这类字符串判断不够可靠。相对路径拼接后可能包含 ..，路径中也可能出现符号链接；正确顺序是拒绝绝对路径，基于固定根目录调用 resolve()，再用路径对象判断规范化结果是否仍位于根目录下。

工具策略还要区分资源动作。读文件可以自动执行，但写入、删除、移动和批量操作通常应返回审批请求，或只开放到一个专用输出目录。不要让模型通过额外参数把 approved 自己改成 true；示例中的审批值只是展示接口契约，真实系统应从服务端会话、人工确认或策略引擎注入。

拒绝消息也属于接口的一部分。建议至少区分 invalid-argument、outside-workspace、approval-required 和 operation-disabled。模型拿到结构化结果后可以改用安全的相对路径或向用户请求确认；如果统一返回“执行失败”，它可能继续猜参数，甚至把失败描述成已经完成。

用策略层和日志把越权调用变成可追踪事件

工具入口前可以再放一层策略对象，统一保存允许的动作、目录和审批要求。日志不要记录文件内容或密钥，只记录工具名、原始参数是否被拒绝、规范化后的相对路径、拒绝原因、会话标识和审批结果。这样既能定位误报，也能发现 Agent 是否反复尝试同一种越界写法。

对于 OpenAI Agents SDK 一类的框架，工具级输入 guardrail 适合做“调用前检查”，而工具实现内部的校验仍然必须保留，因为 hosted tool、外部服务或绕过 SDK 的调用路径不应天然获得本地文件权限。安全边界最终属于实际执行文件操作的服务，而不是提示词、工具描述或模型输出。

常见问题

只把允许目录写进系统提示词可以吗？

不可以。提示词能帮助模型选择正确参数，但不能阻止恶意输入、模型误判或其他调用方直接请求工具。工作区判断必须在服务端执行。

检查路径前缀为什么会误判？

因为字符串前缀没有表达路径层级，且无法处理 .. 和符号链接。应当先规范化，再用路径对象判断父子关系。

写工具一定要人工审批吗？

不一定，但要有独立策略。低风险的专用输出目录可以自动写入；覆盖已有文件、删除或跨目录移动应默认要求审批或直接关闭。

文件工具的安全设计可以归结为一句话：模型提交意图，服务端决定资源。把参数收窄、路径规范化、动作分级和结构化拒绝放在同一条调用链上，才能让“不能访问工作区外文件”成为可执行的约束。