Agent-S 完整上手指南：让 AI 像人一样操作你的电脑，OSWorld 成绩超人类的开源框架

Agent-S 完整上手指南：让 AI 像人一样操作你的电脑，OSWorld 成绩超人类的开源框架

【免费下载链接】Agent-SAgent S: an open agentic framework that uses computers like a human项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-S

Agent-S 是一个开源的计算机操作智能体框架（computer use agent），它通过"视觉理解 + 代码执行"的方式，让大模型真正动手操作桌面：点击、输入、切换窗口、处理文件，像人一样完成任务。最新的 Agent S3 版本在 OSWorld 基准测试中，单跑即可达到 66% 成功率，配合 Behavior Best-of-N 技术后达到 72.6%，超过了约 72% 的人类水平。如果你想在本地跑一个能"用电脑"的 AI，或者想研究 GUI 智能体的工程实现，这个项目值得仔细看一遍。

它到底能干什么？

先回答一个最关心的问题：Agent-S 和普通的"聊天机器人"有什么本质区别？

区别在于它不只会说话，还会动手。你给它一句自然语言指令，比如"帮我关闭 VS Code"或"计算表格里的总销售额并生成图表"，它会：

1. 截图看屏幕：像人一样"看"当前桌面状态；
2. 规划操作：把任务拆成子步骤，决定下一步做什么；
3. 生成代码执行：通过 Agent-Computer Interface（ACI）把操作翻译成 Python 代码（如pyautogui.click()）并执行；
4. 持续观察反馈：每一步执行后再截图，确认结果是否符合预期。

整个流程可以概括为"看屏幕 → 想 → 动手 → 再看屏幕"的循环。早期的 Agent S1 版本还支持从网页检索外部知识（通过 Perplexica 搜索服务）、从记忆中提取历史任务经验，这些能力在 gui_agents/s1/ 目录下都有完整实现。

架构怎么设计的？看懂这张图就够了

Agent-S 的模块化设计是它最值得借鉴的地方。下面这张 S2 架构图把核心闭环讲得很清楚：

各角色分工如下：

• Worker（执行层）：主脑，负责理解任务、规划步骤、决定下一步动作；
• Grounding（定位层）：把"点击那个蓝色按钮"这类描述性动作，落地为精确的屏幕坐标和可执行代码；
• Memory（记忆层）：交互产生的经验先存入记忆；
• Manager（管理层）：从记忆中提取可复用的知识，再指导 Worker 做更主动的规划（Proactive Plan）。

这个"经验 → 记忆 → 知识 → 规划"的闭环，是 Agent-S 区别于"无状态调用大模型"的关键：它越用越熟练。

到了 S3 版本，团队反而做了减法——去掉了层级结构以降低推理延迟（见 gui_agents/s3/agents/agent_s.py 中AgentS3的注释："uses no hierarchy for less inference time"），只保留 Worker + Grounding + 一个可选的反思（Reflection）智能体。结构更简单，速度更快，效果更好。

环境怎么准备？

在动手之前，有四个前置条件需要确认：

1. 单显示器：Agent-S 的坐标定位基于单屏幕设计，多显示器环境不是它的主场。

2. 操作系统：Linux、macOS、Windows 均支持。

3. 安装依赖：

pip install gui-agents

如果想改代码做实验，先克隆仓库再装开发版：

git clone https://gitcode.com/GitHub_Trending/ag/Agent-S pip install -e .

另有一个容易漏掉的步骤：安装 Tesseract OCR，因为pytesseract依赖它的原生组件：

brew install tesseract # macOS sudo apt install tesseract-ocr # Linux

4. 配置 API Key：把主模型的 key 写入 shell 配置文件（Linux 用.bashrc，macOS 用.zshrc）：

export OPENAI_API_KEY=<你的key> export ANTHROPIC_API_KEY=<你的key> export HF_TOKEN=<你的token>

支持的推理后端包括 OpenAI、Anthropic、Gemini、Azure OpenAI、vLLM 本地部署和 Open Router，详细的环境变量设置见 models.md。

这里有一个硬性要求：Grounding（定位）模型是必需的，官方推荐 UI-TARS-1.5-7B（可通过 Hugging Face Inference Endpoints 或其他厂商托管）。没有 grounding 模型，智能体就"看不见"该点哪里，无法完成精细操作。

跑通第一个任务

环境就绪后，用官方推荐的组合（主模型gpt-5-2025-08-07+ 定位模型ui-tars-1.5-7b）运行 CLI：

agent_s \ --provider openai \ --model gpt-5-2025-08-07 \ --ground_provider huggingface \ --ground_url http://localhost:8080 \ --ground_model ui-tars-1.5-7b \ --grounding_width 1920 \ --grounding_height 1080

启动后会出现一个输入提示框，输入类似"打开计算器"的指令，智能体就会开始接管屏幕。运行中按Ctrl+C可以随时暂停观察，按Esc恢复执行——这个调试机制对第一次运行的人非常有用。

两个参数容易踩坑，注意一下：

• --grounding_width / --grounding_height不是屏幕分辨率，而是定位模型输出坐标系的分辨率。用 UI-TARS-1.5-7B 填1920 1080，用 UI-TARS-72B 则填1000 1000；
• 如果你用的是 o3 系列等特殊模型，需要通过--model_temperature 1.0固定温度。

除了 CLI，也可以作为 Python SDK 集成到自己的项目里，核心就三步：实例化AgentS3、传入截图、调用predict。完整的推理循环可以直接参考 gui_agents/s3/cli_app.py，OpenClaw 集成的封装脚本在 integrations/openclaw/。

成绩有多硬？看数据说话

这是 Agent-S 最受关注的部分。先看 OSWorld 基准上各家智能体的对比（OSWorld 是一套 369 个真实桌面任务的评测集，覆盖操作系统操作、办公、专业软件等场景）：

几个关键数字，客观陈述：

Behavior Best-of-N（bBoN）不是换个更强的模型，而是一个评测策略：同一任务跑多条轨迹（rollout），由一个裁判模型对比轨迹间的行为差异，选出最优的一条。工具脚本就在 osworld_setup/s3/bbon/ 里，generate_facts.py生成行为描述，run_judge.py做轨迹对比。

这个策略的泛化性也不错：在 WindowsAgentArena 上，从零样本的 50.2% 提升到 56.6%（3 条 rollout 中挑选）；AndroidWorld 上从 68.1% 提升到 71.6%。

S2 时代的纵向进步也很直观——同样步数预算下，S2 明显领先同期的 Operator、UI-TARS 和 Claude 3.7：

S1 时代按任务类别的拆解（操作系统类是强项，办公与专业软件类相对弱）也可以参考这张图：

进阶玩法与调优技巧

开启本地编程环境。很多任务用代码比用鼠标快得多：批量处理文件、操作表格、跑自动化脚本。加上一个参数即可：

agent_s ... --enable_local_env

启用后智能体可以调用call_code_agent直接在本地执行 Python 和 Bash。但必须郑重提醒：这会以当前用户权限执行任意代码，Bash 命令有 30 秒超时保护。只在可信环境和可信输入下开启，处理不可信任务时建议放进沙盒。

用 SDK 精细控制。CLI 之外的 Python 接口暴露了几个实用的调优参数（见 gui_agents/s3/）：

• max_trajectory_length（默认 8）：轨迹中保留的历史截图轮数。调小省 token、提速度；调大让智能体"记性"更好，但上下文成本更高；
• enable_reflection（默认 True）：反思智能体会检查 Worker 的决策并给出修正建议。简单任务上关掉它（对应 OpenClaw 封装里的--no-reflection）可以明显提速，代价是准确率略有下降。

模型替换很灵活。主模型和 grounding 模型是解耦的，可以各自独立更换厂商或换成 vLLM 本地部署的模型，工程参数只需改engine_params字典里的engine_type和model两个字段。

在评测环境里部署。如果目标是跑 OSWorld 完整评测而不是在真机上玩，仓库提供了现成的运行脚本：本地 VMware 用run_local.py，AWS 用run.py，命令顺序都写在 osworld_setup/s3/run.sh 中，部署细节见 osworld_setup/s3/OSWorld.md。WindowsAgentArena 的环境搭建坑比较多（Office 应用缺失、虚拟机不重置等），WAA_setup.md 里有一份很详细的排障记录。

谁适合用这个项目？

• 想在本地部署"会用电脑"的 AI 的人：pip install gui-agents加一个 grounding 模型端点，就能在自己桌面上跑起来；
• 研究 GUI 智能体的工程师：S1 → S2 → S3 三代实现全部开源在 gui_agents/ 下，从带记忆知识闭环的完整架构，到 S3 的极简结构，可以直接对比不同设计的取舍；
• 做自动化评测的团队：OSWorld、WindowsAgentArena 两套评测的部署脚本和 bBoN 裁判工具都已内置。

最后一句安全提醒：Agent-S 拥有完整的 GUI 控制权，并且会直接执行生成的代码。把它当成一位权限很大的"新同事"，给它安排任务前，先确认环境是可信的。

【免费下载链接】Agent-SAgent S: an open agentic framework that uses computers like a human项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-S