【小白】从零开始让AI接管你的机械臂（so-100＋skills+openclaw/claude code）

用 AI Agent 控制机械臂Skill 驱动的智能机器人开发教程想象一下这样的场景你抓起桌上那个绿色的瓶盖 它打开摄像头 - 识别瓶盖 - 计算位置 - 精准抓取 - 完成 你把它放到左边 它提起物体 - 平滑移动 - 放下 - 归位 你跳个舞 它......它真的跳了抓取这不是科幻。这是一份SKILL.md文件 Claude Code做到的事。本文将教你如何用 Skill 系统让 AI Agent 直接控制物理世界的机械臂。不写控制代码用自然语言指挥机器人。项目开源地址github.com/Linmoqian/claw_armdocs目录下提供了更详细的教程核心思想Skill 是 AI 控制物理世界的桥梁传统机器人开发的流程是人写控制代码 - 机器人执行。这个项目做了一件不一样的事让 AI 读一份 Skill 文档自主决策如何控制机械臂。传统方式人 --写代码-- 机器人 本项目 人 --写Skill-- AI Agent --自主决策-- 机器人Skill 是一份 Markdown 文件描述了AI 应该遵守什么规则安全第一机械臂有哪些关节、怎么控制视觉系统怎么用、坐标系怎么转换遇到异常怎么处理AI 读完 Skill 后就能理解物理世界的约束安全、准确地控制机械臂。你将构建的系统最终效果在终端中输入自然语言机械臂立即执行cdclaw_arm claude帮我控制机械臂抓起那个绿色物体[AI 读取 Skill]→[打开摄像头检测]→[计算位姿]→[控制关节移动]→[闭合夹爪]把它放到左边[AI 规划路径]→[平滑移动]→[释放]→[归位]系统架构整个系统以 Skill 为中心连接 AI 和物理世界------------------ | SKILL.md | | (控制规则文档) | ----------------- | ---------------------------- | | --------v-------- ---------v--------- | AI Agent | | 物理世界 | | (Claude Code) | | | | 理解意图 | | SO-100 机械臂 | | 规划动作 | | USB 摄像头 | | 生成指令 | | STS3215 舵机 | ---------------- ------------------ | ^ | 串口指令 / Python 脚本 | -----------------------------Skill 的引用文件构成 AI 对物理世界的认知skills/nature_arm/ ├── SKILL.md # 核心规则文档为了这叠醋包的饺子 [video(video-cUQoJAYk-1775476418167)(type-csdn)(url-https://live.csdn.net/v/embed/520489)(image-https://i-blog.csdnimg.cn/img_convert/a97cf7ecca8fc2b697b2dec8b7bf8f5f.jpeg)(title-抓取)] [video(video-iNbE4ENi-1775476425262)(type-csdn)(url-https://live.csdn.net/v/embed/520489)(image-https://i-blog.csdnimg.cn/img_convert/a97cf7ecca8fc2b697b2dec8b7bf8f5f.jpeg)(title-抓取)] ├── references/ │ └── so100_calibration.md # 关节校准数据AI 需要的参数 └── scripts/ ├── SDK/ # 串口通信协议AI 调用的底层 ├── simple_joint.py # 关节控制AI 的执行手段 └── simple_pnp.py # 视觉定位AI 的感知手段第一步环境搭建这个项目需要两套运行时Python控制硬件和 Node.js运行 Claude Code。1.1 安装 Node.jsWindows从 Node.js 官网 下载 LTS 版本双击安装。macOS / Linuxcurl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh|bashnvminstall--lts验证node--version# v20.xnpm--version# 10.x1.2 安装 Claude CodeClaude Code 是 Anthropic 官方的 AI 编程助手也是运行 Skill 的平台。# Windows PowerShellirm https://claude.ai/install.ps1|iex# macOS / Linuxcurl-fsSLhttps://claude.ai/install.sh|bash备选方式方式命令npmnpm install -g anthropic-ai/claude-codemacOS Homebrewbrew install --cask claude-codeWindows WinGetwinget install Anthropic.ClaudeCodeOpenClaw 也可以作为替代方案npm install -g openclaw。它支持多种 AI 模型但注意 2026 年 4 月起通过 OpenClaw 使用 Claude 需要 API Key 计费。1.3 安装 Python 环境gitclone https://github.com/Linmoqian/claw_arm.gitcdclaw_arm condaenvcreate-fenvironment.yml conda activate claw_arm依赖只有三个opencv-python、numpy、pyserial。1.4 验证全部就绪python-cimport cv2, numpy, serial; print(Python OK)claude--version第二步硬件准备物料清单组件推荐型号参考价格机械臂SO-100 (6自由度)1500-2000 元摄像头USB 1080p100-200 元电源12V 5A30 元标定板棋盘格 9x620 元可选总预算约 1700 元起。SO-100 机械臂关节布局ID关节作用1底座旋转 (base)左右旋转2肩关节 (shoulder)前后俯仰3肘关节 (elbow)小臂弯曲4腕俯仰 (wrist_pitch)手腕上下5腕旋转 (wrist_roll)手腕旋转6夹爪 (gripper)抓取/释放连接与测试# 确认串口号Windows 设备管理器 / Linux: ls /dev/ttyUSB*# 修改脚本中的串口号后测试python script/1.3test_motors.py# 电机逐个转动python CV/1_camera_test.py# 摄像头画面弹出两个都通过硬件就准备好了。第三步理解 Skill——AI 控制机械臂的核心这是本文最重要的部分。Skill 是一份 Markdown 文件它是 AI Agent 和物理世界之间的说明书。3.1 完整的 SKILL.md项目中的skills/nature_arm/SKILL.md--- name: nature_arm description: 自然的机械臂。 metadata: {env: python, mode: control} --- # 规则 - 第一守则绝对确保用户安全 - 第二守则绝对保障自身安全 - 第三守则最快反馈现实实体 - 运动要求低速平滑消除抖动 - 代码生成非必要不新写代码 - 代码改动代码最小化的更改 - 服务保证环境完备端口正确 - 思考要求尽快进行安全响应 - 专注领域专注于机械臂任务 # 触发条件 任何涉及机械臂的相关词。 # 关节描述 ID:1~6的描述参考 \references\so100_calibration.md 关节 1-5 为运动轴通道 6 控制末端夹爪开合 # 关节控制 基于描述参考 \scripts\simple_joint.py 进行控制 # 空间理解 基于pnp进行位姿理解参考 \scripts\simple_pnp.py 进行理解 输出的位姿是相机坐标系输出单位毫米 # SDK接入 SDK的位置位于 \scripts\SDK 若出现错误必须先检索 SDK 文档确认参数定义 # 异常处理 - 通信丢失立即停止发送指令保持当前力矩。 - 用户急停收到停止、急停指令跳过所有逻辑直接发送 Stop 信号。 - 报错处理捕获异常日志分析原因后建议用户重试或回退不盲目重试。 # 交互风格 - 响应简洁直接反馈执行状态成功/失败/原因。 # 格外建议 - 在抓取任务时抵达目标位置后应该先停顿1s再进行夹爪抓取3.2 逐块解析Frontmatter——告诉 AI 这是什么技能name:nature_arm# 技能名也是斜杠命令名description:自然的机械臂。# AI 根据这个判断何时激活当用户说帮我控制机械臂或输入/nature_armAI 就会加载这个 Skill。规则——AI 的行为约束这不是普通代码规则而是给 AI 的安全锁。机器人三原则的变体用户安全 自身安全 执行效率低速平滑禁止猛烈动作代码最小改动不瞎写新代码触发条件——什么时候激活任何涉及机械臂的相关词。AI 会根据对话内容自动判断是否需要激活这个 Skill。引用——AI 的知识来源\references\so100_calibration.md # 机械臂的关节参数 \scripts\simple_joint.py # 怎么控制关节 \scripts\simple_pnp.py # 怎么通过视觉定位 \scripts\SDK # 底层通信协议\path语法让 AI 在执行时读取这些文件获得精确的参数和接口定义。不需要把所有代码塞进 SKILL.md引用外部文件即可。异常处理——紧急情况的行为AI 遇到问题时不盲目重试而是停下来分析。收到急停指令时跳过所有逻辑直接停止。3.3 Skill 引用的知识文件AI 通过引用文件获得对物理世界的理解关节参数(references/so100_calibration.md)# 零点位置按顺序1-6 zero_shoulder_pan 2078 zero_shoulder_lift 930 zero_elbow_flex 3008 ... # 运动范围 range_shoulder_pan 721, 3489 range_shoulder_lift 919, 3301 ...AI 读到这些数据后就知道每个关节的安全范围不会发出超出极限的指令。关节控制接口(scripts/simple_joint.py)classJoint:defenable(self):...# 启用扭矩defdisable(self):...# 释放扭矩defmove(self,position):# 移动到目标位置 (0-4095)defposition(self)-int:# 读取当前位置AI 读取接口定义后就知道该调用哪些方法来控制关节。视觉定位(scripts/simple_pnp.py)AI 读取后理解整个感知-决策-执行链GreenDetector检测目标物体PoseEstimator通过 PnP 算法计算 3D 位姿ArmKinematics做逆运动学求解Arm.camera_to_base()将相机坐标转到基座坐标MotorController发送最终的关节指令3.4 SKILL.md 字段参考字段说明name技能名称决定斜杠命令/namedescription用途描述AI 据此自动匹配触发时机disable-model-invocation设为true禁止自动触发仅手动allowed-tools免确认使用的工具列表context设为fork在隔离子代理中运行第四步Skill 背后——硬件控制层Skill 告诉 AI “做什么”底层模块告诉机械臂 “怎么做”。了解这些有助于你编写更好的 Skill。4.1 舵机通信协议机械臂通过串口通信波特率 1000000。SDK 封装了三个核心寄存器操作寄存器地址功能用法TORQUE_ENABLE40扭矩开关写 1 启用写 0 释放GOAL_POSITION42目标位置写入 0-4095 的目标角度PRESENT_POSITION56当前位置读取当前角度只读fromSDKimportPortHandler,PacketHandler portPortHandler(COM7)port.setBaudRate(1000000)port.openPort()pktPacketHandler(0.0)pkt.write1ByteTxRx(port,motor_id,40,1)# 启用扭矩pkt.write2ByteTxRx(port,motor_id,42,2048)# 移动到中间位置pos,_,_pkt.read2ByteTxRx(port,motor_id,56)# 读取位置位置范围 0-4095对应舵机旋转 0-360 度。4.2 关节控制封装Joint类提供更安全的接口fromJoints.simple_jointimportJoint jointJoint(port,pkt,joint_id2)# 肩关节joint.enable()joint.move(2047)# 移动到中间位置print(joint.position())# 读取当前角度joint.disable()# 安全释放move()内置了范围限制max(0, min(4095, position))防止超出机械极限。4.3 视觉感知层Skill 引用的simple_pnp.py实现了完整的感知-定位链classGreenDetector:HSV 颜色检测找到绿色物体defdetect(self,frame):...classPoseEstimator:PnP 位姿估计从像素坐标算出 3D 位置defestimate(self,center):...classArmKinematics:SO100 运动学逆运动学求解关节角度definverse_simple(self,target_position):...classArm:串联一切视觉 - 坐标转换 - 运动defmove_to(self,t_cam):...# 相机坐标 - 基座坐标 - 关节角度defgrasp(self,closeTrue):...# 抓取/释放数据流摄像头帧 → HSV 颜色过滤 → 轮廓提取 → 中心点坐标 → PnP 位姿估计 → 相机坐标 (mm) → 手眼标定转换 → 基座坐标 (mm) → 逆运动学 → 6个关节角度 → 串口发送 → 机械臂执行4.4 坐标转换AI 需要理解的核心概念——坐标系统坐标系参考物示例像素坐标图像平面(320, 240) 像素相机坐标摄像头(15, -20, 300) mm基座坐标机械臂底座(43, -59, 342) mm手眼标定矩阵simple_pnp.py中已包含R_cam2basenp.array([[0.994,-0.069,-0.084],[0.107,0.502,0.858],[-0.017,-0.862,0.506]])t_cam2basenp.array([28.4,-39.2,42.1])# mm# 相机坐标 → 基座坐标t_baseR_cam2base t_camt_cam2base这个标定矩阵是你的安装位置决定的。换一个摄像头角度就需要重新标定。4.5 平滑运动预设位置 S 曲线插值保证动作平滑POSES{home:[2123,1966,2077,2082,2041,2006],right_above:[2500,1800,1200,1500,1900,2500],right_pick:[2500,1900,1000,1200,1900,2500],center:[2123,1700,1400,1600,2041,2500],left_above:[1700,1800,1200,1500,2200,2500],left_place:[1700,1900,1000,1200,2200,2500],}# S 曲线插值起止速度为零中间平滑过渡smooth_tt*t*(3-2*t)第五步安装 Skill 到 Claude CodeSkill 文件准备好了现在让 Claude Code 能找到它。5.1 放置 Skill三种方式按推荐程度排序方式一项目级推荐cdclaw_armmkdir-p.claude/skillscp-rskills/nature_arm .claude/skills/只在claw_arm项目中生效跟随项目版本控制。方式二–add-dir 加载claude --add-dir ./skills不修改项目结构灵活但需要每次手动指定。方式三个人级cp-rskills/nature_arm ~/.claude/skills/你的所有项目都能用但可能与其它项目冲突。5.2 启动并使用cdclaw_arm claude两种触发方式斜杠命令手动触发明确指定 /nature_arm 抓取桌面上的绿色物体 /nature_arm 把东西放到左边 /nature_arm 跳个舞自然语言AI 自动匹配 帮我控制机械臂抓起那个方块 让机械臂回到初始位置AI 根据description: 自然的机械臂。自动判断是否激活 Skill。5.3 AI 执行流程当你发出抓取绿色物体的指令后AI 的完整执行链1. 加载 SKILL.md读取规则和引用文件 2. 调用 simple_pnp.py 中的 GreenDetector 检测绿色物体 3. 调用 PoseEstimator 计算 3D 位姿相机坐标系 4. 调用 Arm.camera_to_base() 转换到基座坐标系 5. 调用 ArmKinematics.inverse_simple() 做逆运动学求解 6. 调用 MotorController.move_angles() 发送关节指令 7. 等待 1 秒Skill 中的格外建议 8. 调用 Arm.grasp(True) 闭合夹爪 9. 反馈执行结果AI 自主完成了从感知到执行的完整链路。你只需要一句话。第六步编写自己的 Skill理解了nature_arm后你可以编写新的 Skill 扩展机械臂的能力。6.1 创建新 Skillmkdir-pskills/pick_cup/references编写skills/pick_cup/SKILL.md--- name: pick_cup description: 专门抓取杯子并放到指定位置。识别杯子形状和位置。 --- # 规则 - 安全第一运动前检查路径上是否有障碍物 - 杯子易碎下降速度必须比平时慢 50% - 抓取前先停顿 2 秒确认位置 # 触发条件 用户要求抓取杯子、水杯、马克杯相关操作。 # 检测策略 杯口为圆形使用 Hough 圆检测而非颜色检测。 参考 OpenCV 的 HoughCircles 函数。 # 流程 1. 使用 HoughCircles 检测杯口位置 2. 移动到杯口正上方 5cm 处 3. 停顿 2 秒确认 4. 缓慢下降steps50比默认慢 5. 闭合夹爪 6. 提升到安全高度 7. 移动到用户指定的目标位置 8. 释放杯子 # 参考 关节参数\references\so100_calibration.md 关节控制\scripts\simple_joint.py6.2 编写 Skill 的要点1. 规则要具体。不要只写注意安全要写下降速度必须比平时慢 50%。AI 会严格遵守你写的规则。2. 善用引用。\path让 Skill 文件保持简洁细节放到引用文件中。AI 执行时会读取全部引用。3. 定义异常处理。告诉 AI 遇到问题时该怎么做而不是盲目重试。4. 描述触发条件。好的 description 让 AI 准确判断何时激活 Skill避免误触发。6.3 Skill 目录的完整结构一个完善的 Skill 可以这样组织skills/my_skill/ ├── SKILL.md # 核心规则文件必需 ├── references/ # 参数和数据AI 的知识库 │ ├── calibration.md # 标定数据 │ └── color_config.md # 颜色阈值 └── scripts/ # 可执行脚本AI 的工具 ├── detect.py # 检测逻辑 └── control.py # 控制逻辑第七步飞书远程控制可选配置飞书机器人后可以在飞书聊天中用自然语言控制机械臂。打开网址创建应用https://open.feishu.cn/app配置长连接接收事件7.1 导入权限配置项目根目录的feishu.json定义了飞书机器人所需的权限将其导入{scopes:{tenant:[aily:file:read,aily:file:write,aily:knowledge:read,aily:knowledge:write,aily:message:read,aily:message:write,aily:run:read,aily:run:write,aily:session:read,aily:session:write,aily:skill:read,aily:skill:write,app_engine:application.environment_variable:read,auth:user_access_token:read,cardkit:card:write,contact:contact.base:readonly,im:message,im:message.group_at_msg:readonly,im:message.p2p_msg:readonly,im:message.reactions:write_only,im:message:send_as_bot,im:message:update],user:[aily:skill:write]}}7.2 配置步骤登录飞书开放平台创建企业自建应用进入「权限管理」→「导入权限配置」→ 上传feishu.json确认权限生效后发布应用配置完成后在飞书对话中就能用自然语言控制机械臂。以下为效果图。openclaw配置1.下载飞书插件2.绑定对应密钥第八步进阶方向替换视觉模块当前使用 HSV 颜色检测只能识别预设颜色。在 Skill 中引用 YOLO 模型可以识别任意物体# 检测策略 使用 YOLOv8 进行目标检测模型路径\models\yolo_v8n.pt 支持识别瓶子、杯子、苹果、书本等 COCO 类别物体。多 Skill 协作为不同任务编写不同 Skillskills/ ├── nature_arm/ # 通用机械臂控制 ├── pick_cup/ # 杯子搬运专家 ├── sort_color/ # 颜色分拣专家 └── dance/ # 舞蹈动作库AI 会根据对话内容自动选择合适的 Skill。LeRobot 具身智能集成 HuggingFace LeRobot 框架让机械臂通过模仿学习自主完成复杂任务。Skill 可以从按规则执行进化为从示范中学习。故障排除Claude Code 找不到 Skill确认目录结构.claude/skills/nature_arm/SKILL.md或使用--add-dir。AI 控制动作不准重新标定相机python script/2.2calibration.py更新references/so100_calibration.md中的校准数据检查simple_pnp.py中的手眼标定矩阵电机连接不上检查项操作串口号确认设备管理器中的端口号驱动安装 CH340 或 CP2102波特率必须是 1000000占用关闭其它串口工具AI 触发了错误动作在 SKILL.md 的规则中添加更具体的约束。比如移动前必须先读取当前位置确认安全。技术栈总结层级技术在系统中的角色AI AgentClaude Code / OpenClaw大脑理解意图、规划动作SkillSKILL.md 引用文件规则约束 AI 行为、提供知识语言Python 3.10执行实际控制硬件视觉OpenCV PnP眼睛检测物体、计算位姿运动NumPy 逆运动学小脑关节角度求解通信pySerial SDK神经串口指令传输硬件STS3215 舵机肌肉执行物理动作远程飞书机器人延伸聊天界面控制写在最后OpenClaw 技能编写规范OpenClaw 的 Skill 遵循 AgentSkills 规范本质上是一个包含元数据和说明文件的文件夹。SKILL.md 的格式文件名skills//SKILL.md顶部 YAML frontmatter最重要的是 name / description / metadata.openclaw正文用 Markdown 写“什么时候用、怎么用、示例命令/示例 JSON、注意事项”等内容。skill 的 metadata.openclaw.requires 可以声明需要的 bins / env / config 等用户侧配置在 ~/.openclaw/openclaw.json 的 skills 下启用/禁用、注入 env、apiKey 便捷字段等这个项目的核心洞察是AI Agent 不需要写控制代码它只需要一份好的 Skill 文档。Skill 是连接 AI 世界和物理世界的桥梁。你写的不只是代码而是 AI 理解物理世界的说明书。关节参数、安全范围、控制接口、视觉定位——这些知识通过 Skill 传递给 AI让它能够安全、准确地操控机械臂。这种 Skill 驱动的模式可以扩展到更多场景3D 打印机、CNC 机床、无人机。核心思路不变——把物理世界的知识写成 Skill让 AI 自主决策执行。“最好的 AI 控制不是让 AI 写代码而是让 AI 读说明书。”“如果这个项目对你有帮助欢迎到 GitHub 给个 Star。”参考开发文档飞书API文档https://open.feishu.cn/document/home/index?langzh-CNLerobot开发文档https://hugging-face.cn/docs/lerobot/index通义千问API文档https://help.aliyun.com/zh/model-studio/qwen-api-reference/so-arm100开发文档:https://huggingface.co/docs/lerobot/so100openclaw的skills开发文档https://docs.openclaw.ai/zh-CN/tools/skillsSDK来自https://gitee.com/ftservo/FTServo_Python/tree/main/scservo_sdk硬件选型相机随便门锁都行通信方式UART串口通信电源5.5 mm×2.1 mm DC 5 V 4 A舵机选型飞特FeeTech舵机、Feetech_STS3215、ST-3215- C001 (7.4V) 1:345 齿轮比电机机械臂校准方式1使用Lerobot提供的标定工具进行机械臂校准lerobot-calibrate--robot.typeso100_follower--robot.portCOM7--robot.idmy_so100_arm程序会引导您第一步将机械臂移动到中间位置按 Enter第二步移动所有关节通过完整运动范围按 Enter完成后会生成标定文件calibration_my_so100_arm.json包含每个关节的零点位置和运动范围。方式2使用本项目提供的scrit/so100_control.py进行校准想法如果 LLM skills 具身智能