OrbitPilot

使用文档

如何使用 OrbitPilot

快速开始、使用场景、Agent Skills、MCP 服务、移动端配对与 API 接入说明。

返回首页

如何使用 OrbitPilot

OrbitPilot 是连接 AI Agent 与已注册 Android 真机的云端控制平面。Agent 提交目标与结构化自动化步骤；云端负责调度、安全策略与状态管理，并由设备端的 AutoPilot 完成点击、输入、滑动与截图观察。

快速开始

  1. 在 /register 注册账号，或在 /login 登录。
  2. 在控制台 设备 页面 注册设备，复制一次性 device token（仅显示一次）。
  3. 在手机上 安装 AutoPilot（见下方 移动端（AutoPilot））。
  4. 在 设置 -> API Keys 创建 API Key，按 Agent 需要勾选 scope。
  5. 通过 SKILLS.md、MCP 或直接调用 POST /v1/tasks 接入 Agent。

控制台（Dashboard）用于管理设备、任务、计划、人工确认与 API Key。复杂规划由外部 Agent 完成；OrbitPilot 专注执行、调度、可观测性与安全护栏。

使用场景

场景说明
立即执行Agent 提交任务；云端选择在线设备；AutoPilot 执行步骤；截图与状态回传；Agent 收到完成结果或确认请求。
定时任务保存 cron 或周期计划；Worker 唤醒任务、分配设备、记录日志；失败可通过控制台或 Webhook 跟进。
人工确认发布公开内容、私信等高风险操作前暂停；操作者在控制台批准或拒绝后继续或终止。
运维监控运营人员通过控制台查看设备清单、任务时间线、截图历史与待确认队列，无需写代码。

当前 MVP 以 Android 为主；支付与购买类操作在策略层禁止。

控制台

登录后打开 /app/overview 查看设备与任务概览。

模块用途
设备注册手机、查看在线/忙碌状态、吊销 token
任务创建、查看与取消自动化运行
计划管理一次性或周期性调度
确认批准或拒绝暂停的高风险步骤
设置API Key、Webhook、个人资料

界面支持 中英文 切换（页头语言工具）以及 浅色 / 深色 主题。

Agent Skills

Skills 是供 AI 客户端（Cursor、Claude Code、Codex 等）加载的 Markdown 说明。OrbitPilot 提供：

  • 仓库根目录 SKILLS.md — Agent 用的完整 HTTP / WebSocket 约定
  • .agents/skills/orbitpilot-api/ — 面向集成的精简 Skill（API Key、任务、设备、Webhook）

当 Agent 需要列出设备、创建任务、处理 Webhook 或通过 WebSocket（/ws）配对 AutoPilot 时，让其读取 SKILLS.md。

典型外部规划流程：

  1. 使用 devices:read 调用 GET /v1/devices 获取设备列表
  2. 使用 tasks:write 调用 POST /v1/tasks 下发结构化步骤
  3. 轮询任务状态或通过 Webhook 接收事件
  4. 在控制台或 Webhook 载荷中处理 confirmation_required

每个 API Key 仅申请 最小 scope。控制台概览需要同时具备 devices:read 与 tasks:read。

MCP 服务

@orbitpilot/mcp-server 将 OrbitPilot HTTP API 封装为 MCP 工具（前缀 orbitpilot_，例如 orbitpilot_list_devices、orbitpilot_create_task）。当客户端（Cursor、VS Code、Windsurf）使用 Model Context Protocol 而非直接 REST 时，优先使用 MCP。

运行模式

模式适用场景认证方式
stdio本地开发；由 Cursor 拉起子进程在 server env 中配置 ORBITPILOT_API_KEY
HTTP生产或团队共享 MCP（HTTPS）每次请求 Authorization: Bearer opk_... 或 X-Api-Key

本地 stdio（在仓库根目录）：

ORBITPILOT_API_KEY=opk_xxx pnpm mcp:dev

本地 HTTP：

pnpm mcp:dev:http
# 默认 http://127.0.0.1:5151

Cursor（远程 HTTP） — 配置 ~/.cursor/mcp.json 或项目 .cursor/mcp.json：

{
  "mcpServers": {
    "orbitpilot": {
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer opk_your_key_here"
      }
    }
  }
}

生产环境 MCP 在栈内监听 127.0.0.1:5151，由 nginx 等反向代理对外暴露，并设置 MCP_PUBLIC_URL。更多客户端与 Docker 说明见 packages/mcp-server/README.md。

移动端（AutoPilot）

AutoPilot 是 Android 客户端：通过 WebSocket 连接 OrbitPilot 云端，在无障碍服务授权下执行界面操作。

环境要求

  • Android 8.0 及以上（真机或模拟器）
  • 已在控制台注册设备并持有有效 device token
  • 按提示开启 OrbitPilot 无障碍服务
  • Android 13+ 请允许 通知权限，以便前台服务保持连接

安装与配对

  1. 在落地页 安卓客户端 区块下载 APK（需配置 NEXT_PUBLIC_AUTOPILOT_APK_URL），或从 apps/autopilot-android 自行构建。
  2. 打开 AutoPilot，填写 WebSocket 地址（如 wss://api.example.com/ws）与 device token。
  3. 在控制台 设备 中确认设备为 在线。

AutoPilot 上报心跳与忙碌/空闲状态，避免同一台手机被过度并发占用。

HTTP API 与 Webhook

  • REST 路由均在 /v1 下（如 POST /v1/tasks、GET /v1/devices）。
  • 机器调用使用 API Key（opk_...），请求头 Authorization: Bearer 或 X-Api-Key。
  • 浏览器会话使用 POST /v1/auth/login 设置的 Cookie。

Webhook：在 设置 -> Webhooks 配置回调地址。按 SKILLS.md 使用密钥与请求头对 完整 JSON 正文 做 HMAC 校验。切勿在日志中输出 opk_、device token 或 webhook 明文密钥。

部署启用时，可在 API 主机访问 /v1/docs 查看 OpenAPI/Swagger。

安全建议

  • 将 device token 与 API Key 视为一次性或可轮换机密。
  • 对发布、外发消息等操作启用人工确认。
  • MVP 禁止支付相关步骤；关注任务步骤上的 orbit_risk。
  • 为每个集成申请最小 scope 集合。

下一步