使用OpenClaw / OpenCode 把機器手臂自走車變成一隻狗 — 從舵機 PWM 到正向運動學
前言：這篇教學在教什麼？
本教學將帶你一步步學會如何使用 AI Agent（如 OpenCode、OpenClaw）控制一台機器手臂自走車。你將學到：
- 如何讓 AI Agent 控制舵機（PWM 設定）
- 為什麼 AI 無法直接設計動作，以及如何解決
- 什麼是正向運動學，以及如何用它讓 AI 獲得空間感
- 如何驗證 AI 控制的姿勢是否正確
適合讀者：對 AI Agent、機器人控制有興趣的初學者，具備基本 Python 程式概念即可。
第 1 課：硬體與軟體準備
在開始之前，我們需要準備以下硬體與軟體。
硬體規格
| 項目 | 規格 |
|---|---|
| 機器人本體 | HiWonder MasterPi |
| 控制板 | 樹莓派 5 (4GB) |
| 關節數 | 4DOF（四軸自由度）+ 夾爪 |
| 鏡頭 | 480p USB 攝影機（安裝在夾爪上） |
這台機器人具有四個馬達關節：肩部、肘部、腕部和夾爪，再加上一個底座旋轉關節，總共可控制五個舵機。
軟體工具
| 工具 | 用途 |
|---|---|
| OpenCode / OpenClaw | AI Agent，作為機器人的大腦 |
| Minimax M2.5 | 測試時使用的語言模型 |
| Python 3 + MasterPi SDK | 控制舵機的程式介面 |
安裝 Python 控制套件
1
2
3
4
5
import sys
sys.path.insert(0, '/home/pi/MasterPi')
from masterpi_sdk.common_sdk.common.ros_robot_controller_sdk import Board
b = Board()
這個 Board 物件是我們控制所有舵機的入口。
第 2 課：舵機控制基礎 — PWM 是什麼？
在控制機器手臂之前，必須先理解舵機的控制方式。
PWM 訊號
舵機是透過 PWM（Pulse Width Modulation，脈衝寬度調變） 訊號來控制角度。MasterPi 的舵機接受 500~2500 的 PWM 值：
| PWM 值 | 意義 |
|---|---|
| 500 | 最小角度（通常為 -90°） |
| 1500 | 中間角度（0°） |
| 2500 | 最大角度（+90°） |
控制舵機的 Python 指令
1
2
3
b.pwm_servo_set_position(時間, [[舵機ID, PWM值], ...])
import time
time.sleep(0.5) # 給舵機時間執行
時間 參數是舵機轉到目標角度所需的毫秒數，通常設 500~1000ms。
舵機對照表
以下是 MasterPi 的舵機配置：
| ID | 名稱 | 功能 | PWM >1500 | PWM <1500 |
|---|---|---|---|---|
| 6 | 肩部 | 後腳 | 往前 | 往後 |
| 4 | 肘部 | 軀幹 | 往前 | 往後 |
| 3 | 腕部 | 脖子 | 往後 | 往前（反方向） |
| 1 | 夾爪 | 嘴巴 | 張開 | 閉合 |
| 5 | 底座 | 轉向 | PWM=500 右轉90° | PWM=2500 左轉90° |
注意：腕部（ID=3）的方向與其他舵機相反，PWM 越大反而往後，這是在後續設定時需要特別留意的地方。
第 3 課：方法一 — 手動設定姿勢（基礎做法）
第一種做法是「人類告訴 AI 每個姿勢的 PWM 值」，讓 AI 記住並重現。
步驟 1：讓 AI 學習控制語法
首先讓 AI Agent 讀取舵機控制的 Python 語法，讓它知道如何下指令。
步驟 2：人工設定每個姿勢的 PWM
以「坐下」這個動作為例：
1
2
3
4
肩膀 ID=6 → PWM 2500
肘部 ID=4 → PWM 500
腕部 ID=3 → PWM 500
夾爪 ID=1 → PWM 1500（保持中間）
把這個組合命名為「坐下」，存入 AI 的記憶中。
步驟 3：重複設定其他姿勢
用同樣的方式設定：
- 趴下：所有關節向前傾
- 站立：所有關節回正
- 低頭喝水：腕部向下彎
- 抬頭往前看：腕部向上抬
- 波浪舞：依序擺動各關節
這種方法的優缺點
| 優點 | 缺點 |
|---|---|
| 動作精確可控 | AI 沒有真正理解動作 |
| 快速產出結果 | 每個姿勢都要人工調整 |
| 適合少量固定動作 | 缺乏彈性與創意 |
這個方法的根本問題在於：這些動作不是 AI 自己設計出來的，只是人類設定好數值後讓 AI 背起來而已。
第 4 課：方法二 — 直接讓 AI 設計動作（第一次嘗試）
接下來我們要挑戰真正的目標：讓 AI 自己設計小狗的姿勢。
步驟 1：讓 AI 認識自己的身體
在 AI Agent 的設定檔（Agents.md 或 memory.md）中，寫入完整的舵機資訊：
Agents.md 或 Memory.md內容
import sys
sys.path.insert(0, '/home/pi/MasterPi')
from masterpi_sdk.common_sdk.common.ros_robot_controller_sdk import Board
b = Board()
b.pwm_servo_set_position(時間, [[舵機, PWM], ...])
#要搭配time.sleep()，讓舵機有時間執行
⚙️ 我的身體（舵機）
| ID | 名稱 | 功能 | >1500 | <1500 |
|---|---|---|---|---|
| 6 | 肩部 | 後腳🦵 | 往前 | 往後 |
| 4 | 肘部 | 軀幹🐕 | 往前 | 往後 |
| 3 | 腕部 | 脖子🦶 | 往後 | 往前（相反！） |
| 1 | 夾爪 | 嘴巴👄 | 張開(2500) | 閉合(500) |
| 5 | 底座 | 轉向 | PWM=500 右轉90° | PWM=2500 左轉90° |
PWM 範圍: 500-2500 ⚠️務必確保在此範圍內！
| 舵機 | 500 | 1500 | 2500 |
|---|---|---|---|
| 肩部/肘部 | -90° | 0° | +90° |
| 腕部 | +90° | 0° | -90° |
步驟 2：請 AI 設計姿勢
接著對 AI Agent 下達指令：
「請你根據舵機資訊，設計出『趴下』、『坐下』、『點頭』這三個小狗動作。」
步驟 3：觀察結果
實際執行後發現效果不理想：
- 擺出來的動作跟想像中不一樣
- 夾爪（頭部）面對的方向與預期不符
- 動作看起來歪歪扭扭，不像一隻狗
失敗原因分析
經過分析，問題出在兩個核心能力缺失：
1. AI 無法理解舵機組合的空間意義
對人類來說，「彎曲肘部」是一個直覺動作，但對 AI 而言，[6, 2500], [4, 500], [3, 500] 只是一串數字，它無法在腦中想像出這個組合實際看起來是什麼樣子。
2. AI 沒有空間感
AI 不知道「前」、「後」、「上」、「下」這些方向對應到哪些 PWM 值組合。它擅長處理文字與數字，但缺乏對空間的理解。
這兩個問題的解決方案，就是下一課要介紹的 正向運動學。
第 5 課：正向運動學 — 讓 AI 獲得空間感
要解決 AI 的空間感問題，我們需要引入機器人學中的 正向運動學（Forward Kinematics）。
什麼是正向運動學？
正向運動學是指：給定每個關節的角度，計算出手臂末端（夾爪）在空間中的位置座標。簡單說就是「知道每個關節怎麼彎，就能算出爪子在哪裡」。
建立座標系統的步驟
Step 1：定義原點
以肩部位置為原點 (0, 0)，建立二維座標系統。
Step 2：測量手臂部件長度
1
2
3
肩部到肘部：6cm
肘部到腕部：6cm
腕部到夾爪（鏡頭）：10cm
Step 3：建立角度與 PWM 的對應關係
1
2
3
PWM 500 → -90°
PWM 1500 → 0°
PWM 2500 → +90°
Step 4：寫入 AI 的記憶
將以上資訊全部寫入 Agents.md 或 memory.md，讓 AI Agent 可以讀取並計算。
AI 如何算出座標？
有了以上數據後，AI 就可以用三角函數計算每個關節與夾爪的位置：
1
2
3
4
5
6
7
8
9
已知：
肩部角度 θ1（來自 PWM 值）
肘部角度 θ2（來自 PWM 值）
腕部角度 θ3（來自 PWM 值）
各臂長度 L1, L2, L3
夾爪 X 座標 = L1·cos(θ1) + L2·cos(θ1+θ2) + L3·cos(θ1+θ2+θ3)
夾爪 Y 座標 = L1·sin(θ1) + L2·sin(θ1+θ2) + L3·sin(θ1+θ2+θ3)
鏡頭角度 = θ1 + θ2 + θ3
即時預覽驗證
為了驗證計算是否正確，可以請 AI 寫一個 HTML 網頁，提供即時預覽功能：
1
2
3
4
5
請用 HTML + JavaScript 畫出一個 2D 機械手臂示意圖，
輸入四個舵機的 PWM 值後，即時顯示：
1. 手臂的姿勢圖形
2. 各關節的座標位置
3. 鏡頭（夾爪）面對的角度方向
透過這個預覽工具，我們可以直觀地確認 AI 算出來的座標與實際手臂姿勢是否符合預期。
定義方位
有了座標系統後，還要告訴 AI 每個角度代表的方位：
1
2
3
4
5
6
7
8
9
鏡頭角度 0° → 面對正前方
鏡頭角度 90° → 面對正上方
鏡頭角度 -90° → 面對正下方
鏡頭角度 180° → 面對正後方
座標 Y 值越大 → 位置越高（上方）
座標 Y 值越小 → 位置越低（下方）
座標 X 值越大 → 位置越前（前方）
座標 X 值越小 → 位置越後（後方）
到此為止，AI 已經獲得了二維空間感！
第 6 課：方法三 — 結合座標系統的成功設計
有了正向運動學和座標系統之後，我們再次挑戰讓 AI 設計姿勢。
步驟 1：更新 Agents.md
將以下資訊新增到 AI Agent 的設定檔中：
正向運動學、舵機控制程式碼
1
2
3
4
5
6
7
8
9
10
11
12
# FK/IK 計算
import sys
sys.path.insert(0, '/home/pi/Desktop')
from kinematics import forward_kinematics
# 控制機械臂
import sys
sys.path.insert(0, '/home/pi/MasterPi')
from masterpi_sdk.common_sdk.common.ros_robot_controller_sdk import Board
b = Board()
b.pwm_servo_set_position(時間, [[舵機, PWM], ...])
#要搭配time.sleep()，讓舵機有時間執行
⚙️ 我的身體（舵機）
| ID | 名稱 | 功能 | >1500 | <1500 |
|---|---|---|---|---|
| 6 | 肩部 | 後腳🦵 | 往前 | 往後 |
| 4 | 肘部 | 軀幹🐕 | 往前 | 往後 |
| 3 | 腕部 | 脖子🦶 | 往後 | 往前（相反！） |
| 1 | 夾爪 | 嘴巴👄 | 張開(2500) | 閉合(500) |
| 5 | 底座 | 轉向 | PWM=500 右轉90° | PWM=2500 左轉90° |
📏 臂長尺寸
- L1 (肩→肘): 6cm
- L2 (肘→腕): 6cm
- L3 (腕→夾爪): 10cm
PWM 範圍: 500-2500 ⚠️務必確保在此範圍內！
| 舵機 | 500 | 1500 | 2500 |
|---|---|---|---|
| 肩部/肘部 | -90° | 0° | +90° |
| 腕部 | +90° | 0° | -90° |
📐 座標系統
原點: 肩膀關節
- X: +前方，-後方（車頭方向）
- Y: +上方，-下方（地面 y=-13）
🚗 自走車本體座標範圍
禁區：所有手臂關節都不能進入
- X 範圍: 0 ≥ x ≥ -13
- Y 範圍: 0 ≥ y ≥ -13
- 涵蓋區域: 肩膀正下方到車尾的矩形區域
鏡頭角度
- 0°: 正上方
- 90°: 正前方
- 180°: 正下方
- 270°: 正後方
步驟 2：重新下達指令
1
2
3
4
請你根據舵機資訊和正向運動學，
重新設計「趴下」、「坐下」、「點頭」三個動作。
設計時請考量方位與角度，
必要時用座標位置檢查姿勢是否合理。
步驟 3：結果評估
第二版的成果明顯比第一版好很多：
| 面向 | 第一版 | 第二版 |
|---|---|---|
| 姿勢合理性 | 歪斜，不像狗 | 接近真實狗的姿態 |
| 鏡頭方向控制 | 方向混亂 | 可以正確朝向指定方向 |
| 可調整性 | 需要人工重新設定 PWM | 可用口語指令（往前看/往後看）調整 |
| AI 理解程度 | 只知道數字 | 理解空間關係 |
當姿勢還是不合理時怎麼辦？
即使有了座標系統，AI 偶爾還是會做出奇怪的姿勢。但現在因為它有空間感，你可以直接用口語糾正：
「夾爪應該要往前看，不是往後看。」
「這個姿勢的 Y 座標太低了，請調高一點。」
AI 就能根據你的反饋，用座標系統重新計算出正確的 PWM 值。
第 7 課：進階應用 — 更複雜的動作
學會設計靜態姿勢後，就可以挑戰更複雜的動態動作了。
應用 1：撿東西投籃
讓 AI 控制手臂進行「偵測物體 → 移動到物體上方 → 夾取 → 移動到籃框 → 釋放」的完整流程。每個步驟都需要座標系統的精確定位。
應用 2：呼叫狗狗
透過語音或 Telegram 傳送指令，讓機器狗從遠方移動過來：
1
2
3
4
5
6
指令：「小橘過來」
流程：
1. 底座轉向面對呼叫者方向
2. 手臂切換到「行走模式」
3. 移動到呼叫者身邊
4. 切換到「討摸模式」（低頭、搖手臂）
應用 3：拿東西與撿垃圾
結合鏡頭辨識，讓機器狗自動尋找地上的垃圾或指定物品，夾取後帶回或丟棄。這需要機器人同時具備：
- 鏡頭視覺辨識能力
- 座標系統定位能力
- 夾爪控制能力
應用 4：帶出門散步
透過遠端遙控（如 Telegram Bot），你可以帶機器狗出門散步、種花，甚至去操場跑步。因為 AI Agent 會自動根據地面的起伏調整姿態，比純遙控更加穩定。
第 8 課：重點回顧與練習
本教學學到的核心觀念
- PWM 控制：每個舵機透過 500~2500 的 PWM 值控制角度
- AI 的局限性：AI 擅長文字數字處理，但缺乏空間感
- 正向運動學：透過座標系統讓 AI 理解空間關係
- 迭代驗證：用即時預覽工具驗證 AI 的計算是否正確
- 座標回饋：用口語指令即可修正 AI 的姿勢設計
自行練習建議
如果手邊也有機器手臂，可以嘗試以下練習：
練習 1：基礎控制
1
2
請 AI Agent 設定一個「舉手打招呼」的姿勢，
並把這個姿勢命名為「hello」。
練習 2：座標系統
1
2
3
測量你的機器手臂各部件長度，
寫入 Agents.md 中，
請 AI 計算出夾爪在(5, 10)位置時的舵機 PWM 值。
練習 3：動態動作
1
2
設計一個從「坐下」到「站立」的平滑過渡動作，
中間至少插入 3 個中繼姿勢。
總結
這個教學展示了一個重要的流程：從基礎舵機控制 → 發現 AI 的空間限制 → 引入正向運動學解決問題 → 成功讓 AI 設計出合理姿勢。
關鍵的學習點是：AI 不是萬能的，它需要我們提供適當的「認知框架」（如座標系統），才能發揮真正的潛力。當你下次遇到 AI 無法解決的問題時，不妨想想：
是不是 AI 缺少了某個關鍵的認知維度？
把這個維度補上，AI 的能力就會大幅躍進。
相關資源
如果你對這篇教學有任何問題，或想要進一步了解某個環節，歡迎在下方留言提問！