Minion

为每个 AI Agent 配备一台专属电脑。

轻量级 Linux 桌面（办公、开发、研究、浏览器、数据、Windows 应用），任意 Agent 都能使用：
Claude、ChatGPT、Gemini、Cursor、VS Code、LangChain、自编代码，或在笔记本电脑上运行的模型。
Agent 以文本形式读取屏幕，批量操作或通过代码操作，并使用任何程序或网站。

English · 简体中文 · 繁體中文 · 한국어 · 日本語 · עברית

## 开始使用

你只需要安装 Docker（或 OrbStack 或 Podman）。然后选择一种方式：

1. 在 AI 应用中一键安装：

Claude Code：claude plugin marketplace add apophisss/minion && claude plugin install minion@minion。其他任何 MCP 客户端：uvx minion-desktop mcp 或 npx -y minion-desktop mcp。这些按钮以及 uvx 和 npx 都会通过 uv 启动 Minion（npx 也可以改用 pipx）；Claude Desktop 扩展无需其他依赖。

2. 运行一行命令，安装 Minion 并连接你电脑上的所有 AI 应用（Claude Desktop、Claude Code、 Cursor、VS Code、Windsurf/Devin、Gemini CLI、Codex、LM Studio、Cline、Kiro）：

curl -fsSL https://raw.githubusercontent.com/apophisss/minion/main/install.sh | sh        # macOS, Linux

irm https://raw.githubusercontent.com/apophisss/minion/main/install.ps1 | iex             # Windows

命令最后会运行 minion setup，检查 Docker、准备桌面环境并运行 minion connect。你随时可以再次运行任一命令。

**3. 在浏览器中通过 ChatGPT、Claude.ai 或 Le Chat 使用：**运行 minion share，并将输出的 URL 粘贴到 应用的连接器设置中（操作方法）。

然后只需提出请求：“创建一个办公桌面，在 Writer 中撰写一页关于我们第三季度数据的简报，并将其保存为 brief.docx。” 所有安装方式请见 docs/install.md。

_{▶ 观看一分钟演示：一个 Agent 在 Wikipedia 上研究旅行计划，制作带图表的预算，并将计划写成 PDF。共调用工具 12 次，文本共 2,372 个 token；若用截图完成相同步骤，费用约为 36,855。通过 python scripts/demo_video.py 实时录制，该脚本会执行 Agent 会进行的调用。}

---

为什么选择 Minion

• 🖥️ 任何程序，任何网站。 每个桌面都是真正的 Linux 计算机：浏览器、LibreOffice、IDE、终端、文件对话框和安装程序，还可通过 windows（Wine）配置运行 Windows 程序。按名称打开任何应用，首次打开时会自动安装（open gimp、open vscode、open dbeaver，或任何 Debian 软件包）；Web 应用会在浏览器中打开（open gmail），首次打开时还会显示一些应用使用提示。130 多款可按名称打开的应用。
• 🧭 快速操作每个应用。 see --menus 会列出所有菜单命令及其键盘快捷键；menu "File > Export as PDF" 无需打开菜单即可运行命令。path ~/out.pdf 可填写任何打开/保存对话框。右键菜单会显示在 see 的结果中，button:Save 可指定一种控件；位于可视区域下方的按钮会自动滚动到视野内。任何文档都能以文本形式读取（read report.docx、含公式的 xlsx、pptx、pdf），并可通过一次调用完成转换（convert report.docx pdf）。
• 🧠 Agent 以文本形式读取屏幕。 see 会将任意窗口转换为控件列表，并提供稳定的 @ids。这些信息来自辅助功能树，必要时会使用 OCR：@12 button "Save" (210,62)。网页、编辑器（含行号）、终端、带选项的下拉菜单，以及电子表格（逐行显示：row 2: A2 North · B2 120）都会以准确文本呈现。需要关注像素时，截图可以标出 @ids。
• 🎯 可靠的操作。 每次操作都会等待屏幕稳定（等待网页加载完毕，或应用不再显示“Loading…”），并报告发生的情况：窗口、页面警告或提示、已保存或下载的文件，以及接收到点击的弹出窗口。文本目标必须确实显示在屏幕上：未命中时会失败并提供最接近的候选项，而不会点击其他内容。已通过 AI Agent 执行的 93 项日常任务测试。
• 🪙 专为节省 token 打造。 只返回差异，而非重新读取（see(changes=true)：约 80 个 token，而不是约 900 个）。代码模式可在一次调用中运行 50 步 GUI 循环；裁剪和半尺寸截图可降低图像成本；紧凑模式可将工具定义从约 3,300 个 token 缩减到 450 个；Agent Skill 在实际使用前只占约 100 个 token。
• 🪶 轻量精简。 每个桌面使用一个小型容器（Xvfb、双进程窗口管理器和任务栏、小型 Agent），无需 VNC 或桌面环境。桌面约 1.5 秒即可就绪，空闲时占用约 60 MB。空闲桌面会自动冻结（CPU 占用为 0%），约 0.2 秒即可唤醒。
• 🔌 适用于所有 Agent。 到处使用同一套工具：MCP（本地或远程）、适用于 OpenAI、Anthropic、Gemini 和本地模型的函数调用、带 OpenAPI 的 HTTP、供 Shell Agent 使用的 CLI 和 Agent Skill、Python 和 TypeScript SDK，以及适用于 Claude、OpenAI 和 Gemini 计算机使用的原生适配器。
• ⚡ 为并行而设计。 create count=8 会为每个工作进程启动一个桌面；fork 可在执行有风险的步骤前克隆桌面；会话之间彼此隔离。
• 🙋 支持人工介入。 浏览器中的实时视图支持一键接管控制、双向传输文件（将文件拖到屏幕上）和共享剪贴板。Agent 可以交接任务（“请登录”）并等待完成；手动登录后保存的登录状态，也会应用于新桌面。
• 🎞️ 教一次，反复回放。 每项操作都会被录制。可导出 HTML 时间线或 GIF，也可将会话转换为无需任何模型即可回放的 Python 脚本。
• 📦 零依赖。 主机端仅使用 Python 标准库。桌面可在 Docker 或 Podman 中运行（macOS、Windows、Linux），也可在 Linux 上原生运行。

在命令行中快速体验

任何拥有终端的 Agent（Claude Code、Codex CLI、Aider、Open Interpreter、Goose）都可以直接使用 CLI，而 minion skill --install 会教它如何使用：

minion up research
minion open en.wikipedia.org             # waits until the page has loaded
minion fill "Search Wikipedia" "Ada Lovelace" && minion key Return
minion wait-for "Analytical Engine"      # says where it saw the text
minion see --full                        # read the article as text
minion select @14 "Title"                # pick a dropdown option
minion shot -o page.png --marks          # a screenshot with @ids drawn on it
minion read ~/Downloads/paper.pdf         # any document as text: pdf, docx, xlsx, pptx, epub...
minion open gimp                          # any app by name: installed the first time
minion menu "File > Export As > Export as PDF..."   # any menu command
minion path ~/Documents/report.pdf        # fill the open Save/Open dialog
minion cp :~/Documents/notes.md .        # copy files out (and in)

_{菜单、文件对话框和按名称启动应用：menu "File > Export As > Export Directly as PDF"、path ~/Documents/report.pdf，然后执行 open gimp，GIMP 在 16 s 内完成安装。由飞行记录器录制。}

适用于所有 Agent

你的 Agent	连接方式
Claude Desktop/Code、Cursor、VS Code、Codex、Gemini CLI、opencode、OpenClaw、Windsurf/Devin、LM Studio、Kiro、Goose	一键连接、minion connect，或 uvx minion-desktop mcp（安装）
Agent 框架：OpenAI Agents SDK、LangChain/LangGraph、LlamaIndex、CrewAI、smolagents、Pydantic AI、Google ADK、AutoGen	同一个 MCP 服务（已验证的配置示例）
ChatGPT、Claude.ai、Le Chat（Web 应用）	minion share：通过 HTTPS 提供远程 MCP（文档）
任何支持函数调用的模型（OpenAI、Anthropic、Gemini、Mistral，通过 Ollama/vLLM 使用的本地模型）	Toolkit().definitions("openai" | "anthropic" | "gemini") + Toolkit().run_calls()（文档）
任何支持 HTTP 的工具（n8n、Dify、GPT Actions、任何编程语言）	minion serve → /api/tools/*、/mcp 和 /openapi.json（文档）
Shell Agent	minion CLI（文档）及其 Agent Skill（minion skill --install）
Python / TypeScript 代码	from minion import Desktop（文档）· clients/typescript
原生计算机使用模型	Claude 工具集（文档）· OpenAI 和 Gemini 计算机使用（文档）

使用任何兼容 OpenAI 的模型（"anthropic"、"gemini" 和 "openai-responses" 的工作方式相同）的完整 Agent：

from openai import OpenAI
from minion.tools import Toolkit

tk = Toolkit()
client = OpenAI()  # or OpenAI(base_url="http://localhost:11434/v1", api_key="ollama") for a local model
messages = [{"role": "user", "content": "On a research desktop, find the population of Iceland on Wikipedia."}]
while True:
    msg = (
        client.chat.completions.create(model="YOUR-MODEL", messages=messages, tools=tk.definitions("openai"))
        .choices[0]
        .message
    )
    messages.append(msg)
    if not msg.tool_calls:
        break
    messages += tk.run_calls(msg.tool_calls)  # runs every call, returns the messages to send back
print(msg.content)

Python 与代码模式

from minion import Desktop

with Desktop.create("office", keep=False) as desk:  # removed when the block ends
    desk.open("calc")
    result = desk.script("""
for item, price in [("Coffee", 3.5), ("Bagel", 2.25), ("Juice", 4)]:
    write(f"{item}\\t{price}\\n")             # Tab moves right, Return goes down
write("Total\\t=SUM(B1:B3)\\n")
print(cells()["B4"])                          # visible cells as {"A1": ...}
""")
    print(result.stdout)  # 9.75
    desk.key("ctrl+s")
    desk.fill("Name", "q3.xlsx")
    desk.key("Return")
    desk.wait_for("q3.xlsx")
    desk.download("~/Documents/q3.xlsx", ".")

script 会在桌面应用内部运行 Python，支持 click · write · key · scroll · fill · see · elements · cells · wait_for · launch · run。循环只需一次调用，返回内容仅包含代码打印的内容。Desktop API 还提供 screenshot · see · act · open · run · upload · download · clipboard · windows · freeze · fork · snapshot · restore · recording · create_many。详见 docs/python.md。

原生计算机使用（Claude、OpenAI、Gemini）

Minion 为各供应商的计算机使用模型提供了开箱即用的环境，并为你处理截图缩放和坐标映射：

import anthropic
from minion import Desktop
from minion.integrations.anthropic import MinionComputer, allow_all

desk = Desktop.create("office")
with MinionComputer(desk, confirm=allow_all) as computer:  # the desktop is the sandbox
    runner = anthropic.Anthropic().beta.messages.tool_runner(
        model="claude-opus-5-5",
        max_tokens=16000,
        tools=[computer],
        messages=[{"role": "user", "content": "Make a 3-slide deck about otters in Impress."}],
    )
    for message in runner:
        print(message)

Claude 的 computer_toolset_20260801（全部 17 项操作）和较早的 computer_20251124 详见 docs/computer-use.md。OpenAI 和 Gemini 的计算机使用详见 docs/computer-use-openai-gemini.md。

配置文件

配置文件	包含内容	下载大小	空闲 RAM
🌐 browser	Firefox 和 uBlock Origin（广告、跟踪器、Cookie 横幅、新闻邮件弹窗）；下载内容直接保存到 ~/Downloads；终端可通过 see 读取	363 MB	~55–100 MB
📄 office	LibreOffice Writer、Calc、Impress + 文本编辑器 + 文件管理器 + Firefox + PDF 工具。默认保存为 Microsoft 格式，并且准确输入 Agent 发来的内容（不使用自动更正）	526 MB	~85 MB
🛠️ dev	git、Python、Node.js、构建工具、Geany IDE、可通过 see 读取的真实终端、Firefox + Chromium	714 MB	~55 MB
🔎 research	Firefox + pdftotext、pandoc、笔记编辑器、带有 requests 和 BeautifulSoup 的 Python	422 MB	~55 MB
📊 data	office + pandas、NumPy、SciPy、matplotlib、seaborn、openpyxl、SQLite	674 MB	~105 MB
🪟 windows	Wine 10，可运行 64 位和 32 位 Windows .exe/.msi 程序，另有 Firefox 可用于下载这些程序。适用于 x86-64 主机（文档）	717 MB	~56 MB（打开程序时约 270 MB）
🧩 base	X server、窗口管理器、终端和 Agent。可在此基础上构建	199 MB	~65 MB

自定义配置文件是 ~/.config/minion/profiles/ 中的一个 5 行 TOML 文件。首次使用时会自动构建：

# ~/.config/minion/profiles/designer.toml
extends = "browser"
description = "Firefox plus GIMP and Inkscape."
packages = ["gimp", "inkscape"]
apps = [{ name = "GIMP", command = "gimp" }, { name = "Inkscape", command = "inkscape" }]

也可以在运行时添加软件：minion run "minion-install gimp https://example.com/tool.AppImage pip:yt-dlp"。 请参阅 docs/profiles.md。

Agent 如何查看屏幕

see 是 Agent 的主要感知工具。以下是它在 LibreOffice 窗口中的效果：

Screen 1280x800 · 1 window
  [1] "Untitled 1 — LibreOffice Writer" — libreoffice-writer (focused) at 0,0 1280x770

UI of "Untitled 1 — LibreOffice Writer" (click/fill with @id; (x,y) is the element center):
@1 menu "File" (22,38)
@2 menu "Edit" (62,38)
…
@12 document text "Untitled 1 - LibreOffice Document" [editable] (603,424)
  @13 heading "Q3 Market Brief" (603,247)
  @14 paragraph "Prepared by an AI agent on a Minion desktop. No human touched the keyboard." (603,282)

执行操作后，observe="changes"（或 see(changes=true)）只会返回差异：

✓ typed 30 chars
→ screen changed <1% (region 404,226 236x20)
Changes since your last look 1.0s ago (81 elements unchanged; their @ids still work):
  + @84 paragraph "Quarterly numbers look strong." [focused] (603,234)
  ~ @80 label "4 words, 30 characters" (281,730)

对于辅助功能无法读取的文本（例如幻灯片、画布应用、文字图片、远程屏幕，或没有辅助功能树的程序），会使用 OCR 读取；OCR 只处理缺失的文本，并使用屏幕自身的语言：窗口标题和标签中的文字所用的文字系统会决定 OCR 语言。内置支持希伯来语、阿拉伯语、俄语、中文、日语、韩语和印地语，其他语言会在首次使用时安装。大号文字和彩色背景上的浅色文字会分别进行识别；未发生变化的图片绝不会重复读取。在拍摄的 24 张希伯来语幻灯片中，see 能读取 94% 的文字。以下是它在一个以图片形式显示幻灯片的网页中的效果：

@2 heading "Board meeting, October 15" (640,131)
@3 paragraph "The slides from the quarterly review:" (640,186)

Text in the picture at 0,117 800x480 (OCR: accessibility doesn't have it):
  @4 "Q3 review" (146,254)
  @5 "Revenue grew 12% to $4.1M" (218,348)
  @6 "1,240 new customers, churn down to 2.1%" (291,404)
  @7 "Next: launch in Japan and Brazil" (239,460)
  @8 "| Goal: $5M in Q4" (163,555)

需要关注像素时，screenshot --marks 会为每个控件标注其 @id：

效率实测

**五项真实任务（PDF 报告、电子表格、Wikipedia 查询、网页表单、阅读文档）使用 Minion 时消耗 8,668 个 token，使用屏幕截图时消耗 50,505 个 token：减少了 5.8 倍。**完整表格和方法见 docs/benchmarks.md；运行 python scripts/bench_tasks.py 即可复现。

	Token 数
1280×800 屏幕截图	~1,365	基准值
screenshot(detail="low")	~341	尺寸减半
act(observe="crop")，仅限发生变化的区域	~200
see 查看 LibreOffice 窗口	~920	精确文本 + 可点击的 ID
输入一句话后调用 see(changes=true)	~80	稳定的 ID，仅返回差异
see 查看终端	~50–90
工具定义：9 个工具 / 精简版 computer	~3,300 / ~450	每次请求都会发送
输入 5 行电子表格内容：act ×5 / script ×1	5 次调用 / 1 次调用	每个步骤无需与模型往返通信

资源
启动就绪时间	1.2–1.8 s（所有配置文件均适用）
空闲 RAM	每个桌面 54–105 MB（打开 Firefox/LibreOffice 时会额外占用内存）
冻结时	CPU 占用 0.00%，下次调用时约 0.2 s 内恢复
并行运行 3 个桌面	3.0 s

这些数据是在一台 2-vCPU 虚拟机上测得的。运行 python scripts/bench.py 即可复现。

观察、接管、交接

minion view（或 view 工具）会在浏览器中打开任意桌面的实时视图。点击 接管控制，即可使用自己的鼠标和键盘。Agent 可以调用 view(message="Please sign in to your Google account")：你会看到提示横幅，登录后按 完成，Agent 就会继续操作。文件可从桌面下载文件并上传文件到桌面（也可以将文件拖到屏幕上），复制可将桌面的剪贴板内容复制到你的剪贴板，按键可发送浏览器允许的按键（Ctrl+W、Alt+Tab）。

登录一次，即可启动已登录的桌面：minion login github https://github.com/login 会在实时视图中打开相应桌面，你登录后按 完成，之后 minion up --login github（或 desktop(action="create", login="github")）启动的桌面都会自动登录。登录信息保存在你电脑的 Docker 中（详情）。minion serve 会添加一个包含桌面实时缩略图的仪表板：

工作原理

flowchart LR
  subgraph host["Your machine"]
    A["Any agent<br/>(MCP, function calling, HTTP, CLI, SDK)"] --> T["minion tools<br/>(pure-stdlib Python)"]
    T --> V["Live view and dashboard<br/>(minion serve)"]
  end
  subgraph desk["Desktop (one container each)"]
    S["minion agent<br/>RPC over docker exec"] --> X["Xvfb + JWM"]
    S --> AT["AT-SPI<br/>accessibility tree"]
    S --> O["Tesseract OCR"]
    S --> C["code mode<br/>(Python inside)"]
    X --> Apps["Firefox · LibreOffice · Terminal · Wine · …"]
  end
  T -->|"docker exec (no open ports)"| S

请阅读 docs/design.md，了解每项选择背后的原因；阅读 docs/architecture.md，了解内部实现。

安全性

每个桌面都是一个默认不挂载宿主机目录的非特权容器。使用 --offline 可切断网络访问，或通过 --memory 和 --cpus 限制资源。HTTP 服务绑定到 127.0.0.1，需要随机令牌，并会拒绝跨站和 DNS 重绑定请求。与电脑之间传输的文件都限制在一个文件夹内；minion share 网址包含一个新生成的令牌，停止共享后便会失效。桌面用户在容器内部拥有无需密码的 sudo 权限，因此 Agent 可以安装软件。请将屏幕上的所有内容都视为不可信输入（提示词注入），并避免在桌面中保存凭据，除非由人工交接。请阅读 SECURITY.md。

文档

网站 · 安装 · 连接你的应用 · 远程 MCP · 设计 · Agent 与 MCP · 集成 · CLI · Python · HTTP API · Claude 计算机使用 · OpenAI 与 Gemini 计算机使用 · 配置文件 · 按名称查找应用 · Windows 应用 · 架构 · 常见问题

参与贡献

欢迎在 讨论区提出问题和想法，也欢迎在 问题追踪区报告 Bug。要帮助构建 Minion，请选择一个适合新手的问题（翻译、应用、Agent 应用、基准测试任务），阅读 CONTRIBUTING.md，并查看路线图，了解项目的发展方向。

许可证

MIT。桌面环境包含各自遵循其许可证的开源软件（Debian、Firefox、LibreOffice、Wine，等等）。