Windows-Use 是一个在 GUI 层面控制 Windows 的 AI 代理。它通过 Windows UI Automation API 读取屏幕，并使用任意 LLM 来决定点击、输入、滚动或运行什么——无需计算机视觉模型。

只需用英文描述任务，剩下的交给它。

它能做什么

• 打开、切换和调整应用程序窗口大小
• 点击、输入、滚动、拖拽，以及使用键盘快捷键
• 运行 PowerShell 命令并读取输出
• 通过浏览器的无障碍树抓取网页
• 读写文件系统中的文件
• 管理 Windows 虚拟桌面（创建、重命名、切换）
• 通过持久记忆在不同步骤间保留信息
• 通过 STT/TTS 进行语音输入输出（语音交互）

🛠️ 安装

前提条件： Python 3.10+，Windows 7/8/10/11

pip install windows-use

或使用 uv：

uv add windows-use

⚙️ 快速开始

选择任意受支持的 LLM 提供商，并运行一个任务：

Anthropic (Claude)

from windows_use.providers.anthropic import ChatAnthropic
from windows_use import Agent, Browser

llm = ChatAnthropic(model="claude-sonnet-4-5")
agent = Agent(llm=llm, browser=Browser.EDGE)
agent.invoke(task="打开记事本，写一首关于 Windows 的短诗")

OpenAI

from windows_use.providers.openai import ChatOpenAI
from windows_use import Agent, Browser

llm = ChatOpenAI(model="gpt-4o")
agent = Agent(llm=llm, browser=Browser.CHROME)
agent.invoke(task="在 Google 上搜索纽约的天气")

Google Gemini

from windows_use.providers.google import ChatGoogle
from windows_use import Agent, Browser

llm = ChatGoogle(model="gemini-2.5-flash")
agent = Agent(llm=llm, browser=Browser.EDGE)
agent.invoke(task=input("输入一个任务："))

Ollama (本地)

from windows_use.providers.ollama import ChatOllama
from windows_use import Agent, Browser

llm = ChatOllama(model="qwen3-vl:235b-cloud")
agent = Agent(llm=llm, use_vision=False)
agent.invoke(task=input("输入一个任务："))

异步用法

import asyncio
from windows_use.providers.anthropic import ChatAnthropic
from windows_use import Agent

async def main():
    llm = ChatAnthropic(model="claude-sonnet-4-5")
    agent = Agent(llm=llm)
    result = await agent.ainvoke(task="截屏并描述桌面")
    print(result.content)

asyncio.run(main())

🤖 CLI

直接在终端中启动交互式代理：

windows-use

选项：

--model, -m      使用的 LLM 模型
--provider, -p   LLM 提供商
--max-steps      每个任务的最大步数（默认：200）
--debug, -d      启用调试日志

会话内命令：

命令	描述
\llm	切换提供商或模型
\key	更改 API 密钥
\speech	配置 STT/TTS
\voice	录制语音输入
\clear	清屏
\quit	退出

🔌 支持的 LLM 提供商

提供商	导入方式
Anthropic	from windows_use.providers.anthropic import ChatAnthropic
OpenAI	from windows_use.providers.openai import ChatOpenAI
Google	from windows_use.providers.google import ChatGoogle
Groq	from windows_use.providers.groq import ChatGroq
Ollama	from windows_use.providers.ollama import ChatOllama
Mistral	from windows_use.providers.mistral import ChatMistral
Cerebras	from windows_use.providers.cerebras import ChatCerebras
DeepSeek	from windows_use.providers.deepseek import ChatDeepSeek
Azure OpenAI	from windows_use.providers.azure_openai import ChatAzureOpenAI
Open Router	from windows_use.providers.open_router import ChatOpenRouter
LiteLLM	from windows_use.providers.litellm import ChatLiteLLM
NVIDIA	from windows_use.providers.nvidia import ChatNvidia
vLLM	from windows_use.providers.vllm import ChatVLLM

🧰 代理配置

Agent(
    llm=llm,                        # LLM 实例（必需）
    mode="normal",                  # "normal"（完整上下文）或 "flash"（轻量级，更快）
    browser=Browser.EDGE,           # Browser.EDGE | Browser.CHROME | Browser.FIREFOX
    use_vision=False,               # 向 LLM 发送截图
    use_annotation=False,           # 在截图上标注 UI 元素
    use_accessibility=True,         # 使用 Windows 无障碍树
    auto_minimize=False,            # 代理启动前最小化当前窗口
    max_steps=25,                   # 放弃前的最大步数
    max_consecutive_failures=3,     # 连续 N 次工具失败后终止
    instructions=[],                # 额外的系统指令
    secrets={},                     # 传递给代理上下文的键值对秘密
    log_to_console=True,            # 在控制台打印步骤
    log_to_file=False,              # 将步骤写入日志文件
    event_subscriber=None,          # 自定义事件监听器（参见 Events 部分）
    experimental=False,             # 启用实验性工具（文件、记忆、多选）
)

提示： 使用 claude-haiku-4-*、claude-sonnet-4-* 或 claude-opus-4-* 可获得最佳效果。

🛠️ 工具

代理会自动获取以下工具——无需额外配置。

核心工具：

工具	描述
click_tool	在坐标处左键、右键、中键点击或悬停
type_tool	向任何输入字段键入文本
scroll_tool	垂直或水平滚动
move_tool	移动鼠标或拖放
shortcut_tool	按下键盘快捷键（例如 ctrl+c、alt+tab）
app_tool	启动、切换或调整应用程序窗口
shell_tool	运行 PowerShell 命令
scrape_tool	从网页中提取文本内容
desktop_tool	创建、重命名、切换 Windows 虚拟桌面
wait_tool	暂停执行 N 秒
done_tool	向用户返回最终答案

实验性工具（通过 experimental=True 启用）：

工具	描述
file_tool	读取、写入、列出、移动、复制、删除文件
memory_tool	在 markdown 文件中跨步骤持久化信息
multi_select_tool	Ctrl+单击一次选择多个元素
multi_edit_tool	一次操作填写多个表单字段

📡 事件

通过事件系统观察智能体的每一步操作：

from windows_use import Agent, AgentEvent, EventType, BaseEventSubscriber

class MySubscriber(BaseEventSubscriber):
    def invoke(self, event: AgentEvent):
        if event.type == EventType.TOOL_CALL:
            print(f"Tool: {event.data['tool_name']}")
        elif event.type == EventType.DONE:
            print(f"Done: {event.data['answer']}")

agent = Agent(llm=llm, event_subscriber=MySubscriber())

或使用一个普通的可调用对象：

def on_event(event: AgentEvent):
    print(f"{event.type.value}: {event.data}")

agent = Agent(llm=llm, event_subscriber=on_event)

事件类型： THOUGHT · TOOL_CALL · TOOL_RESULT · DONE · ERROR

🎙️ 语音（STT / TTS）

Windows-Use 支持通过多个提供商进行语音输入和语音输出。

STT（语音转文字）： OpenAI Whisper · Google · Groq · ElevenLabs · Deepgram

TTS（文字转语音）： OpenAI · Google · Groq · ElevenLabs · Deepgram

from windows_use.providers.openai import ChatOpenAI, STTOpenAI, TTSOpenAI
from windows_use.speech import STT, TTS

llm = ChatOpenAI(model="gpt-4o")
stt = STT(provider=STTOpenAI())
tts = TTS(provider=TTSOpenAI())

task = stt.invoke()              # 录制并转录语音输入
agent = Agent(llm=llm)
result = agent.invoke(task=task)
tts.invoke(result.content)       # 将响应用语音读出

🖥️ 虚拟桌面

智能体可以原生管理 Windows 虚拟桌面：

from windows_use.vdm.core import create_desktop, switch_desktop, remove_desktop

create_desktop("Work")
switch_desktop("Work")
remove_desktop("Work")

支持 Windows 10（内部版本 17763+）和所有 Windows 11 版本。

⚠️ 安全

此智能体可以：

• 代表用户操作你的计算机
• 修改文件和系统设置
• 对你的系统进行不可逆更改

⚠️ 强烈建议：在虚拟机或 Windows 沙盒中部署

该项目不提供沙盒或隔离层。为你的安全起见：

• ✅ 使用虚拟机（VirtualBox、VMware、Hyper-V）
• ✅ 使用 Windows 沙盒（Windows 10/11 专业版/企业版）
• ✅ 使用专用测试机器

📖 部署前请阅读完整的安全策略。

📡 遥测

Windows-Use 包含轻量级、注重隐私的遥测功能，以帮助提高可靠性并了解真实使用情况。

随时禁用它：

ANONYMIZED_TELEMETRY=false

或在代码中：

import os
os.environ["ANONYMIZED_TELEMETRY"] = "false"

Star 历史

🪪 许可证

MIT — 详见 LICENSE。

🙏 致谢

• UIAutomation
• PyAutoGUI

🤝 贡献

欢迎贡献！开发工作流程请参阅 CONTRIBUTING。

由 Jeomon George 用 ❤️ 制作

---

引用

@software{
  author       = {George, Jeomon},
  title        = {Windows-Use: Enable AI to control Windows OS},
  year         = {2025},
  publisher    = {GitHub},
  url          = {https://github.com/CursorTouch/Windows-Use}
}