Ghost OS

为AI智能体提供完整的计算机操作能力。

你的AI智能体可以编写代码、运行测试、搜索文件，但它无法点击按钮、发送邮件或填写表格。它只能待在聊天框里。

Ghost OS改变了这一切。只需一次安装，任何AI智能体都能看到并操作你Mac上的每一款应用。

认识Specter Ghost OS为AI智能体提供了“眼睛”和“双手”。Shadow为它们提供了记忆。而Specter则为它们打造了一个家园。 在90秒内将持久化的AI智能体部署到专用的虚拟机中。自动DNS、TLS加密、systemd加固。交互式TUI仪表盘。基础设施完全由你掌控。 值得信赖的AI智能体。

认识Shadow Shadow是故事的另一面。Ghost OS让AI智能体在你的Mac上拥有“眼睛”和“双手”，而Shadow则赋予它们记忆与智慧。 14种模态的数据采集。主动建议。会话片段生成。设备端LLM推理。计算机使用训练数据。所有功能均本地运行，且全部开源。 你的电脑一直在默默关注着你。

最新动态  

自学习配方。 向Ghost OS展示一次如何完成某项任务，它便会永久记住。

• ghost_learn_start -- 开始观察用户执行任务
• ghost_learn_stop -- 停止并返回增强后的动作序列
• ghost_learn_status -- 检查录制进度

用户手动完成任务（点击、输入、切换应用）。Ghost OS通过CGEvent监听器，并结合辅助功能树上下文，观察每一个动作。Claude将原始观测结果合成一个可参数化、可重复执行的配方。

无需截图，也不需要视觉模型，仅依靠辅助功能树以及你的键盘和鼠标即可。

用户:    "看我发一封邮件。"
智能体:   ghost_learn_start task_description:"在Gmail中发送邮件"
         ...用户执行任务...
智能体:   ghost_learn_stop
         -> 8个带有完整AX上下文的动作
         -> 合成包含3个参数的配方：收件人、主题、正文
         -> ghost_recipe_save
用户:    "给bob发一封关于Q4报告的邮件"
智能体:   ghost_run recipe:"gmail-send-learned" params:{...}

需要输入监控权限（系统设置 > 隐私与安全性 > 输入监控）。请运行ghost setup进行配置。

感谢超过500位为本项目点赞的朋友们。正是你们的支持让我们不断前行。如果你希望直接参与贡献，我们非常欢迎。详情请参阅CONTRIBUTING.md。

你:     "给sarah@company.com发一封关于Q4报告的邮件"
智能体:   ghost_run recipe:"gmail-send" params:{recipient, subject, body}
         → 邮件编辑界面打开，字段自动填充，邮件成功发送。完成。

安装

配方实战

发送邮件、下载论文——任何应用，任何流程。

超越浏览器

Slack消息、Finder文件夹——Ghost OS操作的是原生macOS应用，而不仅仅是浏览器。

为什么选择Ghost OS？

其他计算机使用工具通常截屏后猜测屏幕内容，而Ghost OS则直接读取macOS的辅助功能树——这是一种结构化、带标签的数据，描述了每个应用中的每一个元素。当辅助功能树不足以解决问题时（如网页应用或动态内容），它会回退到本地视觉模型（ShowUI-2B）进行视觉定位。

一旦识别出工作流程，Ghost OS就会将其保存下来。而其他工具每次都需要重新进行昂贵的推理计算。

• 自学习 — 由前沿模型一次性确定工作流程，再由小型模型长期执行。
• 透明 — 配方以JSON格式呈现，每一步都清晰可见，不存在黑箱操作。
• 原生 — 优先使用辅助功能树，必要时才回退到视觉模型。以结构化数据代替像素级猜测。
• 适用于任何应用 — 不限于浏览器。Slack、Finder、Messages等，你Mac上的任何应用都可以操作。
• 本地运行 — 你的数据始终保留在本地设备上。
• 开源 — 使用MCP协议，可与Claude Code、Cursor、VS Code或其他MCP客户端无缝对接。

安装

brew install ghostwright/ghost-os/ghost-os
ghost setup

就是这样。ghost setup 会处理权限、MCP 配置、配方安装以及视觉模型的设置。

curl -sL https://github.com/ghostwright/ghost-os/releases/latest/download/ghost-os-2.2.1-macos-arm64.tar.gz | tar xz
sudo cp ghost /opt/homebrew/bin/
sudo cp ghost-vision /opt/homebrew/bin/
sudo mkdir -p /opt/homebrew/share/ghost-os
sudo cp GHOST-MCP.md /opt/homebrew/share/ghost-os/
sudo cp -r recipes /opt/homebrew/share/ghost-os/
sudo cp -r vision-sidecar /opt/homebrew/share/ghost-os/
ghost setup

工作原理

Ghost OS 通过 MCP 连接到你的 AI 助手，并为其提供 29 种工具，使其能够查看并操作你的 Mac。它会读取 macOS 的辅助功能树，获取关于每个应用的结构化数据。对于 AX 树无法充分覆盖的 Web 应用（如 Gmail、Slack），本地视觉模型（ShowUI-2B）会从视觉上识别元素。点击、输入、悬停、拖拽、滚动、按键、管理窗口——无论什么应用，而不仅限于浏览器。

你：     “从 arXiv 下载最新的关于思维链提示的论文”
助手：   ghost_run recipe:"arxiv-download" params:{query:"chain of thought prompting"}
         → 导航到 arXiv，搜索，打开 PDF，下载到桌面。完成。

它可以与 Claude Code、Cursor、VS Code 或任何支持 MCP 协议的工具一起工作。

配方

当你的助手找到一个工作流程时，它会将其保存为配方。配方是一个包含步骤、参数和等待条件的 JSON 文件。透明且可审计。

由前沿模型一次性确定工作流程，再由小型模型永久执行。

# 一条命令即可发送邮件
ghost_run recipe:"gmail-send" params:{"recipient":"hello@example.com","subject":"Hello","body":"World"}

# 7 步骤，30 秒，100% 可靠

• 配方只是 JSON 文件。运行前请仔细阅读每一步。
• 可以与团队共享。只需一人学习工作流程，全员受益。
• 可以将多个配方串联起来。助手会知道何时调用哪个配方。
• 使用 Claude 或 GPT-4 编写一次，然后用 Haiku 永久执行。

29 种工具

诊断

$ ghost doctor

  [ok] 辅助功能：已授权
  [ok] 屏幕录制：已授权
  [ok] 输入监控：已授权（用于学习模式）
  [ok] 进程：1 个 ghost MCP 进程
  [ok] MCP 配置：ghost-os 已配置
  [ok] 配方：5 个已安装
  [ok] AX 树：12/12 个应用可读
  [ok] ghost-vision：/opt/homebrew/bin/ghost-vision
  [ok] ShowUI-2B 模型：~/.ghost-os/models/ShowUI-2B（3.0 GB）
  [ok] 视觉 Sidecar：未运行（将在需要时自动启动）

  所有检查均通过。Ghost OS 运行正常。

从源码构建

git clone https://github.com/ghostwright/ghost-os.git
cd ghost-os
swift build
.build/debug/ghost setup

需要 Swift 6.2 及以上版本和 macOS 14 及以上版本。

架构

AI 助手（Claude Code、Cursor、任何 MCP 客户端）
    │
    │ MCP 协议（stdio）
    │
Ghost OS MCP 服务器（Swift）
    │
    ├── 感知 ──── 查看屏幕上的内容（AX 树）
    ├── 视觉 ───── 视觉定位（ShowUI-2B，本地）
    ├── 行动 ───── 点击、输入、滚动、按键
    ├── 配方 ───── 自学习的工作流程
    └── AXorcist ─── macOS 辅助功能引擎

约 7,000 行 Swift 代码加上 Python 视觉 Sidecar。基于 @steipete 的 AXorcist 构建。

贡献

请参阅 CONTRIBUTING.md。我们需要更多应用的配方、不同环境下的测试以及错误报告。如果你正在构建能够真正做事的 AI 助手，那么这就是你需要的项目。

贡献者

感谢所有为 Ghost OS 做出贡献的人。

许可证

MIT

Ghost OS 快速上手指南

Ghost OS 是一款专为 macOS 设计的开源工具，赋予 AI 智能体（Agent）“眼睛”和“双手”，使其能够直接操作本地应用程序（如 Slack、Finder、浏览器等），而不仅限于聊天窗口。它通过读取 macOS 辅助功能树（Accessibility Tree）结合本地视觉模型，实现安全、透明且可学习的自动化工作流。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：macOS 14.0 (Sonoma) 或更高版本。
• 架构支持：Apple Silicon (ARM64) 或 Intel Mac。
• 构建依赖（仅源码编译时需要）：Swift 6.2+。
• 客户端工具：需配合支持 MCP (Model Context Protocol) 的 AI 客户端使用，例如 Claude Code、Cursor 或 VS Code。

安装步骤

推荐使用 Homebrew 进行一键安装，这是最简便的方式。

方法一：Homebrew 安装（推荐）

1. 打开终端，运行以下命令添加源并安装：

   brew install ghostwright/ghost-os/ghost-os
   

2. 初始化配置（自动处理权限、MCP 配置及模型下载）：

   ghost setup
   

   注意：运行此命令后，系统可能会弹出“输入监控”、“辅助功能”和“屏幕录制”的权限请求，请务必在“系统设置 > 隐私与安全性”中全部允许，否则工具无法正常工作。

方法二：手动安装（适用于 macOS Beta 版用户）

如果 Homebrew 在开发者预览版系统中报错，可使用以下手动安装脚本：

curl -sL https://github.com/ghostwright/ghost-os/releases/latest/download/ghost-os-2.2.1-macos-arm64.tar.gz | tar xz
sudo cp ghost /opt/homebrew/bin/
sudo cp ghost-vision /opt/homebrew/bin/
sudo mkdir -p /opt/homebrew/share/ghost-os
sudo cp GHOST-MCP.md /opt/homebrew/share/ghost-os/
sudo cp -r recipes /opt/homebrew/share/ghost-os/
sudo cp -r vision-sidecar /opt/homebrew/share/ghost-os/
ghost setup

验证安装

运行诊断命令检查所有权限和服务状态：

ghost doctor

若输出显示所有项均为 [ok]，则表示安装成功。

基本使用

Ghost OS 的核心在于让 AI 智能体通过 MCP 协议调用其提供的 29 个工具来操作电脑。以下是两种主要的使用场景：

1. 连接 AI 智能体执行任务

配置好 MCP 后，您可以在支持的 AI 客户端（如 Cursor 或 Claude Code）中直接下达自然语言指令。Ghost OS 会自动解析并操作界面。

示例场景：下载论文 用户在对话框中输入：

"Download the latest paper on chain-of-thought prompting from arXiv"

AI 智能体将自动调用 ghost_run 执行预置的食谱（Recipe）：

Agent: ghost_run recipe:"arxiv-download" params:{query:"chain of thought prompting"}
→ 自动导航至 arXiv，搜索关键词，打开 PDF 并下载到桌面。

2. 手动调用工具与自学习模式

您也可以直接在终端或通过 MCP 调试工具调用具体命令。Ghost OS 最大的亮点是**自学习（Self-learning）**功能：您可以演示一次操作，它会记录并生成可复用的 JSON 食谱。

开启学习模式： 告诉 AI 开始观察您的操作：

# AI 调用此工具开始记录
ghost_learn_start task_description:"send email in Gmail"

执行操作： 此时，请您手动在电脑上完成一次完整任务（例如：打开 Gmail -> 点击撰写 -> 填写收件人/主题/正文 -> 发送）。Ghost OS 会通过 CGEvent 监听并记录每一步的辅助功能上下文。

结束学习并保存： 完成任务后，通知 AI 停止记录：

# AI 调用此工具停止记录并合成食谱
ghost_learn_stop

系统将自动生成一个包含参数（如收件人、主题）的 JSON 食谱。下次只需运行：

ghost_run recipe:"gmail-send-learned" params:{recipient:"bob@example.com", subject:"Report", body:"..."}

即可自动重放该流程。

核心工具速查

Ghost OS 提供了一系列精细的控制工具，常用包括：

• ghost_context: 获取当前应用、窗口标题及屏幕上所有可交互元素。
• ghost_click: 点击指定名称、ID 或坐标的元素。
• ghost_type: 向指定字段输入文本。
• ghost_screenshot: 截取当前窗口用于视觉调试。
• ghost_ground: 当辅助功能树无法识别时（如复杂网页），使用本地视觉模型定位元素坐标。

通过以上步骤，您已可以让 AI 真正“操作”您的 Mac，实现从代码编写到应用交互的全流程自动化。