Agent生成并执行Python代码的场景越来越多，比如数据分析助手、自动化脚本工具、代码解释器插件。如果不做任何隔离，直接调用系统Python，生成代码中的os.remove、shutil.rmtree、subprocess.run都可能对宿主机造成破坏。因此需要构建一个受控的执行环境，这个环境必须包含独立的解释器、受限的沙箱、明确的依赖白名单和可靠的超时机制。下面从这几个方面依次展开。
解释器选型与虚拟环境隔离
系统自带的Python解释器往往被操作系统或其他工具依赖，版本升级、包卸载都可能影响系统稳定性。Agent执行代码时如果直接使用系统Python，安装的第三方库会污染全局site-packages目录，不同任务之间的依赖冲突也会频繁出现。因此第一步是创建一个独立的虚拟环境。使用venv模块是最简单的方式，它可以复制一份解释器链接并建立独立的包安装目录。在Windows下创建虚拟环境并安装常用库的命令如下：
python -m venv agent_env agent_env\Scripts\python.exe -m pip install pandas numpy requests
虚拟环境解决的是Python包层面的隔离，它不会限制文件访问、网络连接或进程创建。但它为后续沙箱提供了干净的依赖基础。Agent调用代码时应该明确指定这个虚拟环境里的解释器路径，而不是依赖PATH环境变量。PATH可能被用户或其他进程修改，导致实际执行的解释器并非预期版本。比较稳妥的做法是在配置文件中写入解释器的绝对路径，例如Linux下的/home/agent/agent_env/bin/python，Windows下的C:\agent_env\Scripts\python.exe。注意Windows路径中的反斜杠要保留，程序读取时不会因为正斜杠或反斜杠的混用而出错。
如果Agent需要同时运行多个不同依赖需求的任务，可以为每个任务创建独立的虚拟环境，或者使用conda这类环境管理工具。conda不仅能隔离Python包，还能管理非Python依赖，例如某些科学计算库需要的底层C库。但conda体积较大，启动速度慢，对于轻量级Agent可能不是最佳选择。实际项目中常见做法是：基础环境用venv保持精简，遇到特殊依赖时再单独构建conda环境或Docker镜像。无论哪种方式，解释器路径都需要在Agent配置中显式声明，并且定期检查环境完整性，避免缺少关键包导致代码执行失败。
subprocess封装与超时控制
Agent通常通过subprocess模块来调用Python解释器执行代码。直接使用subprocess.run虽然方便，但如果不加限制，一段包含while True的死循环代码会让整个Agent进程卡住。subprocess.run提供了timeout参数，当子进程运行超过指定秒数后会抛出TimeoutExpired异常。不过仅仅设置timeout还不够，因为子进程可能再启动孙进程，超时后只杀掉了直接子进程，孙进程会继续在后台运行。为避免这种情况，可以在创建子进程时设置start_new_session=True，让子进程成为新会话的领导者，超时后通过os.killpg杀死整个进程组。
import subprocess
import os
import signal
def run_code(code: str, timeout: int = 10, cwd: str = None):
try:
proc = subprocess.run(
[r"C:\agent_env\Scripts\python.exe", "-c", code],
capture_output=True,
text=True,
timeout=timeout,
cwd=cwd,
start_new_session=True
)
return proc.stdout, proc.stderr, proc.returncode
except subprocess.TimeoutExpired:
return "", "execution timeout", -1上面的封装函数还把标准输出和标准错误分开返回，便于Agent判断执行结果。capture_output=True会把输出缓存在内存中，如果代码输出量巨大，可能撑爆Agent进程的内存。更稳妥的做法是限制输出大小，可以使用subprocess.Popen并手动读取管道，对输出长度做截断。比如只读取前10KB内容，超过后直接终止子进程。这样既能拿到必要的执行反馈，又不至于因为大量日志导致Agent自身崩溃。
超时控制还需要考虑不同任务的执行时间差异。数据分析任务可能跑几秒钟，机器学习训练可能需要几分钟。Agent可以根据任务类型设置不同的超时阈值，或采用动态超时策略：先执行一个轻量级检查代码，估算运行时间，再设置实际执行超时。但这会增加复杂度。至少要做到默认超时不可过长，比如10到30秒，并且允许用户手动终止执行。同时要记录每次执行的时间和输出，便于之后做审计和优化。
沙箱隔离与权限限制
虚拟环境和超时控制无法阻止恶意代码删除文件或者访问内网。比如代码中写入shutil.rmtree('/')，如果解释器拥有足够权限，宿主机数据会被清空。因此需要更严格的沙箱隔离。Docker是目前应用最广泛的方案，它利用Linux命名空间和cgroup实现进程、文件系统、网络、内存、CPU的隔离。一条典型的Docker执行命令如下：
docker run --rm --network none --memory 512m --cpus 1 -v /tmp/agent_work:/workspace:rw python:3.11 python -c "print('hello')"这条命令中，--network none禁用网络，--memory 512m限制内存上限为512MB，--cpus 1限制最多使用一个CPU核心，-v只把宿主机/tmp/agent_work目录挂载到容器/workspace，并且允许读写。这样即使代码执行rm -rf /，删除的也只是容器内部的根目录，宿主机不受影响。而且容器本身是临时的，--rm参数会在退出后自动清理，避免残留进程或文件。
对于不想依赖Docker的场景，Linux下还可以使用bubblewrap或firejail等轻量级沙箱工具。它们不需要完整容器运行时，直接利用内核特性创建受限命名空间。例如bubblewrap可以指定只读根文件系统、临时tmpfs和受限的设备访问。不过这些工具配置相对复杂，跨平台兼容性差。如果Agent部署在Windows或macOS上，可以考虑使用虚拟机或云函数执行环境。云函数天然提供隔离和资源限制，但会增加网络延迟和成本。总体来看，Docker是平衡安全性与易用性的主流选择。
沙箱内部还需要注意文件系统权限。即使挂载了工作目录，也建议以非root用户运行容器，并在工作目录上设置合适的读写权限。Dockerfile中可以创建一个专用用户，例如：
FROM python:3.11-slim RUN useradd -m agent USER agent WORKDIR /workspace
这样容器内进程默认以agent用户身份运行，对系统目录只有读权限，无法修改系统配置。如果代码尝试写入/etc或/usr等目录，会因为权限不足而失败。结合只读挂载和临时目录，可以进一步缩小攻击面。
依赖管理与白名单策略
Agent执行代码需要第三方库，但每次都在沙箱里pip install会带来两个问题：一是安装过程可能被篡改或安装恶意依赖，二是网络下载耗时影响执行效率。比较合理的做法是在构建沙箱镜像或虚拟环境时，预先安装好一组经过审核的常用库。例如数据分析任务可以预装pandas、numpy、matplotlib，网络请求任务预装requests、httpx。这样代码运行时不再需要临时安装，依赖也处于可控状态。
仅预装还不够，还需要对代码中导入的模块做白名单校验。可以用Python的ast模块静态解析代码，检查所有import语句是否命中允许列表。下面是一个简单的校验函数：
import ast
ALLOWED_MODULES = {"pandas", "numpy", "math", "json", "requests"}
def check_imports(code: str) -> bool:
try:
tree = ast.parse(code)
except SyntaxError:
return False
for node in ast.walk(tree):
if isinstance(node, ast.Import):
for alias in node.names:
if alias.name.split(".")[0] not in ALLOWED_MODULES:
return False
elif isinstance(node, ast.ImportFrom):
if node.module and node.module.split(".")[0] not in ALLOWED_MODULES:
return False
return True这个函数只检查导入的顶层模块名，例如import pandas没问题，import os则会被拒绝。它不能防止通过importlib动态导入，但可以拦截大部分常规代码。对于动态导入和内置危险函数，需要在沙箱层面做更深入的限制。例如可以使用seccomp过滤系统调用，或者使用RestrictedPython等受限执行库。不过RestrictedPython会限制很多Python特性，可能无法满足复杂任务需求，需要根据实际场景权衡。
依赖白名单之外，还应禁止代码访问危险的内置函数。eval、exec、compile、open、__import__等函数经常被用来绕过限制。虽然可以在执行前用AST扫描函数调用名称，但Python的动态特性让静态分析难以完全覆盖。更可靠的方式是在沙箱中运行代码，即使代码调用了open，也只能访问沙箱内挂载的文件，无法触及宿主机。因此依赖管理与沙箱隔离需要配合使用，单靠任何一层都不够安全。
最后，Agent执行代码的环境配置不是一次性的工作。随着任务类型增加和依赖变化，需要定期更新白名单和预装库。每次执行代码时记录日志，包括代码内容、执行时长、退出码和输出摘要，后续可以分析异常调用模式，及时调整安全策略。只有把解释器隔离、执行封装、沙箱限制、依赖管理四个层面都落实到位，Agent才能真正成为一个稳定可控的代码执行工具，而不是一个潜在的系统后门。
Python代码解释器Agent环境配置沙箱隔离修改时间：2026-09-24 15:26:03