# 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 入门](/guides/guides_v2-zh/ru-men/getting-started.md) —— 平台基础
* [GPU 比较指南](/guides/guides_v2-zh/ru-men/gpu-comparison.md) —— 如果你需要用于本地大模型的 GPU
* [在 Clore.ai 上运行 Ollama](/guides/guides_v2-zh/yu-yan-mo-xing/ollama.md) —— SWE-agent 的本地大模型后端
* [在 Clore.ai 上运行 vLLM](/guides/guides_v2-zh/yu-yan-mo-xing/vllm.md) —— 高吞吐量的本地大模型服务器
* [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 时间。对于有大量问题的团队，这在常规漏洞修复上比雇佣开发者节省数个数量级。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/ai-ping-tai-yu-zhi-neng-ti/swe-agent.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.