# SWE-agent 代码修复器

## 概览

[SWE-agent](https://github.com/SWE-agent/SWE-agent) 是一个由 AI 驱动的软件工程代理， **通过让语言模型通过终端界面与代码仓库交互来自动解决 GitHub 问题** 呈现在 **NeurIPS 2024** 并且拥有超过 **15,000 个 GitHub 星标**，SWE-agent 已成为用于自动修复漏洞和代码修复的领先开源解决方案。

与本档档中大多数工具不同，SWE-agent **不需要 GPU** —— 它调用外部大模型 API（Claude、GPT-4、Gemini，或自托管模型）来推理代码并生成修复。它 *确实* 需要的是一个可靠的 Docker 环境用于安全的沙箱式代码执行。Clore.ai 的 CPU 服务器（或任何带 Docker 的租用实例）非常适合。

**主要功能：**

* 🐛 使用单个命令自动解决 GitHub 问题
* 🔒 在 Docker 容器内进行沙箱式执行 —— 可安全运行任意代码
* 🤖 支持 Claude、GPT-4、Gemini、兼容 OpenAI 的以及本地模型
* 🌐 用于监控代理进度的 Web 界面
* 🛡️ 用于 CTF 挑战和渗透测试的网络安全模式
* 📊 与 SWE-bench 兼容 —— 在 300+ 个真实 GitHub 问题上进行了测试
* 🔧 通过 YAML 配置文件可配置代理行为

***

## 要求

### 硬件要求

SWE-agent 不需要 GPU —— 它使用基于 API 的大模型来进行推理：

| 方案          | CPU     | 内存    | 存储         | Clore.ai 价格 |
| ----------- | ------- | ----- | ---------- | ----------- |
| **最低**      | 4 核     | 8 GB  | 30 GB SSD  | 约 $0.03/小时  |
| **推荐**      | 8 核     | 16 GB | 60 GB SSD  | 约 $0.06/小时  |
| **高负载**     | 16 核    | 32 GB | 100 GB SSD | 约 $0.10/小时  |
| **使用本地大模型** | GPU 服务器 | 32 GB | 100 GB SSD | \~$0.20/小时  |

> 💡 **成本提示：** SWE-agent 在 Clore.ai 上运行出奇地便宜，因为你不需要 GPU。主要成本是大模型 API 调用（例如 Claude Sonnet 约 $0.003/1K tokens）。典型的问题修复在 API 费用上花费约 $0.50–$2.00。

### 软件与 API 要求

| 要求               | 详细信息                         |
| ---------------- | ---------------------------- |
| **已预装 Docker**   | 沙箱代码执行所需                     |
| **大模型 API 密钥**   | Anthropic、OpenAI、Google，或自托管 |
| **GitHub 令牌**    | 用于访问私有仓库和创建 PR               |
| **Python 3.11+** | 用于 `pip install sweagent` 方法 |

### 大模型 API 定价参考

| A100            | 输入              | 输出              | 典型运行成本              |
| --------------- | --------------- | --------------- | ------------------- |
| Claude Sonnet 4 | $3/百万 tokens    | $15/百万 tokens   | 约 $1.00–$2.00       |
| GPT-4o          | $5/百万 tokens    | $15/百万 tokens   | 约 $1.00–$3.00       |
| GPT-4o mini     | $0.15/百万 tokens | $0.60/百万 tokens | 约 $0.05–$0.20       |
| Ollama（本地）      | 免费              | 免费              | 仅需支付 Clore.ai 的小时费用 |

***

## 快速开始

### 步骤 1 — 在 Clore.ai 上租用服务器

1. 登录到 [clore.ai](https://clore.ai)
2. 筛选： **启用 Docker** —— GPU 可选（CPU 服务器即可）
3. 推荐镜像： `ubuntu:22.04` 或任何支持 Docker 的镜像
4. 打开端口： **22** （SSH）， **7860** （SWE-agent Web 界面）
5. 建议至少 16 GB 内存以运行 Docker-in-Docker

### 步骤 2 — 通过 SSH 连接

```bash
ssh -p <CLORE_SSH_PORT> root@<CLORE_SERVER_IP>

# 验证 Docker 是否可用
docker --version
docker run --rm hello-world
```

### 步骤 3 — 拉取 SWE-agent Docker 镜像

```bash
# 拉取官方 SWE-agent 镜像（预构建，推荐）
docker pull sweagent/swe-agent:latest

# 验证
docker images | grep sweagent
```

或者，从源码构建以获取最新开发版本：

```bash
git clone https://github.com/SWE-agent/SWE-agent.git
cd SWE-agent
docker build -t sweagent/swe-agent:local .
```

### 步骤 4 — 设置 API 密钥

```bash
# 为 SWE-agent 配置创建目录
mkdir -p /workspace/sweagent && cd /workspace/sweagent

# 使用你的 API 密钥创建环境文件
cat > /workspace/sweagent/.env << 'EOF'
# 大模型 API 密钥（仅添加你拥有的）
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...

# 用于访问仓库和创建 PR 的 GitHub 令牌
GITHUB_TOKEN=ghp_...

# 可选：自托管大模型端点
# OPENAI_BASE_URL=http://your-ollama-server:11434/v1
EOF

chmod 600 /workspace/sweagent/.env
```

### 步骤 5 — 修复你的第一个 GitHub 问题

```bash
# 基本用法 —— 使用 Claude Sonnet 修复一个 GitHub 问题
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /workspace/sweagent/output:/output \
  -v /var/run/docker.sock:/var/run/docker.sock \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=claude-sonnet-4-20250514 \
    --agent.model.per_instance_cost_limit=2.00 \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/1 \
    --actions.apply_patch_locally=true \
    --output_dir=/output
```

### 步骤 6 — 查看输出

```bash
# SWE-agent 将结果写入输出目录
ls -la /workspace/sweagent/output/

# 查看生成的补丁
cat /workspace/sweagent/output/*.patch

# 查看完整的代理轨迹（代理做了什么）
cat /workspace/sweagent/output/*.traj | python3 -m json.tool | less
```

***

## 配置

### 基本配置文件

不要使用冗长的命令行参数，请使用 YAML 配置：

```bash
cat > /workspace/sweagent/config.yaml << 'EOF'
# SWE-agent 配置
agent:
  model:
    name: claude-sonnet-4-20250514
    per_instance_cost_limit: 2.00
    total_cost_limit: 10.00
    temperature: 0.0
  config:
    # 代理的系统提示
    system_template: "default"
    # 在 API 错误时重试的次数
    retry_with_output_if_run_fails: true

env:
  repo:
    # 将按运行时设置
    github_url: ""
  deployment:
    docker_args:
      - "--memory=4g"
      - "--cpus=2"

problem_statement:
  github_url: ""

actions:
  apply_patch_locally: true
  open_pr: false  # 设置为 true 以自动创建 PR

output_dir: /output
EOF
```

```bash
# 使用配置文件运行
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /workspace/sweagent/output:/output \
  -v /workspace/sweagent/config.yaml:/config.yaml \
  -v /var/run/docker.sock:/var/run/docker.sock \
  sweagent/swe-agent:latest \
  python run.py \
    --config /config.yaml \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/42
```

### Web UI 模式

SWE-agent 包含基于 Gradio 的 Web 界面以供交互使用：

```bash
# 启动 Web 界面
docker run -d \
  --name sweagent-ui \
  --env-file /workspace/sweagent/.env \
  -p 7860:7860 \
  -v /workspace/sweagent/output:/output \
  -v /var/run/docker.sock:/var/run/docker.sock \
  sweagent/swe-agent:latest \
  python app.py --port 7860 --host 0.0.0.0

# 访问界面
echo "打开： http://<CLORE_SERVER_IP>:<MAPPED_PORT>"
docker logs -f sweagent-ui
```

### 使用不同的大模型提供商

```bash
# GPT-4o（OpenAI）
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /workspace/sweagent/output:/output \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=gpt-4o-2024-11-20 \
    --agent.model.per_instance_cost_limit=3.00 \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/1

# GPT-4o Mini（预算选项）
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /workspace/sweagent/output:/output \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=gpt-4o-mini-2024-07-18 \
    --agent.model.per_instance_cost_limit=0.50 \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/1

# 本地 Ollama（配合 Ollama 指南使用）
# 首先在 GPU 服务器上部署 Ollama（参见 ../language-models/ollama.md）
# 然后将其用作 SWE-agent 的后端：
docker run --rm \
  -e OPENAI_API_KEY=dummy \
  -e OPENAI_BASE_URL=http://<OLLAMA_HOST>:11434/v1 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /workspace/sweagent/output:/output \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=qwen2.5-coder:32b \
    --agent.model.per_instance_cost_limit=0.00 \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/1
```

### 批量处理多个问题

```bash
# 使用 SWE-bench 格式处理多个问题
cat > /workspace/sweagent/batch_issues.json << 'EOF'
[
  {
    "repo": "USER/REPO",
    "issue_number": 1,
    "model": "claude-sonnet-4-20250514"
  },
  {
    "repo": "USER/REPO",
    "issue_number": 2,
    "model": "claude-sonnet-4-20250514"
  }
]
EOF

# 批量运行脚本
cat > /workspace/sweagent/run_batch.sh << 'BASH'
#!/bin/bash
set -e

ISSUES_FILE="${1:-/workspace/sweagent/batch_issues.json}"
OUTPUT_DIR="/workspace/sweagent/output"
ENV_FILE="/workspace/sweagent/.env"

echo "开始批量 SWE-agent 运行..."
python3 -c "
import json
issues = json.load(open('$ISSUES_FILE'))
for i, issue in enumerate(issues):
    print(f'Issue {i+1}/{len(issues)}: {issue[\"repo\"]}#{issue[\"issue_number\"]}')
" 

jq -c '.[]' "$ISSUES_FILE" | while read issue; do
    REPO=$(echo "$issue" | jq -r '.repo')
    ISSUE_NUM=$(echo "$issue" | jq -r '.issue_number')
    MODEL=$(echo "$issue" | jq -r '.model')

    echo "=== 处理： $REPO#$ISSUE_NUM 使用 $MODEL ==="
    
    docker run --rm \
      --env-file "$ENV_FILE" \
      -v "$OUTPUT_DIR:/output" \
      -v /var/run/docker.sock:/var/run/docker.sock \
      sweagent/swe-agent:latest \
      python run.py \
        --agent.model.name="$MODEL" \
        --agent.model.per_instance_cost_limit=2.00 \
        --env.repo.github_url="https://github.com/$REPO" \
        --problem_statement.github_url="https://github.com/$REPO/issues/$ISSUE_NUM" \
        --output_dir=/output || echo "失败： $REPO#$ISSUE_NUM"
done

echo "批量完成。结果位于 $OUTPUT_DIR"
BASH

chmod +x /workspace/sweagent/run_batch.sh
/workspace/sweagent/run_batch.sh
```

***

## Docker-in-Docker 设置

SWE-agent 在嵌套的 Docker 容器中运行代码以保证安全。这需要对 Docker socket 的访问：

```bash
# 验证 Docker socket 是否可访问
ls -la /var/run/docker.sock

# 测试 Docker-in-Docker 是否工作
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker:latest docker run --rm hello-world

# SWE-agent 将自动拉取其沙箱镜像
# 默认沙箱： sweagent/swe-agent:latest（或专门的环境镜像）
```

### 安全注意事项

```bash
# SWE-agent 沙箱资源限制（在你的 YAML 中配置）
cat >> /workspace/sweagent/config.yaml << 'EOF'
env:
  deployment:
    docker_args:
      - "--memory=4g"          # 限制沙箱内存
      - "--cpus=2"             # 限制沙箱 CPU
      - "--network=bridge"     # 隔离网络
      - "--read-only"          # 只读文件系统（有例外）
      - "--tmpfs=/tmp:size=1g" # 仅 /tmp 可写
EOF

# 切勿直接在宿主机上运行 SWE-agent —— 始终使用 Docker
# 沙箱容器隔离潜在有害代码
```

### 使用预构建的环境镜像

```bash
# SWE-agent 支持针对每个仓库的自定义环境镜像
# 这通过预装依赖加快运行速度
cat > /workspace/sweagent/env-config.yaml << 'EOF'
env:
  deployment:
    image: sweagent/swe-agent:latest
    pre_install:
      - "pip install -e ."
      - "pip install pytest"
    post_clone:
      - "git config --global user.email 'agent@sweagent.ai'"
      - "git config --global user.name 'SWE-agent'"
EOF
```

***

## 提示与最佳实践

### 🎯 编写有效的问题描述

SWE-agent 修复的质量在很大程度上取决于问题描述的质量：

````bash
# 方法 1：使用 GitHub 问题 URL（推荐）
--problem_statement.github_url=https://github.com/USER/REPO/issues/42

# 方法 2：提供包含详细描述的文本文件
cat > /workspace/sweagent/issue.txt << 'EOF'
## 错误描述
函数 `calculate_total()` 在 `billing/calculator.py` 中返回 0 
当折扣恰好为 100% 时。 

## 重现步骤
```python
total = calculate_total(price=100, discount=100)
assert total == 0  # 这会失败，返回 100 而不是 0
````

## 期望行为

当折扣为 100% 时应返回 0。

## 相关代码

参见 `billing/calculator.py` 第 45-67 行。EOF

docker run --rm\
\--env-file /workspace/sweagent/.env\
-v /workspace/sweagent/output:/output\
-v /workspace/sweagent/issue.txt:/issue.txt\
-v /var/run/docker.sock:/var/run/docker.sock\
sweagent/swe-agent:latest\
python run.py\
\--agent.model.name=claude-sonnet-4-20250514\
\--env.repo.github\_url=<https://github.com/USER/REPO\\>
\--problem\_statement.text\_file=/issue.txt

````

### 💰 成本控制

```bash
# 始终设置每实例成本上限
--agent.model.per_instance_cost_limit=2.00  # 每个问题最多 $2

# 对初步分诊使用 GPT-4o mini，复杂修复使用 Claude
# 预算策略：约 $0.10 用于扫描，约 $1.50 用于修复

# 实时监控成本
docker logs -f sweagent-ui | grep -E "(cost|tokens|spent)"

# 为所有运行设置总预算
--agent.model.total_cost_limit=20.00  # 超过 $20 则停止所有运行
````

### 🔄 自动创建 PR

```bash
# 自动用修复创建拉取请求
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /workspace/sweagent/output:/output \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=claude-sonnet-4-20250514 \
    --agent.model.per_instance_cost_limit=2.00 \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/42 \
    --actions.open_pr=true \
    --actions.push_gh_repo_url=https://github.com/USER/REPO
```

### 📊 SWE-bench 评估

```bash
# 在官方 SWE-bench 基准上运行 SWE-agent
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /workspace/sweagent/output:/output \
  sweagent/swe-agent:latest \
  python run_batch.py \
    --agent.model.name=claude-sonnet-4-20250514 \
    --env.repo.github_url=https://github.com/USER/REPO \
    --instances.type=swe_bench \
    --instances.subset=lite \
    --instances.split=test \
    --output_dir=/output \
    --num_workers=4
```

### 🛡️ 网络安全模式

```bash
# SWE-agent 支持 CTF 和网络安全挑战
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /workspace/sweagent/output:/output \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=claude-sonnet-4-20250514 \
    --agent.config=config/default_from_url_ctf.yaml \
    --env.deployment.image=sweagent/ctf-env:latest \
    --problem_statement.text="在运行的 Web 服务 http://challenge.local:8080 中找到 flag" \
    --output_dir=/output
```

***

## # 使用固定种子以获得一致结果

### Docker socket 权限被拒绝

```bash
# 错误：尝试连接 Docker 守护进程时权限被拒绝
# 解决方法：确保正确挂载 Docker socket

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  sweagent/swe-agent:latest \
  docker ps

# 如果看到权限错误，请检查 socket 权限
ls -la /var/run/docker.sock
# 应为： srw-rw---- root docker

# 将当前用户添加到 docker 组（如果不是 root）
usermod -aG docker $USER
newgrp docker
```

### API 密钥错误

```bash
# 验证你的 API 密钥是否设置正确
docker run --rm \
  --env-file /workspace/sweagent/.env \
  sweagent/swe-agent:latest \
  python -c "
批处理处理
keys = ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'GITHUB_TOKEN']
for k in keys:
    val = os.environ.get(k, 'NOT SET')
    masked = val[:8] + '...' if len(val) > 8 else val
    print(f'{k}: {masked}')
"

# 测试 Anthropic API 密钥
curl https://api.anthropic.com/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"
```

### 代理陷入循环

```bash
# SWE-agent 有内置的步骤上限（默认约 100 步）
# 通过配置增加或减少：

docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=claude-sonnet-4-20250514 \
    --agent.model.per_instance_cost_limit=2.00 \
    --agent.max_requeries=5 \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/1

# 终止卡住的运行
docker ps | grep sweagent
docker stop <container_id>
```

### 代码执行过程中内存不足

```bash
# 增加沙箱内存限制
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /workspace/sweagent/output:/output \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=claude-sonnet-4-20250514 \
    --env.deployment.docker_args='["--memory=8g", "--cpus=4"]' \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/1

# 对于大型代码库，将 Clore.ai 实例增加到 32GB 内存
```

### GitHub 限流

```bash
# GitHub API 有速率限制 —— 使用具有 repo 范围的个人访问令牌
# 检查你当前的速率限制状态
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/rate_limit | jq '.rate'

# 如果被限流，等待重置或使用不同的令牌
# 速率限制每小时重置
```

***

## 延伸阅读

* [SWE-agent GitHub](https://github.com/SWE-agent/SWE-agent) —— 主仓库和文档
* [SWE-agent 文档](https://swe-agent.com/docs/) —— 官方文档
* [SWE-agent 论文（NeurIPS 2024）](https://arxiv.org/abs/2405.15793) —— 研究论文
* [SWE-bench 排行榜](https://www.swebench.com/) —— 查看不同模型的表现
* [Clore.ai 入门](https://docs.clore.ai/guides/guides_v2-zh/kuai-su-ru-men/getting-started) —— 平台基础
* [GPU 比较指南](https://docs.clore.ai/guides/guides_v2-zh/kuai-su-ru-men/gpu-comparison) —— 如果你需要用于本地大模型的 GPU
* [在 Clore.ai 上运行 Ollama](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/ollama) —— SWE-agent 的本地大模型后端
* [在 Clore.ai 上运行 vLLM](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/vllm) —— 高吞吐量的本地大模型服务器
* [Anthropic API 定价](https://www.anthropic.com/pricing) —— Claude API 成本
* [OpenAI API 定价](https://openai.com/api/pricing/) —— GPT-4 API 成本

> 💡 **Clore.ai + SWE-agent 的最佳方案：** 租用一台仅 CPU 的服务器（4 核，16GB 内存），约 $0.05/小时，在其上使用 Claude Sonnet 4 运行 SWE-agent，修复 GitHub 问题的总成本约为 **每个问题 $1–2** （API 成本）外加几分钱的 Clore.ai 时间。对于有大量问题的团队，这在常规漏洞修复上比雇佣开发者节省数个数量级。