mini-swe-agent SWE-ReX Docker 环境实战指南：用 SWE-ReX 沙箱化 Docker 执行运行 SWE-bench 评测

mini-swe-agent 通过 SwerexDockerEnvironment（配置名 swerex_docker）提供了一条基于 SWE-ReX 的 Docker 沙箱执行路径：与自带的 DockerEnvironment 直接调用 docker exec 不同，它委托 SWE-ReX 的 DockerDeployment 管理容器生命周期与命令执行，适合在 SWE-bench 等需要隔离、可并行的评测场景中使用。读完本文，你将掌握该环境类的配置参数、源码级执行流程、与原生 Docker 环境的差异，以及如何在 YAML 配置和命令行中启用它。

一、SWE-ReX Docker 环境在 mini-swe-agent 中的定位

在 mini-swe-agent 中，环境（Environment）是真正执行模型生成代码的组件。官方文档 Environment classes 明确指出：mini CLI 默认使用 local 环境在本机执行，但评测 SWE-bench 时必须运行在隔离环境中。为此，项目在 environments/init.py 中注册了多条后端路径：

• docker（DockerEnvironment）— 直接用 docker exec 执行命令；
• singularity（SingularityEnvironment）— 面向无 Docker 的 HPC 场景；
• swerex_docker（SwerexDockerEnvironment）— 通过 SWE-ReX 管理 Docker 执行；
• swerex_modal（SwerexModalEnvironment）— 通过 SWE-ReX 在 Modal 云端执行；
• bubblewrap、contree — 其他沙箱方案。

其中 swerex_docker 与 swerex_modal 同属"基于 SWE-ReX 的进阶环境"，位于 environments/extra/ 目录。模块 environments/README.md 的说明为：extra/swerex_docker.py — Execute environments with docker via swerex。

选择环境的入口在 get_environment_class()：支持字符串映射（如 swerex_docker）或完整模块路径，未知类型会抛出 ValueError。而 get_environment() 则从配置中弹出 environment_class 键并据此实例化环境，这意味着你既可以在 CLI 传 --environment-class，也可以在 YAML 配置的 environment.environment_class 中声明。

二、依赖安装与前置条件

SwerexDockerEnvironment 直接导入并实例化 SWE-ReX 的 DockerDeployment（见 swerex_docker.py），因此必须安装 SWE-ReX 库。在 pyproject.toml 中，swe-rex>=1.4.0 被声明为 full 可选依赖组的一部分，同时 dev 组也包含 swe-rex（pyproject.toml）。

推荐安装方式：

pip install "mini-swe-agent[full]"

运行前提：

• 本机可用 Docker（或 podman 别名到 docker）；
• 目标镜像已可拉取（首次启动时 SWE-ReX 负责拉取镜像）；
• 需要网络与足够的容器权限。

测试模块 test_swerex_docker.py 中有一段环境可用性探测逻辑，可作为自检命令：执行 docker version 并在 5 秒内成功返回即视为 Docker 可用；两个测试用例均以 @pytest.mark.slow 标记并在此条件下跳过，说明该环境需要真实 Docker 守护进程才能验证。

三、配置类 SwerexDockerEnvironmentConfig 参数详解

SwerexDockerEnvironment 在初始化时将所有关键字参数交给 SwerexDockerEnvironmentConfig（基于 Pydantic BaseModel）校验，可用参数如下：

参数	类型	默认值	说明
image	str	无（必填）	要运行的 Docker 镜像，例如 python:3.11
cwd	str	"/"	容器内执行命令的工作目录
timeout	int	30	单条命令在容器内的执行超时（秒）
deployment_extra_kwargs	dict[str, Any]	{}	透传给 SWE-ReX DockerDeployment 的额外关键字参数

关键点：

• image 是唯一必填项。它是构造 DockerDeployment 的第一个位置参数（swerex_docker.py），测试中使用的 python:3.11 即典型取值。
• deployment_extra_kwargs 是扩展口。SWE-ReX DockerDeployment 支持如端口、日志配置、运行时选项等更多参数，mini-swe-agent 不做拦截，全部透传，因此想定制容器行为时应优先利用该字段，而不是修改本模块。
• cwd 与 timeout 均可被单次执行覆盖，见下文 execute() 的签名。

四、核心执行流程：从 action 到容器输出的完整链路

SwerexDockerEnvironment 的主体逻辑非常精简（整个文件约 80 行），核心是 __init__、execute、_check_finished、get_template_vars、serialize 五个方法。

4.1 初始化：启动部署

init 完成两件事：

1. 用传入关键字参数构建 SwerexDockerEnvironmentConfig；
2. 构造 DockerDeployment(image=self.config.image, **self.config.deployment_extra_kwargs) 并 asyncio.run(self.deployment.start()) 同步启动容器。

值得注意：这里使用 asyncio.run 包装 SWE-ReX 的异步 API，保证环境类的接口对调用方保持同步、易用。与原生 DockerEnvironment 自行拼装 docker run -d ... 命令并用 subprocess 启动容器（见 docker.py）相比，容器生命周期完全交由 SWE-ReX 管理，这是两者最本质的区别。

4.2 execute：执行单条命令并归一化输出

execute(action, cwd="", *, timeout=None) 是环境的核心接口，输入是一个 dict（约定含 command 键），输出是统一结构的 dict：

• 从 action.get("command", "") 取出命令；
• 构造 SWE-ReX 的 RexCommand(command=..., shell=True, check=False, cwd=cwd or config.cwd, timeout=timeout or config.timeout, merge_output_streams=True)；
• 通过 deployment.runtime.execute(...) 执行并取回 stdout 与 exit_code；
• 成功时返回 {"output": result.stdout, "returncode": result.exit_code, "exception_info": ""}；
• 任何异常时返回 {"output": 错误文本, "returncode": -1, "exception_info": "An error occurred while executing the command: ...", "extra": {"exception_type": ..., "exception": ...}}。

几个实现细节对使用有直接影响：

• shell=True：命令由容器内 shell 解释，支持管道、重定向等复合命令；
• check=False：命令非零退出码不会被当成异常，而是如实记录在 returncode 中，这与原生 DockerEnvironment 的行为一致；
• merge_output_streams=True：stdout 与 stderr 合并输出，便于模型一次性看到完整结果；
• cwd 与 timeout 的可选覆盖：调用方传入非空 cwd 或 timeout 时会覆盖配置默认值。

4.3 任务提交哨兵：COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT

_check_finished 与原生 DockerEnvironment._check_finished 逻辑完全一致：若输出首行（去除左侧空白后）恰为 COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT 且返回码为 0，则把剩余行作为最终提交内容，抛出 Submitted 异常，中断 agent 循环。这正是 SWE-bench 类任务的标准提交协议——SWE-bench 评测模板要求模型用 echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT && cat patch.txt 提交补丁（见 swebench.yaml），本环境会在命令输出的第一行识别到该哨兵后自动截取补丁内容。

4.4 模板变量与序列化

• get_template_vars：用 recursive_merge 将配置字典与额外 kwargs 合并，供 agent 系统模板/实例模板渲染使用；
• serialize：输出包含完整配置（JSON 序列化）与 environment_type（模块路径.类名）的 info 结构，用于结果记录与复现。

五、与原生 DockerEnvironment 的对比与选型

两个环境在 mini-swe-agent 中都能在 Docker 容器里执行 bash，但架构取舍不同：

维度	DockerEnvironment	SwerexDockerEnvironment
源码位置	docker.py	extra/swerex_docker.py
容器管理	自行拼 docker run -d/docker exec，subprocess 调用	委托 SWE-ReX DockerDeployment.start()
配置项	image、cwd、env、forward_env、timeout、executable、run_args、container_timeout、pull_timeout、interpreter	image、cwd、timeout、deployment_extra_kwargs
扩展点	直接改 run_args、interpreter 等	通过 deployment_extra_kwargs 透传 SWE-ReX
环境变量注入	env/forward_env	无直接参数，需经 deployment_extra_kwargs

选型建议：

• 需要轻量、零额外依赖、直接掌控容器命令细节 → 用 docker；
• 已在 SWE-ReX 生态（如与 swerex_modal 共用同一套运行时语义）或希望复用 SWE-ReX 的部署能力 → 用 swerex_docker；
• 需要远程/大规模并行 → 考虑 swerex_modal（需 Modal 账号，见 swerex_modal.md）。

六、在配置与命令行中启用 swerex_docker

选择环境有两种等价方式（见 environments.md）：

1. CLI 参数：--environment-class swerex_docker
2. YAML 配置：在 agent 配置文件的 environment: 段设置 environment_class: swerex_docker

示例配置片段（仿照 swebench.yaml 中 environment 段的组织方式）：

environment:
  environment_class: swerex_docker
  image: python:3.11
  cwd: "/testbed"
  timeout: 60
  deployment_extra_kwargs:
    # 例如：启用 SWE-ReX 部署层面的自定义选项
    {}

命令行示例（评测 SWE-bench，参考 swerex_modal.md 中 mini-extra swebench 的调用模式）：

mini-extra swebench \
    --environment-class swerex_docker \
    --subset verified \
    --split test \
    -o ./results/mini-swerex-docker

七、测试验证：如何在本地确认该环境可用

仓库提供了两个针对本环境的集成测试（test_swerex_docker.py），可直接验证：

pytest tests/environments/extra/test_swerex_docker.py -m slow

• test_swerex_docker_basic_execution：用 python:3.11 镜像启动环境并执行 echo 'hello world'，断言返回码为 0 且输出包含该字符串；
• test_swerex_docker_command_failure：执行 exit 1，断言返回码正确捕获为 1（验证 check=False 语义）。

两个用例都要求 Docker 可用，否则以 skip 处理。运行前请确认本机 docker version 可正常返回。

八、注意事项与限制

• 依赖限制：必须安装 swe-rex>=1.4.0（mini-swe-agent[full] 已包含），否则模块导入即失败；
• 同步包装：execute() 内部用 asyncio.run 驱动 SWE-ReX 异步 API，请勿在已运行的 asyncio 事件循环中直接调用，避免嵌套事件循环冲突（从源码结构看，该环境面向评测脚本这类同步调用方设计）；
• 哨兵协议：若业务命令输出恰好以 COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT 开头且返回码为 0，会触发提交中断逻辑，设计业务命令时应避免该前缀；
• 环境变量：与 DockerEnvironment 不同，本环境没有 env/forward_env 参数，注入环境变量需通过 deployment_extra_kwargs 借助 SWE-ReX 的部署选项实现；
• 文档参考：官方参考页 swerex_docker.md 与进阶说明 environments.md 可作为进一步查阅入口。