SWE-agent 配置教程：从安装到跑通第一个 GitHub Issue
SWE-agent 是一个用大模型自动修复 GitHub Issue 的开源工具，配置过程主要分三步：准备 Python 环境、安装依赖并填入模型 API Key、用 Docker 沙箱跑通一个简单任务。
下面按实际执行顺序展开，每一步都给出命令和预期结果。
先确认系统和 Python 条件
SWE-agent 官方推荐在 Linux 或 macOS 下运行，Windows 建议使用 WSL2。
开始前确认两件事：
- Python 版本不低于 3.9，执行
python3 --version检查。 - 已安装 Docker，执行
docker --version能看到版本号即可。SWE-agent 默认用 Docker 创建隔离环境来执行代码，没有 Docker 时部分任务无法运行。
如果 Python 版本偏低，
可以用 conda create -n sweagent python=3.11 新建环境，
再执行 conda activate sweagent 进入。
安装 SWE-agent 并写入 API Key
从 GitHub 拉取源码后安装依赖：
git clone https://github.com/princeton-nlp/SWE-agent.git
cd SWE-agent
pip install -e .安装完成后，需要配置模型访问凭证。
SWE-agent 通过环境变量读取 API Key，以 OpenAI 兼容接口为例：
export OPENAI_API_KEY="你的密钥"如果使用其他模型服务，在运行命令时通过 --model 参数指定模型名称，并确认对应服务商的接口地址和密钥变量名与文档一致。
密钥不要写进代码仓库，建议放在 ~/.bashrc 或单独的 .env 文件中，通过 source 加载。
跑通第一个任务
SWE-agent 自带一个入门示例，适合验证配置是否生效：
python run.py --model gpt-4o --problem_statement "fix the bug in the example" --repo_path ./example_repo更常见的用法是直接传入 GitHub Issue 链接：
python run.py --model gpt-4o --issue_url https://github.com/owner/repo/issues/1命令执行后，SWE-agent 会拉取仓库、创建 Docker 容器、让模型分析问题并尝试修改代码。
终端会打印每一步的思考和操作记录。
如果看到类似 Patch generated successfully 的提示，说明配置基本可用。
常见报错和避坑点
配置过程中最容易卡在三个地方：
- Docker 权限不足：执行
docker ps报permission denied，把当前用户加入 docker 组后重新登录：sudo usermod -aG docker $USER。 - API Key 未生效：确认
echo $OPENAI_API_KEY有输出，且变量名与 SWE-agent 读取的变量名一致。不同模型提供商可能使用不同的变量名，以运行时报错信息为准。 - 任务超时或容器启动失败：先检查 Docker 服务是否运行（
systemctl status docker），再确认磁盘空间和网络能否拉取镜像。
另外，SWE-agent 的默认配置会限制单次任务的执行步数和时间，复杂 Issue 可能无法一次修复。
建议先用小仓库或简单 Issue 验证流程，再逐步增加难度。
验证配置是否真正可用
判断 SWE-agent 配置成功，不看安装命令是否报错，而看能否生成有效的代码补丁。
跑完第一个任务后，检查输出目录中是否生成了 .patch 文件或修改后的文件。
如果任务失败但容器正常启动、模型正常返回内容，说明环境配置没有问题，问题出在任务本身或模型能力上。
此时可以换一个更简单的 Issue 重试，或调整 --model 参数换用其他模型。
整体来看，
SWE-agent 配置教程的关键在于环境隔离和密钥管理：
Python 和 Docker 负责运行环境，
API Key 负责模型调用，
两者都验证通过后，
再考虑批量处理 Issue 或接入自己的仓库。
