GBOX

GBOX 提供了让AI代理操作计算机和移动设备的环境。

移动场景： 您的代理可以使用GBOX来开发/测试Android应用，或者在Android上运行应用以完成各种任务（移动自动化）。

桌面场景： 您的代理可以使用GBOX来操作桌面应用，如浏览器、终端、VSCode等（桌面自动化）。

MCP： 您还可以将GBOX MCP插件到任何您喜欢的代理中，例如Cursor、Claude Code。这些代理将立即获得操作计算机和移动设备的能力。

安装

系统要求

• MacOS
  • 版本：10.15或更高版本
  • Homebrew

注意：在其他平台上使用gbox，请查看npm包@gbox.ai/cli中的安装说明。您也可以登录GBOX.AI以使用基于Web的仪表板。

安装步骤

快速安装（推荐）

选项1：仅安装GBOX CLI

curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash

这只会安装GBOX CLI。当需要时，额外的依赖项（如ADB、frpc、Appium）将自动安装，或者您可以稍后使用以下命令进行安装：

gbox setup

选项2：安装所有依赖项（一步设置）

curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- --with-deps

这会一次性安装所有内容：

• GBOX CLI
• Node.js 和 npm（如果不存在）
• Android 调试桥（ADB）
• FRP 客户端（frpc）
• Appium 服务器、驱动程序和插件

非交互模式：

# 仅CLI
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- -y

# 包括所有依赖项
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- -y --with-deps

其他安装方法

通过Homebrew（macOS）：

brew install gbox

通过npm（Linux/Windows）：

npm install -g @gbox.ai/cli

设置依赖项

如果您仅安装了GBOX CLI，可以随时安装所有命令依赖项：

gbox setup

或者交互式安装它们：

gbox setup -y

更新GBOX CLI

保持您的GBOX CLI最新：

使用安装脚本：

# 交互式更新（已安装时会提示）
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash

# 强制更新且不提示
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- --update

# 即使有新版本也跳过更新
curl -fsSL https://raw.githubusercontent.com/babelcloud/gbox/main/install.sh | bash -s -- --update=false

使用Homebrew（macOS）：

brew upgrade gbox

使用npm（Linux/Windows）：

npm update -g @gbox.ai/cli

开始使用

# 登录到gbox.ai
gbox login

# 连接您的Android设备（缺少时将自动安装依赖项）
gbox device-connect

# 导出MCP配置并合并到Claude Code/Cursor
gbox mcp export --merge-to claude-code
gbox mcp export --merge-to cursor

命令行用法

查看详细用法请参阅GBOX CLI 参考。

SDK 用法

查看详细用法请参阅GBOX SDK 参考。

将GBOX作为MCP服务器使用（需登录）

使用GBOX CLI配置MCP服务器到您的Claude Code/Cursor：

# 导出MCP配置给Cursor
gbox mcp export --merge-to cursor

# 导出MCP配置给Claude Code
gbox mcp export --merge-to claude-code --scope project

或者将以下内容复制粘贴到您的Claude Code/Cursor MCP配置中：

{
  "mcpServers": {
    "gbox-android": {
      "command": "npx",
      "args": [
        "-y",
        "@gbox.ai/mcp-server@latest"
      ]
    }
  }
}

注意：

• 目前，GBOX MCP只能控制Android环境。
• 如果您需要Cursor/Claude Code控制您的本地Android设备，请参阅注册本地设备

Android MCP 使用案例

使用案例	演示
Claude Code 开发/测试Android应用
Claude Code 比较电子商务应用的价格

环境

目前，GBOX支持以下环境：

• Android
• Linux桌面/浏览器

Android环境

有三种类型的Android环境，您可以根据需求选择：

1. 云虚拟设备：

登录GBOX.AI获取一个云虚拟设备。最适合测试和开发。

2. 云物理设备：

登录GBOX.AI获取一个云物理设备。云物理设备是一台真实的Android手机，可用于生产场景。

3. 本地物理设备：

使用自己的物理设备注册本地设备。您的本地设备可以是任何启用了开发者模式的Android设备。最适合生产场景和个人使用。

Linux桌面/浏览器环境

登录GBOX.AI获取一个Linux桌面/浏览器环境。最适合测试和开发。

开发gbox

预备条件

• Go 1.21或更高版本
• Make
• pnpm（通过corepack）
• Node.js 16.13或更高版本

构建

# 为当前平台构建
make build

# 为所有平台构建
make build-all

# 创建分发包
make dist

运行服务

# MCP服务器
cd packages/mcp-server && pnpm dev

# MCP检查器
cd packages/mcp-server && pnpm inspect

贡献

我们欢迎贡献！请随意提交Pull Request。对于重大更改，请先打开一个问题来讨论您想要更改的内容。

1. 分叉仓库
2. 创建您的功能分支（git checkout -b username/feature-name）
3. 提交您的更改（git commit -m '添加某些功能'）
4. 推送到分支（git push origin username/feature-name）
5. 打开一个Pull Request

关于本地开发和调试需要注意的事

许可证

此项目根据Apache许可证2.0发布 - 详情见LICENSE文件。