SWE-agent 安装与配置完全指南从源码部署、浏览器试跑到模型与 API Key 设置【免费下载链接】SWE-agentSWE-agent takes a GitHub issue and tries to automatically fix it, using your LM of choice. It can also be employed for offensive cybersecurity or competitive coding challenges. [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/sw/SWE-agentSWE-agent 是一款面向 AI 软件工程的开源 Agent-Computer Interface给定一个 GitHub issue它可以调用语言模型如 GPT-4o、Claude Sonnet 4自主使用工具修复真实仓库中的问题也可用于攻防安全CTF与编程竞赛场景。本指南以官方安装文档为主线系统讲解 SWE-agent 的三种上手路径——源码安装、浏览器Codespaces试跑、版本更新与排障并深入覆盖模型接入、API Key 配置、本地模型接入等实战细节。读完本文你将能够在一台全新机器上完整部署 SWE-agent并把任意 litellm 支持的模型接入其中开始运行。安装方式总览SWE-agent 的官方文档提供了三条上手路径适用于不同场景路径适用场景复杂度从源码安装本地完整部署官方推荐默认选项中等浏览器运行Codespaces快速第一眼体验无需本地环境最低查看 Changelog了解版本演进、新特性与破坏性变更-源码安装是官方最推荐的本地部署方式浏览器方案则适合先跑起来看看的快速体验Changelog 记录了从 v0.2 到 v1.1.0 的完整演进历史升级前务必查阅。此外仓库内还提供了 安装排障指南、模型与 API Key 配置 以及 1.0 迁移指南下文将逐一展开。从源码安装推荐源码安装是 SWE-agent 的默认且最推荐的安装方式全部过程只需三步第一步克隆仓库git clone https://github.com/SWE-agent/SWE-agent.git第二步以可编辑模式安装在仓库根目录执行python -m pip install --upgrade pip pip install --editable .--editable可编辑模式会建立源码与已安装包之间的软链接便于开发调试与任何 Python 工程一样官方强烈建议使用 conda 或 virtual environments 管理依赖避免污染全局环境。关于运行环境仓库的 pyproject.toml 明确声明requires-python 3.11即要求 Python 3.11 及以上版本。安装时 pip 会自动解析该文件中的依赖包括litellm1.44.12、swe-rex1.4.0、pydantic、rich、tenacity等核心库并注册命令行入口[project.scripts] sweagent sweagent.run.run:main第三步配置语言模型按 模型与 API Key 配置 的说明为你的语言模型设置 API Key。这一步不可跳过因为 SWE-agent 的所有智能行为都依赖 LLM 驱动。验证安装sweagent --help若安装成功应看到顶层命令的概览。从源码看入口实现在 sweagent/run/run.pymain()会解析子命令并分发同时 sweagent/main.py 也提供了模块级入口因此当sweagent命令找不到时可退而求其次使用python -m sweagent。如果两者都失败请用which python确认当前 shell 使用的 Python 与你安装 SWE-agent 时是同一个解释器。如果命令找不到先尝试python -m sweagent再不行就用which python核对解释器路径是否与安装时一致。可选安装步骤安装 Docker强烈推荐SWE-agent 的默认代码执行后端是 Docker。请先安装 Docker 并启动本地 Docker 服务。若确实不想使用 Docker也可以将代码执行放到云端SWE-ReX 支持 modal、AWS 等云端运行时。遇到问题可参考 安装排障指南 中的 Docker 小节。安装 Node.js使用 Web GUI 时如果你计划使用基于 Web 的图形界面需要额外安装 Node.js 及其 npm 工具链。安装小贴士保持更新SWE-agent 仍在活跃开发中新特性频繁加入。要确保处于最新版本只需定期执行git pull即可无需重新执行pip install。EnIGMA 模式与 v0.7SWE-agent EnIGMA攻防安全 CTF 模式目前只兼容v0.7在完成第一步 clone 后需执行git switch v0.7切换到对应版本。二次开发若想修改 SWE-agent 源码请额外阅读仓库内的贡献指南。在浏览器中运行Codespaces 快速体验在浏览器中运行是体验 SWE-agent 最快捷的方式无需安装任何本地依赖。步骤如下点击项目 README 或文档中的 Open in GitHub Codespaces 按钮在浏览器内启动一个 VSCode 云端开发环境项目会自动完成环境预置。在左侧文件树中找到.env文件按模板填写你的语言模型 API Key更多说明见 模型与 API Key 配置。务必等待终端窗口中的postCreateCommand执行完毕再开始操作否则环境可能尚未就绪。输入你的 SWE-agent 命令具体用法见 命令行入门教程。模型与 API Key 配置SWE-agent 通过 litellm 统一接入各家的语言模型所有 API 模型基本开箱即用只需添加 Key 并指定--agent.model.name本地模型则需要额外配置见下文。设置 API Key 的三种方式为了访问你选择的大模型以及私有 GitHub 仓库需要提供对应 Key。官方文档提供三种等价方式设置环境变量直接在 shell 环境中导出对应变量创建.env文件在仓库根目录创建.env其中定义的变量会覆盖/替代环境变量命令行参数使用--agent.model.api_key直接传入 Key。.env文件模板示例# 取消对应 Key 前的注释符号 # 即可生效 # GITHUB_TOKENGitHub Token for access to private repos # OPENAI_API_KEYOpenAI API Key Here if using OpenAI Model # ANTHROPIC_API_KEYAnthropic API Key Here if using Anthropic Model # TOGETHER_API_KEYTogether API Key Here if using Together Model提示更多高级配置温度、采样、重试等见 模型配置文档。支持的 API 模型SWE-agent 支持所有 litellm 所支持的模型。官方文档给出的几个--agent.model.name参考值模型API Key备注claude-sonnet-4-20250514ANTHROPIC_API_KEY官方推荐模型gpt-4oOPENAI_API_KEYo1-previewOPENAI_API_KEY可能需要将 temperature 与采样参数设为受支持的值若你使用的是默认 litellm 注册表之外的自定义模型如本地新模型可通过litellm_model_registry配置项提供自定义模型注册文件以获得正确的成本追踪详见 自定义成本追踪。解析器function calling 与 thought_action默认配置使用function calling从模型响应中提取动作即模型直接以 JSON 对象形式提供动作。如果模型不支持函数调用需要将agent.tools.parse_function.type设置为thought_action此时 SWE-agent 会从模型响应中提取最后一个三反引号代码块作为动作。两种解析器的取舍如下function calling动作以结构化 JSON 返回模型能看到函数签名thought_action解析最后一个代码块模型看不到函数签名因此必须在提示词prompt中把工具文档写清楚。更多解析器细节见 解析器 API 文档。使用本地模型SWE-agent 支持所有通过 OpenAI 兼容 API 提供服务的本地模型例如通过 litellm 对接 Ollama 上的 llama。将模型配置写入你的 YAML 配置文件默认加载config/default.yaml也可用--config指定agent: model: name: ollama/llama2 # (1)! api_base: http://localhost:11434 per_instance_cost_limit: 0 # (2)! total_cost_limit: 0 per_instance_call_limit: 100 max_input_tokens: 0 # (3)! tools: # 从模型输出中获取动作的默认方式是 function calling。 # 若本地模型不支持可改用 thought_action 解析器见下文 parse_function: type: thought_action # 若你使用的不是 Claude大概率不需要 cache_control 历史处理器 # 若配置中存在请删除 history_processors: []模型名必须包含 provider即形如provider/model_name本地模型的名称和 provider 可以任意取。本地模型无法追踪成本因此必须把成本上限设为 0 以禁用成本追踪原因见下文警告。设为 0 表示禁用 max input tokens 检查。注意无论是否手动指定SWE-agent 运行时总会加载一个配置文件。若未用--config指定加载的默认配置即 config/default.yaml默认使用 function calling 和 prompt cachinghistory_processors中的cache_control这未必是你想要的。如果使用 litellm proxy 服务器请将agent.model.name设为openai/...并将agent.model.api_key设为代理配置的 Key或任意非空随机值不能为空。本地模型三大警告模型 provider 格式模型名必须包含 providerprovider/model_name形式本地模型的 provider 与名称可以任意指定。成本/Token 限制若不关闭默认成本上限会因成本计算器在 litellm 模型成本字典中找不到该模型而报错。两种解决方案推荐方案是将per_instance_cost_limit设为 0改用per_instance_call_limit限制每个 issue 的运行步数或者提供包含模型成本信息的自定义litellm_model_registry文件见自定义成本追踪。另外请确保max_input_tokens设为非None值以避免其他警告。消息格式cache_control历史处理器要求特定的消息格式如{role: user, content: [{type: text, text: some text, cache_control: {type: ephemeral}}]}并非所有语言模型都能理解目前主要用于 Anthropic 的缓存控制。不需要时请务必删除该历史处理器。仓库中的默认配置 config/default.yaml 就包含history_processors: - type: cache_control, last_n_messages: 2使用非 Claude 模型时请移除。常见错误排查若报Error code: 404请检查配置的 Key特别确认OPENAI_API_BASE_URL是否设置正确若不使用该变量对应行应删除或注释掉。完整的可用配置项见 模型配置 API 文档特定模型的使用技巧见 模型配置页。安装疑难排解Docker 问题Docker 是 SWE-agent 的默认执行后端大部分安装问题集中在 Docker 环境上。首先用最基础的命令验证 Docker 是否可用docker run hello-world如果出现如下错误docker: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Head http://%2Fvar%2Frun%2Fdocker.sock/_ping: dial unix /var/run/docker.sock: connect: permission denied.按以下顺序排查检查是否允许使用 Docker socket在 Docker Desktop 中点击SettingsAdvancedAllow the default Docker socket to be used (requires password)命令行层面可将当前用户加入docker用户组或临时调整 socket 权限若 Docker 安装使用了不同的 socket 路径可能需要创建符号链接。此外若你使用了 Docker Hub 上的容器镜像执行过docker pull ...或docker run ...务必注意latest标签不会自动更新即便镜像带有latest标签如sweagent/swe-agent-run:latest也请主动执行docker pull sweagent/swe-agent-run:latest确保拿到最新版本。剩余问题可在仓库中开 Issue 反馈。版本演进与迁移要点Changelog 关键节点Changelog 记录了项目从 0.2.0 到 1.1.0 的演进。与安装直接相关的要点包括1.1.02025-05-22主要修复版本新增 SWE-bench 多语言/多模态兼容与 SWE-smith 支持破坏性变更包括轨迹数据格式中messages字段改为query、多个 windowed 工具包重命名、review_on_submit工具包被review_on_submit_m取代。1.0.12025-02-28主要修复本地模型兼容性并将anthropic_filemap设为新的默认配置requires-python 3.11在此版本确认。1.0.02025-02-13大规模重构版本——引入 SWE-ReX 实现快速并行代码执行、支持云端代码执行、可配置重试机制、基于 tool bundles 的灵活工具定义、全部模型通过 litellm 接入、支持命令行覆盖任意配置项、新增命令行轨迹查看器与全新 CLI 子命令体系。0.7.02024-09-23引入 EnIGMA 模式交互式 Agent 工具与 Summarizer。0.3.02024-05-02支持通过 GitHub Codespaces 在云端运行 SWE-agent。从 0.x 迁移到 1.0 的核心变化若你熟悉旧版 SWE-agent迁移指南 概括了以下主要变化CLI 重构不再有run.py脚本取而代之的是统一的sweagent入口点并拆分为多个子命令——sweagent run运行单个 issue、sweagent run-batch批量运行以及多种工具命令sweagent --help可查看全部选项。层级化配置配置改为层级化结构命令行选项形如--agent.model.namegpt-4o配置文件也相应更新。从 sweagent/run/run.py 的源码可以看出顶层子命令包括run/r、run-batch/b、merge-preds、inspect/i、inspector/I、run-replay、traj-to-demo、run-api、remove-unfinished/ru、quick-stats/qs、shell/sh等。环境配置简化删除了复杂的 conda/pip/docker 环境设置选项改为始终从你指定的 Docker 镜像启动推荐镜像自带全部依赖也可通过EnvironmentConfig.post_startup_commands在启动 agent 前执行额外命令。每个 tool bundle 可附带setup.sh脚本例如安装工具所需的 flake8仓库的 tools/ 目录下可看到各工具包的config.yaml与install.sh结构。代码层面SWEEnv基本退化为swerex运行时的小包装Agent类大幅简化将工具/执行逻辑委托给新的Tools类。旧版保留大规模重构前的 SWE-agent 仍保留在v0.7分支SWE-agent EnIGMA 配置目前仍需使用该版本。安装后可以做什么安装完成并配置好模型后可以继续探索Hello World命令行初体验——让 SWE-agent 在本地仓库上修复第一个 issueSWE-bench 批量评测——在标准基准上批量运行与评估配置详解——掌握 YAML 配置体系的全部选项。SWE-agent 仍处于活跃开发阶段新特性不断加入安装后记得定期git pull保持版本最新。【免费下载链接】SWE-agentSWE-agent takes a GitHub issue and tries to automatically fix it, using your LM of choice. It can also be employed for offensive cybersecurity or competitive coding challenges. [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/sw/SWE-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考