你会遇到什么

这个工具解决什么问题：让 Agent 在沙箱里执行代码——本地/云端隔离执行，支持并行（SWE-agent 出品）。Agent 跑代码不再直接碰你的机器：swerex-remote 起沙箱执行服务器，agent 客户端连上去跑命令。 什么时候用：

• 你要给 Agent 一个隔离的代码执行环境（跑命令、跑测试）；
• 你要并行执行（沙箱隔离 + 并行）；
• 你要用 Python API 把沙箱接进自己的 Agent 流程（RemoteSandbox）。

什么时候别用：不需要隔离执行、直接本机跑就行时；或没有 Docker（沙箱执行依赖 Docker，本环境未实测沙箱运行）。 注意事项：重档条目——沙箱执行依赖 Docker；CLI/库层安装本身已实测，沙箱运行未实测（无 Docker 环境）。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

它怎么工作：pip 包 swe-rex 提供 swerex-remote CLI（沙箱执行服务器：--host/--port/--auth-token）+ Python 库 swerex（RemoteSandbox 客户端：host/port/auth_token → run("命令")）。先起服务器，客户端连接执行。 关键概念：

• swerex-remote：沙箱执行服务器（需 Docker + 认证 token）；
• RemoteSandbox：Python 客户端 API；
• auth-token：连接认证。

装完它动哪里：pip 环境；沙箱容器由 Docker 管理（需 Docker）。

一步步来

第 1 步：装包（为什么锁版本：1.4.0 为收录实测版本）

讲解：pip 安装（国内带清华镜像）。装完验证 CLI 参数面 + 库可导入——这两步本环境实测通过。

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple swe-rex==1.4.0
swerex-remote --help

预期输出: usage: swerex-remote [-h] [--host HOST] [--port PORT] --auth-token AUTH_TOKEN

python3 -c "import swerex; print('swerex OK')"

预期输出: swerex OK

装好确认：

• swerex-remote --help 输出服务器参数面；
• import swerex 不报错。

卡住怎么办：

• pip 慢 → 确认带清华镜像前缀；
• Python 版本 → 确认 >= 3.10。

第 2 步：启动沙箱执行服务器（需 Docker + 认证 token；本环境未实测沙箱运行）

讲解：swerex-remote --host 127.0.0.1 --port 8000 --auth-token <token> 启动。沙箱执行依赖 Docker——本环境无 Docker，未实测服务器运行；命令形态来自 --help。

swerex-remote --host 127.0.0.1 --port 8000 --auth-token <token>

预期输出: 服务器监听（供 agent 客户端连接执行代码）

装好确认：

• 服务器监听 127.0.0.1:8000（需 Docker 环境实测）。

卡住怎么办：

• 报 Docker 缺失 → 沙箱执行依赖 Docker（前置检查 docker-missing）；先装/启 Docker；
• 端口被占 → 换 --port。

第 3 步：Python API 接入（官方形态）

讲解：RemoteSandbox 客户端连服务器执行命令。需要第 2 步的服务器在跑；本环境未实测（无 Docker）。

python3 - <<'PY'
import asyncio
from swerex import RemoteSandbox
async def main:
sandbox = RemoteSandbox(host="127.0.0.1", port=8000, auth_token="<token>")
print(await sandbox.run("echo hi"))
asyncio.run(main)
PY

预期输出: hi（需先启动服务器；本环境未实测——无 Docker）

卡住怎么办：

• 连接被拒 → 先确认服务器已启动（第 2 步）且端口一致；
• token 不一致 → 服务器与客户端 auth-token 必须一致。

怎么确认修好了

第 1 步：确认包与导入面

讲解：swerex-remote --help 输出服务器参数面 + import swerex 不报错，说明安装与库链路通（本环境实测）。

swerex-remote --help
python3 -c "import swerex; print('swerex OK')"

预期输出: usage: swerex-remote [-h] [--host HOST] [--port PORT] --auth-token AUTH_TOKEN；swerex OK

卡住怎么办：

• 命令找不到 → venv 场景先激活 venv，确认 Python >= 3.10；
• import 失败 → 确认 pip 与 python3 同环境。

第 2 步：确认沙箱链路（需 Docker，本环境未实测）

讲解：服务器能监听 + 客户端 run("echo hi") 返回 hi，说明沙箱执行链路完整；沙箱执行依赖 Docker，无 Docker 会报 docker-missing。

swerex-remote --host 127.0.0.1 --port 8000 --auth-token <token>

预期输出: 服务器监听（供 agent 客户端连接执行代码）

python3 - <<'PY'
import asyncio
from swerex import RemoteSandbox
async def main:
sandbox = RemoteSandbox(host="127.0.0.1", port=8000, auth_token="<token>")
print(await sandbox.run("echo hi"))
asyncio.run(main)
PY

预期输出: hi（需先启动服务器；本环境无 Docker 未实测）

卡住怎么办：

• 报 Docker 缺失 → 先装/启 Docker（前置检查 docker-missing）；
• 连接被拒 / token 不一致 → 确认服务器已启动、端口与 auth-token 两边一致。

其它环境的表现（常见变体）

• 沙箱执行：依赖 Docker，容器由 Docker 管理；本环境无 Docker，服务器运行与沙箱执行如实标注未实测。
• 服务器形态：swerex-remote 是前台/托管进程，不需要时停止进程即可（无系统服务注册）。
• 写面：pip 环境 + Docker 容器，不写用户配置目录。
• 共装：与 code-review-graph / repomix 判定 possible-compatible——写面不重叠（沙箱容器 / 图数据 / 输出文件），共装未实测。

日常使用

启动与入口

• 服务器：swerex-remote --host ... --port ... --auth-token ...；
• 客户端：RemoteSandbox（Python API）。

常用操作

操作一：查看 CLI 面（本环境实测）

swerex-remote --help

预期输出: 服务器参数面（--host/--port/--auth-token）

操作二：验证库可导入（本环境实测）

python3 -c "import swerex; print('swerex OK')"

预期输出: swerex OK

操作三：启动沙箱执行服务器（需 Docker + 认证 token；本环境未实测沙箱运行）

swerex-remote --host 127.0.0.1 --port 8000 --auth-token <token>

预期输出: 服务器监听（供 agent 客户端连接执行代码）

操作四：Python API 接入（官方形态）

python3 - <<'PY'
import asyncio
from swerex import RemoteSandbox
async def main:
sandbox = RemoteSandbox(host="127.0.0.1", port=8000, auth_token="<token>")
print(await sandbox.run("echo hi"))
asyncio.run(main)
PY

预期输出: hi（需先启动服务器；本环境未实测——无 Docker）

数据与目录

• pip 环境；沙箱容器由 Docker 管理（容器镜像/数据在 Docker 侧）。

卸载与清理

note: pip 包自动卸载（幂等）；沙箱容器按需清理

pip uninstall -y swe-rex 2>/dev/null || true
command -v swerex-remote >/dev/null 2>&1 && echo '残留: swerex-remote 仍存在' || echo 'swe-rex removed: OK'

预期输出: swe-rex removed: OK

依赖警告

• 版本：[1.4.0, 1.4.0] 锁定（收录实测版本；release v1.4.0 无独立资产，分发走 PyPI）。
• 环境：Python >= 3.10；沙箱执行需 Docker（本环境未实测沙箱运行）。
• 网络：pip 用清华镜像（国内实测路径）。
• 写面：pip 环境；沙箱容器由 Docker 管理。
• 后台进程：swerex-remote 为服务器形态（前台/托管进程）。
• 共装：与 code-review-graph / repomix 判定 possible-compatible——写面不重叠（沙箱容器 / 图数据 / 输出文件），共装未实测。

FAQ（常见问题）

• 问：没有 Docker 能用吗？答：安装与 CLI/库冒烟可以（本环境实测）；沙箱执行（swerex-remote 起服务器）依赖 Docker，未实测。
• 问：服务器怎么停？答：前台进程 Ctrl+C，或托管进程管理（systemd 等）。
• 问：auth-token 是什么？答：连接认证令牌，自己生成（如 openssl rand -hex 16）；服务器与客户端要一致。
• 问：和 repomix / code-review-graph 一起装？答：判定 possible-compatible——写面不重叠（沙箱容器 / 输出文件 / 图数据），共装未实测。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。