第一章 认识 SWE-agent

1.1 什么是 SWE-agent？

SWE-agent 是由普林斯顿大学和斯坦福大学研究团队联合开发的开源 AI Agent，专门用于自动修复 GitHub Issue。它获得了 19k+ GitHub Stars，采用 MIT 许可协议，是当前学术界和工业界最受关注的 AI 代码修复工具之一。

SWE-agent 的核心设计理念是 Agent-Computer Interface (ACI)——一种让大语言模型（LLM）能够像人类开发者一样与计算机交互的接口。通过 ACI，Agent 可以浏览代码库、编辑文件、运行命令、提交修复，整个过程完全自动化。

在权威的 SWE-bench 基准测试中，SWE-agent 达到了当时的 SOTA（State-of-the-Art）水平，展现出强大的代码理解和修复能力。

1.2 mini-SWE-agent 是什么？

官方开发重心已转向 mini-SWE-agent（仓库：swe-agent/mini-swe-agent），这是 SWE-agent 的简化版本。如果你刚接触这个项目，强烈建议直接从 mini-SWE-agent 开始。官方文档也推荐新用户优先使用 mini-SWE-agent 而非完整版。

mini-SWE-agent 移除了完整版中的一些复杂配置和依赖，提供了更简洁的 API 和更快的启动体验。核心功能——通过 AI 自动修复 GitHub Issue——两者都能胜任，但 mini-SWE-agent 的门槛更低。

1.3 核心功能概览

• 自动修复 Issue：给定一个 GitHub Issue 和代码仓库，Agent 会自动分析、定位问题并生成修复补丁
• SWE-bench 支持：可以在 SWE-bench 基准上评估 Agent 性能
• 多模态支持：支持 GPT-4o、Claude Sonnet 4 等多种模型
• EnIGMA 模式：专为 CTF（Capture The Flag）挑战设计的模式
• 批量运行：支持批量处理多个 Issue
• ACI 系统：灵活的 Agent-Computer Interface，可自定义工具

1.4 技术架构

SWE-agent 采用 Docker 作为默认后端运行环境。当你运行一个修复任务时，系统会：

1. 读取配置文件（Token、API Key、模型选择等）
2. 将目标代码仓库加载到 Docker 容器中
3. Agent 在容器内通过 ACI 与环境交互（浏览、编辑、测试）
4. 生成的补丁（patch）输出到宿主机
5. 可选的：自动创建 GitHub PR 提交修复

第二章 快速上手（5分钟）

2.1 前提条件

在开始之前，请确保你的系统满足以下条件：

• Python >= 3.11
• Docker（推荐使用默认后端）
• 一个 OpenAI 或 Anthropic 的 API Key
• 一个 GitHub Token（用于访问仓库和创建 PR）

2.2 安装 mini-SWE-agent（推荐）

这是最快的上手方式：

# 克隆 mini-swe-agent 仓库
git clone https://github.com/swe-agent/mini-swe-agent.git
cd mini-swe-agent

# 安装依赖
pip install -e .

2.3 安装完整版 SWE-agent

如果你需要全部功能（如批量处理、自定义工具等）：

# 克隆完整版仓库
git clone https://github.com/SWE-agent/SWE-agent.git
cd SWE-agent

# 以可编辑模式安装
pip install --editable .

2.4 配置环境变量

在项目根目录创建 .env 文件：

# 必须：至少配置一个 LLM 提供商的 API Key
OPENAI_API_KEY=sk-your-openai-key-here
# 或
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here

# 必须：GitHub Token
GITHUB_TOKEN=ghp_your-github-token-here

2.5 运行第一个修复任务

一切就绪后，运行以下命令自动修复一个 GitHub Issue：

sweagent run \
  --agent.model.name=gpt-4o \
  --agent.model.per_instance_cost_limit=3.0 \
  --env.repo.github_url=https://github.com/owner/repo \
  --problem_statement.github_url=https://github.com/owner/repo/issues/123

第三章 安装与 Docker 环境

3.1 系统要求

3.2 安装 Python 3.11+

macOS：

brew install python@3.11

Ubuntu / Debian：

sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip

Windows (WSL2)： 建议在 WSL2 的 Ubuntu 发行版中安装，步骤同上。

3.3 安装 Docker

macOS： 下载 Docker Desktop for Mac。

Linux：

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
# 登出并重新登录，或执行：
newgrp docker

Windows： 安装 Docker Desktop for Windows，确保启用 WSL2 集成。

3.4 验证 Docker 权限

验证 Docker 是否正常工作：

docker run hello-world

如果遇到 permission denied 错误，说明你的用户不在 docker 组中：

# 将当前用户加入 docker 组
sudo usermod -aG docker $USER

# 验证组成员
groups $USER

# 需要重新登录或执行 newgrp 以生效
sudo systemctl restart docker

3.5 完整安装流程

以下是 SWE-agent 的完整安装步骤：

# 1. 克隆仓库
git clone https://github.com/SWE-agent/SWE-agent.git
cd SWE-agent

# 2. 创建虚拟环境（推荐）
python3.11 -m venv venv
source venv/bin/activate  # Linux/macOS
# 或
# .\venv\Scripts\Activate  # Windows PowerShell

# 3. 安装 SWE-agent
pip install --editable .

# 4. 验证安装
sweagent --help

如果看到帮助信息，说明安装成功。

3.6 mini-SWE-agent 安装

mini-SWE-agent 的安装更简洁：

git clone https://github.com/swe-agent/mini-swe-agent.git
cd mini-swe-agent
pip install -e .

第四章 配置 GitHub Token 与 API

4.1 获取 GitHub Token

SWE-agent 需要 GitHub Token 来：

• 克隆目标代码仓库
• 读取 Issue 内容
• （可选）创建 Pull Request 提交修复

创建 Token 步骤：

1. 登录 GitHub，进入 Settings > Developer settings > Personal access tokens > Tokens (classic)
2. 点击 Generate new token (classic)
3. 设置 Token 名称（如 "swe-agent"）
4. 勾选权限范围（Scope）：至少需要 repo（完整仓库访问）和 read:org（读取组织信息）
5. 点击 Generate token，复制生成的 Token

4.2 获取 LLM API Key

SWE-agent 支持多种 LLM 后端：

4.3 配置 .env 文件

SWE-agent 会自动从项目根目录的 .env 文件加载环境变量。这是推荐的做法：

# === LLM API Keys ===
# 至少配置一个
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxx
# ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx

# === GitHub ===
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# === 可选配置 ===
# API Base URL（用于本地模型或代理）
# OPENAI_API_BASE=http://localhost:8000/v1

# 日志级别
# LOG_LEVEL=INFO

4.4 使用环境变量配置

除了 .env 文件，你也可以通过命令行或系统环境变量配置：

# 导出环境变量
export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxx"
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

# 然后运行命令
sweagent run ...

4.5 使用本地模型

如果你希望使用本地部署的模型（如 Llama、Mistral 等），需要搭建一个 OpenAI 兼容的 API 服务：

• 使用 vLLM、Ollama、text-generation-webui 等工具启动 API
• 设置 OPENAI_API_BASE 指向你的 API 端点
• 设置 OPENAI_API_KEY（即使是 dummy 值也可以）

第五章 自动修复 Issue

5.1 基本用法

修复单个 GitHub Issue 是最核心的功能：

sweagent run \
  --agent.model.name=gpt-4o \
  --agent.model.per_instance_cost_limit=3.0 \
  --env.repo.github_url=https://github.com/psf/requests \
  --problem_statement.github_url=https://github.com/psf/requests/issues/6000

参数说明：

• --agent.model.name：使用的模型名称（如 gpt-4o, claude-sonnet-4-20250514）
• --agent.model.per_instance_cost_limit：每个实例的成本上限（美元）
• --env.repo.github_url：目标代码仓库的 GitHub URL
• --problem_statement.github_url：需要修复的 Issue 的完整 GitHub URL

5.2 使用配置文件

对于复杂的配置，建议使用 YAML 配置文件：

agent:
  model:
    name: gpt-4o
    per_instance_cost_limit: 3.0
  tools:
    - bash
    - editor
    - file_surfer

env:
  repo:
    github_url: https://github.com/psf/requests
  docker:
    image: sweagent/swe-agent:latest

sweagent run --config config/my_config.yaml --problem_statement.github_url=https://github.com/psf/requests/issues/6000

5.3 理解运行过程

当你运行修复命令后，SWE-agent 会经历以下阶段：

1. 环境准备：拉取 Docker 镜像（首次运行时），创建容器
2. 加载仓库：将目标代码仓库克隆到容器中
3. 读取 Issue：通过 GitHub API 获取 Issue 的标题和描述
4. 探索代码：Agent 使用 ACI 工具浏览代码结构，定位相关文件
5. 诊断问题：分析代码，确定导致 Issue 的原因
6. 生成修复：修改代码文件，生成补丁
7. 验证：（如果配置了测试）运行测试验证修复
8. 输出结果：将补丁文件输出到本地，可选创建 PR

5.4 查看结果

修复完成后，SWE-agent 会：

• 在终端输出修复摘要
• 将补丁文件保存到本地（默认路径取决于配置，通常在 trajectories/ 目录下）
• 如果配置了 --actions.open_pr，自动创建 Pull Request

手动检查补丁文件：

# 查看最近生成的补丁
ls -la trajectories/
cat trajectories/patch_*.diff

5.5 批量运行

使用 run-batch 命令批量处理多个 Issue：

sweagent run-batch \
  --agent.model.name=gpt-4o \
  --instances.path=path/to/instances.json

instances.json 文件格式示例：

[
  {
    "repo": "https://github.com/psf/requests",
    "issue_num": 6000
  },
  {
    "repo": "https://github.com/pallets/flask",
    "issue_num": 4200
  }
]

5.6 使用 Inspect 模式

sweagent inspect 命令用于检查运行结果和轨迹：

# 检查最近的运行轨迹
sweagent inspect

# 查看特定轨迹
sweagent inspect --trajectory path/to/trajectory.json

5.7 使用 API 模式

sweagent run-api 启动一个 HTTP API 服务，方便与其他系统集成：

sweagent run-api --port 8000

第六章 自定义工具与配置

6.1 理解 ACI（Agent-Computer Interface）

ACI 是 SWE-agent 的核心设计理念。传统的 LLM Agent 通常让模型直接写 Bash 命令，这会导致模型在面对复杂命令行环境时表现不佳。ACI 通过精心设计的工具接口，让 LLM 能用更自然、更可靠的方式与计算机交互。

ACI 的关键设计原则：

• 限制动作空间：只提供必要的、LLM 容易理解的工具
• 反馈优化：工具的返回格式经过优化，便于 LLM 理解
• 错误处理：提供清晰的错误信息，帮助 LLM 自我纠正
• 状态透明：Agent 能清楚知道当前的工作目录、文件状态等

6.2 内置工具

SWE-agent 提供以下内置工具：

6.3 自定义工具配置

你可以在配置文件中启用或禁用特定工具：

agent:
  tools:
    - bash
    - editor
    # 禁用 file_surfer（不包含在列表中即可）
  tool_config:
    editor:
      # 限制编辑的文件大小（字节）
      max_file_size: 1048576
    bash:
      # 命令超时时间（秒）
      timeout: 60

6.4 自定义 Docker 镜像

你可以指定不同的 Docker 镜像来运行 Agent：

env:
  docker:
    image: sweagent/swe-agent:latest
    # 自定义构建
    build:
      dockerfile: path/to/Dockerfile
      context: path/to/context

6.5 完整的配置示例

agent:
  model:
    name: gpt-4o
    per_instance_cost_limit: 3.0
    temperature: 0.0
  tools:
    - bash
    - editor
    - file_surfer
  tool_config:
    editor:
      max_file_size: 1048576
    bash:
      timeout: 60

env:
  repo:
    github_url: https://github.com/psf/requests
  docker:
    image: sweagent/swe-agent:latest

output:
  trajectory_dir: ./trajectories
  actions:
    open_pr: false

第七章 进阶技巧

7.1 使用多模态模型

SWE-agent 支持多模态模型（如 GPT-4o、Claude Sonnet 4），这些模型可以处理截图、图表等视觉信息。如果 Issue 中包含截图，多模态模型能更好地理解问题背景。

# 使用 Claude Sonnet 4
sweagent run \
  --agent.model.name=claude-sonnet-4-20250514 \
  --agent.model.per_instance_cost_limit=5.0 \
  --env.repo.github_url=https://github.com/owner/repo \
  --problem_statement.github_url=https://github.com/owner/repo/issues/123

7.2 成本控制

合理设置成本上限，避免意外高额费用：

• per_instance_cost_limit：每个 Issue 的成本上限（美元），推荐 2.0 - 5.0
• 可在运行过程中实时监控消耗
• 对于简单 Issue，通常 0.5 - 1.0 美元即可完成修复

7.3 EnIGMA 模式：CTF 挑战

SWE-agent 还包含 EnIGMA 模式，专为 CTF（Capture The Flag）安全挑战设计。这个模式优化了 Agent 的安全分析和漏洞利用能力。

# 启用 EnIGMA 模式（仅兼容 SWE-agent v0.7，不兼容 v1.0/v1.1）
sweagent run --mode enigma --env.repo.github_url=...

7.4 轨迹回放与分析

每次运行都会生成详细的轨迹（trajectory）文件，记录了 Agent 的所有思考和操作步骤。利用这些数据可以：

• 分析 Agent 的决策过程
• 找出失败的原因
• 优化提示词和工具配置
• 用于研究和教学

# 查看轨迹文件
sweagent inspect --trajectory trajectories/run_20250513_063800/trajectory.json

7.5 SWE-bench 评估

如果你需要评估 Agent 在 SWE-bench 基准上的性能：

# 下载 SWE-bench 数据集并运行评估
sweagent run-batch --instances.type swe_bench \
  --agent.model.name=gpt-4o \
  --bench.split=test

7.6 与 CI/CD 集成

你可以将 SWE-agent 集成到 CI/CD 流水线中：

• 使用 sweagent run-api 启动 API 服务
• 在 CI 脚本中调用 API 触发修复任务
• 通过 webhook 自动响应新创建的 Issue
• 使用 --actions.open_pr 自动提交修复 PR

第八章 常见问题与排错

8.1 Docker 权限问题

解决方法：

1. 将用户加入 docker 组：sudo usermod -aG docker $USER
2. 重新登录或执行 newgrp docker
3. 重启 Docker 服务：sudo systemctl restart docker
4. 验证：docker run hello-world

8.2 API Key 配置问题

解决方法：

1. 检查 .env 文件是否在项目根目录
2. 确认环境变量名称拼写正确（OPENAI_API_KEY vs OPENAI_API_Key）
3. 确认 API Key 有效且未过期
4. 确认账户余额充足
5. 尝试直接导出环境变量：export OPENAI_API_KEY="sk-..."

8.3 GitHub Token 问题

解决方法：

1. 确认 Token 有 repo 权限
2. 对于私有仓库，确保 Token 被授予了访问权限
3. 如果使用 fine-grained token，确保已授权到具体仓库
4. 检查 Token 是否过期

8.4 Docker 镜像下载失败

解决方法：

1. 检查网络连接是否能访问 Docker Hub
2. 尝试手动拉取镜像：docker pull sweagent/swe-agent:latest
3. 配置 Docker 镜像加速器（中国用户常见问题）
4. 如果超时，尝试设置更长的超时时间或使用代理

8.5 Python 版本不兼容

解决方法： SWE-agent 需要 Python >= 3.11。使用 python3.11 --version 确认版本。

8.6 SWE-ReX 兼容性问题

SWE-agent 依赖 SWE-ReX 作为评测后端。如果遇到 SWE-ReX 相关问题：

• 确保 SWE-ReX 版本 >= 1.2.0
• 更新命令：pip install --upgrade swe-rex
• 如果使用自定义环境，检查 SWE-ReX 的配置是否正确

8.7 容器退出或超时

解决方法：

1. 增加成本上限：--agent.model.per_instance_cost_limit=5.0
2. 检查 Issue 描述是否清晰，避免模糊的 Issue
3. 确保模型本身没有达到 token 限制
4. 对于复杂 Issue，考虑拆分为多个子任务

8.8 本地模型相关问题

如果你使用本地模型：

• 确保 API 服务运行正常且为 OpenAI 兼容格式
• 检查 OPENAI_API_BASE 是否正确设置
• 本地模型的能力可能不足以处理复杂 Issue
• 注意本地模型的上下文窗口限制

附录：命令速查表

A.1 基础命令

A.2 运行命令

A.3 检查与分析命令

A.4 实用工具命令

A.5 常用参数

A.6 环境变量速查

* 至少配置一个 LLM API Key。

A.7 安装速查