养个小龙虾教你用小龙虾控制七轴臂的方法

OpenClaw 近期的热度持续攀升，作为一款广受关注的开源项目，它大幅降低了机械臂控制的入门难度——操作逻辑清晰直观，设备兼容性出色，更重要的是，它能够实现从 AI 自然语言指令到机械臂实际动作的完整闭环。简单来说，你只需要用自然语言描述需求，它就能自动生成可执行的机械臂控制代码。本文聚焦实际部署，结合 pyAgxArm SDK，完整演示从下载、安装到配置的全过程，最终实现对 NERO 七轴机械臂的高效操控。我们直接进入正题。

视频 DEMO

www.bilibili.com/video/BV1qG…

一、下载与安装 openclaw

• 访问 openclaw 官网：openclaw.ai/
• 点击 Quick Start 标签，运行一键安装脚本即可完成部署

二、开始配置 OpenClaw

• 推荐选择 QWEN 模型，运行稳定性表现良好
• 勾选全部 hook 选项，便于后续功能扩展
• 配置完成后，通过 web 端页面进入管理界面

二、告诉 OpenClaw 学会 Skill 以及控制机械臂的规则

此时需要创建 skill 文件，让 OpenClaw 掌握如何根据自然语言描述自动生成机械臂控制代码。在 skill 目录下新建一个名为 agx_arm_codegen 的文件夹，然后放入以下两个文件：

SKILLS.md

---
name: agx-arm-codegen
description: 引导 OpenClaw 根据用户自然语言生成基于 pyAgxArm 的机械臂控制代码。当用户用提示词描述机械臂动作且现有脚本无法直接满足时，根据本技能提供的 API 与示例自动组织并生成可执行的 Python 脚本。
metadata:{
  "openclaw":{
    "emoji": "烙",
    "requires": { "bins": ["python3", "pip3"] },
  },
}
---

## 功能概览
- 本技能用于**根据用户自然语言描述**，引导 OpenClaw **生成**可执行的 pyAgxArm 控制代码（Python 脚本），而不是仅调用现成 CLI。
- 参考 SDK：pyAgxArm（[GitHub](https://github.com/agilexrobotics/pyAgxArm)）；参考示例：`pyAgxArm/demos/nero/test1.py`。

## 何时使用本技能
- 用户说「写一段代码控制机械臂」「根据我的描述生成控制脚本」「让机械臂按顺序做多个动作」等。
- 用户明确要求「生成 Python 代码」或「给我可运行的脚本」来控制 Nero/Piper 等 AgileX 机械臂。

## 使用本技能生成代码
 - 根据用户提示词，结合本技能的 `references/pyagxarm-api.md` 中的 API 与模板，生成一段完整、可运行的 Python 脚本。
 - 生成后说明：脚本需在已安装 pyAgxArm 和 python-can 的环境中运行，且需 CAN 已激活、机械臂上电；提醒用户注意安全（工作区域无人、可先小幅度测试）。

## 生成代码时的规则
1. **连接与配置**
   - 使用 `create_agx_arm_config(robot="nero", comm="can", channel="can0", interface="socketcan")` 创建配置（Nero 示例；Piper 可用 `robot="piper"`）。
   - 使用 `AgxArmFactory.create_arm(robot_cfg)` 创建机械臂实例，再 `robot.connect()` 建立连接。
2. **使能与运动前**
   - CRITICAL: The robot MUST BE ENABLED before switching modes. If the robot is in a disabled state, you cannot switch modes.
   - 运动前需切换为普通模式，然后使能：`robot.set_normal_mode()`，然后轮询 `robot.enable()` 直到成功；可设 `robot.set_speed_percent(100)`。
   - 运动模式：每当需要使用move_*时或需要切换为*模式时候，需要显式的设置`robot.set_motion_mode(robot.MOTION_MODE.J)`（关节）、`P`（点到点）、`L`（直线）、`C`（圆弧）、`JS`（关节快速响应，慎用）。
3. **运动接口与单位**
   - 关节运动：`robot.move_j([j1, j2, ..., j7])`，单位为**弧度**，Nero 为 7 关节。
   - 笛卡尔：`robot.move_p(pose)` / `robot.move_l(pose)`，pose 为 `[x, y, z, roll, pitch, yaw]`，位置单位**米**，姿态**弧度**。
   - 圆弧：`robot.move_c(start_pose, mid_pose, end_pose)`，每个 pose 为 6 个浮点数。
   - CRITICAL: All movement commands (move_j, move_js, move_mit, move_c, move_l, move_p) must be used in normal mode
   - 运动完成后应轮询 `robot.get_arm_status().msg.motion_status == 0` 或封装 `wait_motion_done(robot, timeout=...)` 再执行下一步。
4. **模式切换**
   - Switching modes (master, slave, normal) requires 1s delay before and after the mode switch
   - Use `robot.set_normal_mode()` to set normal mode
   - Use `robot.set_master_mode()` to set master mode
   - Use `robot.set_slave_mode()` to set slave mode
   - CRITICAL: Enable the robot FIRST with `robot.enable()` BEFORE switching modes
5. **安全与结尾**
   - 在生成脚本中可注明：执行前确认工作区域安全；首次建议小幅度移动；紧急时使用物理急停或 `robot.electronic_emergency_stop()` / `robot.disable()`。
   - 若用户要求「完成后失能」，在脚本末尾调用 `robot.disable()`。
6. **实现细节**
   - When waiting for motion to complete, use shorter timeout (2-3 seconds)
   - After each mechanical arm operation, add a small sleep (0.01 seconds)
   - Motion completion detection: `robot.get_arm_status().msg.motion_status == 0` (not == 1)

## 参考文件
- **API 与最小可运行模板**：`references/pyagxarm-api.md`
生成代码时请结合该文件中的接口说明与代码片段，保证与 pyAgxArm 及 test1.py 用法一致。

## 安全注意事项
- 生成的代码会驱动真实机械臂，必须提醒用户：执行前确认工作区域内无人员和障碍物；建议先小幅度、低速度测试。
- 高风险模式（如 `move_js`、`move_mit`）应在代码注释或对用户说明中标注风险，并建议仅在了解后果后使用。
- 本技能只负责「引导生成代码」，不直接执行运动；实际运行环境、CAN 激活、pyAgxArm 安装由用户自行准备（可参考 agx-arm 技能中的环境准备）。

pyagxarm-api.md

# pyAgxArm API 速查与最小可运行模板
供 OpenClaw 根据用户自然语言生成机械臂控制代码时参考。SDK 来源：pyAgxArm（[GitHub](https://github.com/agilexrobotics/pyAgxArm)）；示例参考：`pyAgxArm/demos/nero/test1.py`。

1. 连接与配置

from pyAgxArm import create_agx_arm_config, AgxArmFactory
# 配置：robot 可选 nero / piper / piper_h / piper_l / piper_x；channel 如 can0
robot_cfg = create_agx_arm_config(
    robot="nero",
    comm="can",
    channel="can0",
    interface="socketcan",
)
robot = AgxArmFactory.create_arm(robot_cfg)
robot.connect()

• create_agx_arm_config(robot, comm="can", channel="can0", interface="socketcan", **kwargs)：创建配置字典；CAN 相关参数通过 kwargs 传入（如 channel、interface）。
• AgxArmFactory.create_arm(config)：返回机械臂驱动实例。
• robot.connect()：建立 CAN 连接并启动读取线程。

2. 使能与模式

robot.set_normal_mode()  # 普通模式（单臂控制）
# 使能：轮询直到成功
while not robot.enable():
    time.sleep(0.01)
robot.set_speed_percent(100)  # 运动速度百分比 0–100
# 失能
while not robot.disable():
    time.sleep(0.01)

• 主从模式（Nero/Piper 等）：robot.set_master_mode()（零力拖拽）、robot.set_slave_mode()（跟随主臂）。

3. 运动模式与运动接口

• 单位：关节角为弧度；笛卡尔位姿为米（x,y,z）和弧度（roll, pitch, yaw）。
• Nero 为 7 关节；Piper 为 6 关节，move_j/move_js 参数数量需与机型一致。

示例（关节运动 + 等待完成）：

import time

def wait_motion_done(robot, timeout: float = 3.0, poll_interval: float = 0.1) -> bool:
    # Shorter timeout (2-3s)
    time.sleep(0.5)
    start_t = time.monotonic()
    while True:
        status = robot.get_arm_status()
        if status is not None and getattr(status.msg, "motion_status", None) == 0:
            return True
        if time.monotonic() - start_t > timeout:
            return False
        time.sleep(poll_interval)

robot.set_motion_mode(robot.MOTION_MODE.J)
robot.move_j([0.01, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0])
wait_motion_done(robot, timeout=3.0)  # Shorter timeout

4. 读取状态

• robot.get_joint_angles()：当前关节角（返回值带 .msg 属性时为数组）。
• robot.get_flange_pose()：当前法兰位姿 [x, y, z, roll, pitch, yaw]。
• robot.get_arm_status()：运动状态等；status.msg.motion_status == 0 表示运动完成。
• 注意：运动完成后检测 robot.get_arm_status().msg.motion_status == 0（不是 == 1）

5. 其他

• 回零：robot.move_j([0] * 7)（Nero 为 7 关节）。
• 急停：robot.electronic_emergency_stop()；恢复需 robot.reset()。
• MIT 阻抗/力矩控制（高级）：robot.set_motion_mode(robot.MOTION_MODE.MIT)，robot.move_mit(joint_index, p_des, v_des, kp, kd, t_ff)，参数范围见 SDK，慎用。

6. 最小可运行模板（生成代码时可基于此扩展）

#!/usr/bin/env python3
import time
from pyAgxArm import create_agx_arm_config, AgxArmFactory

def wait_motion_done(robot, timeout: float = 3.0, poll_interval: float = 0.1) -> bool:
    # Shorter timeout (2-3s)
    time.sleep(0.5)
    start_t = time.monotonic()
    while True:
        status = robot.get_arm_status()
        if status is not None and getattr(status.msg, "motion_status", None) == 0:
            return True
        if time.monotonic() - start_t > timeout:
            return False
        time.sleep(poll_interval)

def main():
    robot_cfg = create_agx_arm_config(
        robot="nero",
        comm="can",
        channel="can0",
        interface="socketcan",
    )
    robot = AgxArmFactory.create_arm(robot_cfg)
    robot.connect()

    # Mode switching requires 1s delay before and after
    time.sleep(1)  # 1s delay before mode switch
    robot.set_normal_mode()
    time.sleep(1)  # 1s delay after mode switch

    # CRITICAL: The robot MUST BE ENABLED before switching modes
    while not robot.enable():
        time.sleep(0.01)
    robot.set_speed_percent(80)

    # After each mechanical arm operation, add a small sleep (0.01 seconds)
    # CRITICAL: All movement commands must be used in normal mode
    robot.set_motion_mode(robot.MOTION_MODE.J)
    robot.move_j([0.05, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0])
    time.sleep(0.01)  # Small delay after move command
    wait_motion_done(robot, timeout=3.0)  # Shorter timeout

    # 可选：退出前失能
    # while not robot.disable():
    #     time.sleep(0.01)

if __name__ == "__main__":
    main()

生成代码时请根据用户描述替换或增加运动步骤（move_j / move_p / move_l / move_c 等），并保持连接、使能、wait_motion_done 和单位（弧度/米）一致。

接下来，将这两个文件放入 OpenClaw 的 skill 目录，让 OpenClaw 学习并应用这个技能。完成机械臂的 CAN 通信配置和 Python 环境搭建后，你就可以通过自然语言描述指令，让 OpenClaw 自动调用 SDK 生成控制代码，直接驱动机械臂运动了。

看到这里，核心流程已经梳理清楚。OpenClaw 之所以能够走红，原因很明显——它把 AI 从一个“只会提建议的云端顾问”变成了一个“能够直接动手的本地执行者”。机械臂作为 AI 连接物理世界的重要桥梁，两者的深度融合必将解锁更多创新应用场景。希望这篇实战指南能帮助你顺利迈过入门门槛，无论是日常调试、项目开发还是技能扩展，都能拥有一个扎实的起点。

在实际操作过程中如果遇到任何问题，欢迎在评论区留言交流。后续我们会持续更新 OpenClaw 的更多玩法，一起充分挖掘这支“开源龙虾”的潜力。