Microduck 从刷机到走起来，教你如何镜像、Wi-Fi、跑模型

装完机器鸭，卡壳的地方往往不在结构上，而在那张 SD 卡里。镜像下错了、卡刷废了、Wi-Fi 配不进、SSH 连不上、程序起来了但鸭子一动不动——这几步里任何一步断掉，前面的螺丝都白拧。这篇只讲这一段：从拿到镜像到第一次让它自己走起来，不碰采购、不碰打印、不碰舵机 ID。

下面所有步骤和命令都对着 AI-FanGe 的 Microduck-build-tutorial 核过一遍，那是 MIT 协议的装机教程，中文英文各一份，命令和默认值可以直接照抄。这位作者已经把系统、依赖、服务和行走模型一起打包成现成镜像，所以新手不用从源码编译，插卡开机就能跑。

镜像从哪拿，为什么先算一遍 sha256

镜像挂在 GitHub 的 Release 里，文件名是 microduck.img.xz，解开就是一张完整系统盘。它内置的东西值得先看清楚，因为这决定了后面每一步会看到什么：Raspberry Pi OS Lite 64 位、主机名 microduck、默认用户 user、部署目录 ~/microduck、虚拟环境 ~/microduck/.venv、行走模型 ~/microduck/src/agents/walk.onnx，还有一个叫 microduck-gamepad.service 的无头手柄服务。

下载完别急着刷卡。镜像这东西最容易出的岔子是下载中断，文件大小对得上、内容缺一段，刷进去的表现就是开机卡住或者分区坏掉，你还以为是硬件问题。作者在发布说明里给了校验值，整串是 096885dc32fb5b1db2ad69ba6bea868d8ab988f2b47c0d884eb63ba0dfdcb5c4，拿它跟你本地算出来的对一遍。

sha256sum microduck.img.xz

这条命令只是把文件的 sha256 打印出来，不改任何东西。两串字符必须一个不差；差一位就是文件坏了，重新下一次，别抱着侥幸心理往下走。

刷进 SD 卡：Pi Imager 四步，和 Windows 上另一套写法

卡建议用 16GB 以上、质量稳定的新卡。刷完之后首次启动会自动把分区扩到整张卡，所以卡大一点不会浪费。

图形化刷写推荐官方的 Raspberry Pi Imager，四个选项点下来就行。先选设备 Raspberry Pi Zero 2 W，再选系统时走 Use custom 那一项，直接指到 microduck.img.xz，然后选目标卡。最后一步有个坑：如果它弹窗问要不要应用系统自定义（OS customization），选 No。这套镜像里的主机名、默认用户和服务都是预设好的，让它按原样写进去就行。

点 Write 之后等它写完并校验完。校验这一步别跳过，它是把刚写进去的数据读回来比对，能挡住劣质卡。

Linux 下也能纯命令行刷，但设备名必须自己确认清楚，写错成电脑硬盘就是当场抹盘：

lsblk

先列块设备，从容量认出哪一块是你的 SD 卡。确认之后才动下面这条：

xzcat microduck.img.xz | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync

这条一行到底：xzcat 边解压边喂给 dd，bs=4M 表示每次写 4MB，status=progress 让你看到进度，conv=fsync 是等数据真正落到卡上再返回。少了最后这一段，进度条走完了数据可能还在内存缓存里，你这时候拔卡，写进去的就是半张盘。命令里的 /dev/sdX 必须换成你刚确认的那块卡。

Windows 上还有另一套写法：不用 Pi Imager，直接拿 Rufus 把镜像文件写进卡里，选完设备、选完镜像、点开始。下面两张截图就是这条路走下来的界面，注意看它要你确认的几个框：设备栏是那张 64GB 的卡，引导类型选的是镜像文件，分区类型 MBR，文件系统 Large FAT32，状态栏走到「准备就绪」才可以按开始。截图里选中的镜像文件名是 Armbian 的 Radxa Zero 3 版本，那是另一条硬件线的系统盘，步骤本身跟写 microduck.img.xz 一模一样，别被名字带偏。

按开始之后界面会变成这样，绿色的进度条配上实时速率，截图里这一下是 28.7 MB/s。这段时间别拔卡、别关软件、别让电脑休眠，写完它自己会提示完成。

配 Wi-Fi 的两条路：改卡里的文件，或者插 HDMI 敲 nmcli

这一步决定你后面能不能用 SSH 连它。两条路任选一条，先记住一个前提：Pi Zero 2 W 只支持 2.4GHz Wi-Fi，家里如果是纯 5GHz 或者双频分开且只给了 5G 的名字，它连不上，换 2.4G 那个。

第一条路最省事，卡还没拔出来就能办。刷完把卡拔下再插回电脑，Ubuntu 一般会挂出两个分区：bootfs 是启动分区，直接可编辑；rootfs 是系统根分区，不用手动改。要改的是 bootfs 里的 network-config。

sudo nano /media/$USER/bootfs/network-config

文件里是一段 YAML，结构照原样留着，只改三处占位符：国家码写两位，比如 CN、US、GB、FR；Wi-Fi 名字和密码填你家的。改完存盘、安全弹出、插回鸭子上电。

顺便说一句，这个文件支持一次写多个 Wi-Fi。家里一个、手机热点一个，写在同一份 access-points 下面，到哪都能自动挑能连上的那个。这对经常带出门演示的人是刚需，省得每次改卡。

第二条路是插 mini HDMI 显示器和 USB 键盘（Zero 这种小板子需要 OTG 转接头），把鸭子当一台小电脑用。镜像是 Lite 版，没有桌面，开机就是黑底白字的终端登录。第一次启动要先扩分区，等一到三分钟，这段千万别断电，断了分区就废了。

看到登录提示后输 user，密码是 password。输密码时屏幕不会显示任何字符，一个点都没有，这是正常现象，敲完直接回车。进去之后连 Wi-Fi：

nmcli device wifi list

先把周围的热点列出来，确认你的名字在里面。然后连它：

sudo nmcli device wifi connect "你的WiFi名字" password "你的WiFi密码"

连上还不够，得让它开机自动连，顺便把 Wi-Fi 省电关掉，不然它自己进省电状态，SSH 会时不时卡一下。

sudo nmcli con mod "你的WiFi名字" connection.autoconnect yessudo nmcli con mod "你的WiFi名字" wifi.powersave disable

这两条都是改连接配置：第一条让它记住、以后开机自己连，第二条关掉这条连接的省电模式。最后确认一遍：

nmcli -t -f NAME,TYPE,AUTOCONNECT,DEVICE connection showhostname -I

看 AUTOCONNECT 那一列是不是 yes，再看有没有拿到 IP。两个都对，以后每次开机它自己就上线了。

首次启动等一到三分钟，怎么算真的起来了

第一次上电它会做四件事：把文件系统扩到整张卡、重新生成 SSH 主机密钥、读 network-config 连 Wi-Fi（用第一条路配的才有这一步，第二条路是进去之后自己 nmcli 配）、启动后台那个手柄服务。这四件事都不出声，你只能等，一到三分钟是正常范围。

怎么判断它真起来了？在电脑上先叫名字试试：

ping microduck.local

这条能通，说明主机名解析和网络都活着。如果 .local 解析不了，别怀疑鸭子坏了，去路由器后台翻一下它分到的 IP，用 IP 直接连，一样能进。

ssh user@microduck.local

默认密码还是 password。第一次登录完建议立刻改掉：

passwd

这条会连着问你当前密码和新密码两遍，改完下次就用新的登。放在家里局域网其实风险不大，但这台机器将来是要连蓝牙手柄、可能还要开服务的，密码别留默认值。

第一次跑模型：在 SSH 里跑，或者远程 SSH 跑

作者把这件事写成了两节，「SSH 模式」和「远程 SSH 运行」，看标题像是两种玩法，实际敲的命令是同一套，区别只在你在哪台机器上敲、以及程序不肯停的时候怎么办。先说结论：只要电脑和鸭子连在同一个 2.4GHz Wi-Fi 里，你在 Windows 的 PowerShell 或者 Linux、macOS 的终端里 SSH 进去跑就行。

进目录，然后启动：

cd ~/microduckPYTHONPATH=src .venv/bin/python src/main.py

第二条前面的 PYTHONPATH=src 是告诉 Python 去 src 目录里找模块，不设这一句，程序会在 import 自己的包时直接报错退出，看着很像镜像没刷好。

跑起来之后它会按顺序做四件事：打开舵机扭矩、平滑地回到中立位（neutral pose）、开始读键盘或手柄输入、加载 walk.onnx 行走策略。第一次跑，把鸭子放在平稳桌面上，或者干脆用手扶住，扭矩一开它会自己找姿势，别让它从桌上翻下去。

键盘操作这套键位记一下，比想象中好用：

还有一个细节：如果你之前连过这台机器，SSH 会报 REMOTE HOST IDENTIFICATION HAS CHANGED。这不是被攻击，是镜像首次启动重新生成了主机密钥，清掉旧记录再连就行。

ssh-keygen -R microduck.local

停不下来怎么办。正常按 q 就退，但如果程序卡住了没反应，别去拔电源，另开一个 SSH 窗口发停止指令：

PYTHONPATH=src .venv/bin/python src/stop.py

关机也走命令，别直接断电源。拔电拔多了，SD 卡迟早给你颜色看：

sudo shutdown -h now

这条下去之后等十到十五秒，再去关电源开关。急这几秒钟，换来的可能是下次开不了机。

手柄：配对一次，之后无头也能启动

键盘跑通之后就该上手柄了，毕竟你不能抱着笔记本追着鸭子跑。SSH 进 Pi，进蓝牙交互界面：

bluetoothctl

进去以后依次敲这几条，其中 XX:XX:XX:XX:XX:XX 换成扫到的手柄地址：power on 打开蓝牙适配器，agent on 打开配对代理，scan on 开始扫描，等手柄出现在列表里，然后 pair、trust、connect 三条依次对上同一个地址，最后 scan off 收工、quit 退出。trust 那条别省，它记住设备，下次开机不用重新配。

这个镜像里已经装好了无头手柄服务，开机就挂着。手柄连上之后，不用 SSH、不用电脑，按住 START 两秒就能把控制循环拉起来：

这里有个现象得提前说清楚，不然你会以为机器坏了：手柄一连上，那个服务会把 Wi-Fi 关掉，为的是让 2.4GHz 蓝牙稳一点。所以你正 SSH 着，手柄一开，连接就断了。这不是故障，是设计。要回到 SSH，先把手柄关掉，Wi-Fi 会自己恢复。

另一条线的配网和版本，别跟这条混着用

国内还有一条走 Radxa ZERO 3W 加十五个飞特 HD1910 的复刻线，它的镜像、配网和版本号跟上面完全是两套东西，混着照抄必然对不上。

它的系统盘叫 microduck-zero3w-0.15.1-R1.img.xz，作者给的 sha256 是 75da978b5d56acd9e4146256431732381de84523bb683e4ab7ac9f0580a7bce5，刷写推荐用 Armbian Imager，压缩包直接喂进去，不用自己先解压。

配网方式也不一样，不是改卡里的文件，而是开机后手机连它自己开的热点，名字 Microduck-kissqy，密码 12345678，手机一般会弹配网页面，填家庭 Wi-Fi 和新的登录密码；没弹就手动开 10.42.0.1:8088。配完在电脑上跑它的机器人中控（版本 V167，Windows 解压后运行 start.cmd，macOS 用 start.command），填 ZERO 的 SSH 地址和登录信息，界面里能看到摄像头、3D 姿态、关节和 IMU 状态。这套镜像预装的是 control.40，用中控装随包固件升到 control.43，版本对不上时中控会报出来。

最容易被忽略的差别是 Wi-Fi 频段，而且两条线要求正好相反。Pi Zero 2 W 只有 2.4GHz，只能用 2.4G；Radxa 这条线明确要求接 5GHz，因为 2.4GHz 会跟无线手柄抢频段，作者实测会断网、SSH 超时、连不上。你要确认自己到底连在哪一段，可以在终端里看这一列：

nmcli -f IN-USE,SSID,FREQ,SIGNAL device wifi list

看 IN-USE 那一列，带星号的就是当前在用的那条，后面跟着频率。名字里带 5G 不等于真连在 5GHz 上，别凭名字判断。

最后

把这段流程走完，你会得到一个能 ping 通、能 SSH、能按 v 键走两步的鸭子。这一段的门槛其实全在细节上：镜像没校验、卡写了一半、Wi-Fi 频段不对、PYTHONPATH 没设、手柄一开把 Wi-Fi 顶掉。上面这些坑，官方教程里都有对应的一句话，只是散在几个小节里，新手一次看不全。

真正麻烦的部分在后面——舵机 ID 分配、零位标定、参数调、走两步就摔怎么查。那些是另外的活，跟刷机不是一回事，别在这一步就开始怀疑人生。

这篇的步骤、命令和默认值都对着 AI-FanGe 的 Microduck-build-tutorial（MIT 协议）核过；Radxa 那条线的做法只作要点参考，那个仓库是作者个人非商业许可，商用要先取得书面授权；刷卡截图取自 fanhao375 的复刻记录。