机械臂远程控制

概述

核心原则

1. 只发 HTTP 请求：将用户意图转为 HTTP 调用，由机械臂侧的 HTTP 网关执行。
2. 禁止生成代码：不要写 Python、不要 SSH、不要 conda；驱动逻辑在网关内完成。
3. 每次一个动作：多步任务逐步发送，上一步完成后再发下一步。
4. 对用户说人话：用自然语言汇报结果，不要把原始 JSON 贴给用户（除非用户要求）。

前置条件

本 Skill 不包含机械臂驱动。使用前必须在机械臂侧（Ubuntu 边缘机）部署符合 [api-contract.md](api-contract.md) 的 HTTP 网关。

• Piper + GraspGen：在 Ubuntu 上部署参考网关后，用 bash start_arm_control.sh 启动，见 [deploy.md](deploy.md)。
• 无真机验证：可用仓库中的 mock_gateway.py 模拟相同 API，见 [deploy.md](deploy.md)。
• 其他品牌：自行实现网关，保证 /health、/status、/control 契约一致即可。

网关配置

读取 skills.entries.robot-control.config（OpenClaw / WorkBuddy 配置）：

未配置 baseUrl 时：先询问用户网关 IP 和端口，建议写入配置后长期使用。192.168.1.210 仅为文档占位，不要当作真实地址去探测。

{
  "skills": {
    "entries": {
      "robot-control": {
        "enabled": true,
        "config": {
          "baseUrl": "http://192.168.1.210:5000",
          "profile": "piper"
        }
      }
    }
  }
}

端点速查

POST Header：Content-Type: application/json

启动检查清单

用户首次使用或动作失败时，按序检查：

1. GET {baseUrl}/health → 网关在线
2. GET {baseUrl}/status → arm.enabled、arm.arm_status_text == "normal"
3. 视觉抓取前 → grasp.ros_available == true、grasp.has_target == true
4. 运动前 → arm.busy == false、grasp.in_progress == false

任一步失败，向用户说明原因并给出可操作建议，不要继续发运动类指令。

查状态（最重要）

用户问「机械臂什么状态」「关节多少」「有没有检测到物体」「能不能抓」时，优先 GET /status，不要 POST。

GET {baseUrl}/status

兼容：POST /control + {"action":"get_status","params":{}}

profile 为 piper（默认）：字段与动作见 [profiles/piper.md](profiles/piper.md)。

查状态时机

• 用户明确问状态
• 关节运动前读当前关节角
• 视觉抓取前确认 grasp.has_target
• 抓取后轮询 GET /grasp/status 直到 in_progress 为 false（间隔 3–5 秒，最多约 60 秒）

状态汇报模板（Piper）

成功时向用户汇报：使能状态、安全状态（normal/急停等）、六轴关节角（度）、夹爪开合（毫米）；若存在 grasp 块，补充视觉是否在线、是否有目标、是否抓取中。

执行步骤（控制类动作）

1. 确认 baseUrl 已配置；未配置则追问。
2. 按 profile 加载动作目录（默认 [profiles/piper.md](profiles/piper.md)）。
3. 解析用户意图，映射到 HTTP 接口。
4. 参数不足时追问，不猜测危险值。
5. 执行 [启动检查清单](#启动检查清单) 中相关项。
6. 立即发起 HTTP 请求。
7. 根据 status 用自然语言告知成功或失败。

HTTP 请求格式

POST /control

POST {baseUrl}/control
Content-Type: application/json

{"action":"<动作名>","params":{...}}

params 无参数时写 {}，不可省略。

POST /grasp

POST {baseUrl}/grasp
Content-Type: application/json

{}

可选：{"require_target": false} 强制触发（默认须先有视觉目标）。

意图映射（通用）

安全约束（通用）

1. 只向用户确认过的 baseUrl 发请求；不扫描网段、不猜测他人 IP、不控制未授权设备。
2. 同一时间只发一条运动指令；arm.busy == true 时不发新的运动类指令。
3. 抓取进行中（grasp.in_progress == true）不发 home 或关节运动。
4. 速度默认适中（Piper 默认 50%），用户未明确要求不超 70%。
5. HTTP 失败或 status == "error" 时停止后续动作并报错。
6. 只发送 profile 中已文档化的 action；见 Piper [不支持列表](profiles/piper.md#当前不支持勿发送)。

响应处理

成功

{"status": "ok", ...}

→ 用自然语言告知完成。

失败

{ "status": "error", "message": "...", "hint": "..." }

更多资料

• HTTP 契约：[api-contract.md](api-contract.md)
• Piper 动作与字段：[profiles/piper.md](profiles/piper.md)
• 对话示例：[examples.md](examples.md)
• 网关部署：[deploy.md](deploy.md)