NAO V6 的开发环境配置这件事，我前前后后折腾了不止一次，从最初拿到机器人不知道从哪下手，到后来帮实验室和几个朋友团队搭建了一套能稳定复用的流程，中间踩过的坑比想象中多。今天这篇就把 NAO V6 开发环境配置的全过程拆开来讲，从工具选型、Python 环境、网络连接到第一个可运行的脚本，该注意的细节全部写在下面。文末我还会把整理好的文件清单和目录结构列出来，照着做基本不会出大问题。
适合看这篇的读者有三类：刚拿到 NAO V6 机器人、正在配环境的实验室新人；准备基于 NAO 做二次开发但被 SDK 版本搞晕的开发者；以及手头没有实体机器人、想先用模拟器写逻辑的爱好者。不管你是 Windows、macOS 还是 Linux，核心思路完全一致，我会在关键节点标注三个系统的差异。
1. 项目概述：NAO V6 开发环境配置的完整思路
1.1 为什么要专门梳理一遍开发环境
NAO V6 不像普通嵌入式设备那样插上 USB 就能开干。它本身运行着一套基于 Linux 的 NAOqi 操作系统，你写的代码要么通过 Choregraphe 图形化编排后上传到机器人，要么通过 Python 或 C++ SDK 在电脑侧连接机器人、调用 NAOqi 提供的各种 API 去控制动作、语音、视觉、传感器。这两条路的前提都一样：电脑端必须有一套和机器人端 NAOqi 版本匹配的开发环境。
我遇到过不少朋友卡在第一步，症状很典型：SDK 下载下来了，Python 装好了，import naoqi 却直接报错；或者 Choregraphe 装好了，却一直连不上机器人。这些问题十有八九不是机器人坏了，而是电脑端环境没配对。版本不匹配、环境变量没配、网络不在同一网段、防火墙拦了端口，任何一个环节出问题都会让你怀疑人生。所以把开发环境当成一个独立的小项目来对待，按步骤走，是最省时间的做法。
1.2 NAO V6 的软件栈构成
NAO V6 这一代机器人的软件栈其实可以拆成三层来看：
- 机器人端系统：NAOqi OS，基于 Linux 内核，负责底层驱动、传感器采集、行为管理和网络服务，对外暴露 NAOqi API。V6 出厂搭载的 NAOqi 版本一般是 2.9.x，这个版本号直接决定了你电脑端该用哪个 SDK。
- 开发端工具：Choregraphe 可视化编程软件，支持拖拽式行为框图设计，也可以直接内嵌 Python 脚本块；同时支持连接实体机器人或启动内置模拟器。
- 开发端 SDK：NAOqi Python SDK 和 C++ SDK，本质上是把 NAOqi API 封装成了本地可调用的库。Python SDK 在 2.8.x 时代仍要求 Python 2.7，2.9.x 开始才逐步支持 Python 3，这是个非常重要的坑。
明白了这三层结构，配置环境就不再是东一榔头西一棒子了。你只需要把电脑端工具链配好，再保证电脑和机器人之间的网络通路畅通，剩下就是调用 API 写逻辑的问题了。
2. 开发环境总体设计与工具选型
2.1 选型思路：模拟器优先，实机验证
我的建议是，环境搭建阶段就把模拟器和实机两条链路都打通，但日常开发默认用模拟器。原因很简单：机器人反复开关机、充电、连接调试，对硬件寿命和开发效率都不友好。Choregraphe 自带的模拟器能模拟大部分行为模块，包括动作、语音、传感器的基础反馈，足够你验证逻辑。
实机验证则放在两个节点：一是环境刚配好时跑一个最简单的“自检脚本”，确认电脑能通过 NAOqi API 控制真实机器人；二是完成一个完整行为模块后，上实机看动作效果和参数调优。这条“模拟器开发、实机验收”的路径，能帮你省掉大量无效等待。
2.2 工具版本匹配，是环境配置的命门
NAO V6 配套的工具版本，我直接把我实测可用的组合列出来：
| 组件 | 推荐版本 | 说明 |
|---|---|---|
| NAOqi OS（机器人端） | 2.9.x（以机器人内置为准） | 可通过系统设置查看 |
| Choregraphe | 2.8.6 或更高 | 支持 V6，自带模拟器 |
| Python SDK | 2.8.x / 2.9.x 对应版本 | 注意区分 Python 2.7 与 3.x 版本包 |
| Python 解释器 | 2.7.18 或 3.x（按 SDK 决定） | 老 SDK 只认 2.7 |
| 操作系统 | Windows 10/11、macOS、Ubuntu | 三者均支持 |
这里要特别强调版本匹配：Choregraphe 的版本号、Python SDK 的版本号和机器人端 NAOqi 的版本号，三者之间不能差太远。比如机器人端是 NAOqi 2.9.5，你却用 2.1.x 的 Python SDK，连上之后大部分 API 的返回结构都对不上，排查起来非常痛苦。我在文末整理的文件包里，会把对应版本的下载入口和校验方式一并标注清楚。
2.3 为什么不建议一上来就选 C++ SDK
NAO 的 C++ SDK 性能更好，但它带来的额外复杂度是：需要配置交叉编译工具链、需要在电脑上装对应架构的依赖库、还要处理编译产物和机器人端的兼容性。对于绝大多数实验室项目和课程作业来说，Python SDK 已经完全够用，NAOqi 的 Python API 覆盖了动作、语音、视觉、对话、导航等几乎所有能力，而且写起来直观、改起来快。
如果你是做运动控制底层算法或者需要极致性能的实时控制，那再考虑 C++。我认识的做 NAO 步态算法的朋友确实用 C++，但那是少数场景。对刚入门的人来说，先跑通 Python 链路，再决定要不要引入 C++，是投入产出比最高的路线。
3. 分步配置实操：从零开始搭建可用环境
3.1 第一步：下载并整理所需文件
配置环境最容易乱的就是文件管理。我建议在工作目录下建一个清晰的目录结构，所有工具和脚本都归档好，后面排错时能省一半时间：
nao-dev/ ├── installers/ # Choregraphe 安装包、Python 安装包 ├── sdks/ # Python SDK、C++ SDK（解压后） ├── config/ # 环境变量脚本、网络配置脚本 ├── examples/ # 测试脚本、示例工程 └── docs/ # 官方文档、版本对照表、README下载时注意：Choregraphe 和 SDK 都要从官方开发者站点下载，认准版本号。有些第三方网站会提供整合包，但我不建议用，因为你不知道里面是什么版本、有没有被改动过。下载完成后，先核对文件 MD5 或 SHA256 值，再开始安装，这一步虽然啰嗦，但能避免很多诡异问题。
3.2 第二步：安装 Python 并配置虚拟环境
如果你的 SDK 是 2.8.x 版本，那对应的 Python SDK 包是基于 Python 2.7 编译的，这时候必须装 Python 2.7.18。如果拿到的是 2.9.x 版本且标注支持 Python 3，那建议装 Python 3.6 到 3.8 之间的版本，太新的版本会因为某些依赖库不兼容而出问题。
装完 Python 后，我强烈建议用虚拟环境隔离 NAO 开发环境，避免和系统 Python 冲突。具体操作：
# 创建虚拟环境 python -m venv naoenv # 激活环境（Windows） naoenv\Scripts\activate # 激活环境（macOS/Linux） source naoenv/bin/activate然后把 Python SDK 解压后的路径加入环境变量。以 Windows 为例，需要把 SDK 中的lib目录和根目录都加入PYTHONPATH，否则import naoqi会找不到模块：
# Windows 临时设置（建议写入系统环境变量） set PYTHONPATH=D:\nao-dev\sdks\pynaoqi-python2.7-2.9.x\lib;D:\nao-dev\sdks\pynaoqi-python2.7-2.9.x # macOS/Linux 临时设置 export PYTHONPATH=/path/to/naoqi-sdk/lib:/path/to/naoqi-sdk提示：把 PYTHONPATH 写入系统环境变量时，记得同时保留系统原有的 PYTHONPATH，用分号（Windows）或冒号（macOS/Linux）拼接，不要覆盖。踩过这个坑的人绝对不止我一个。
验证 SDK 是否可用，打开 Python 交互终端执行：
import naoqi from naoqi import ALProxy print(naoqi.__file__)如果能看到模块路径打印出来，说明 SDK 导入成功，Python 环境这一关就过了。
3.3 第三步：安装 Choregraphe 并配置连接
Choregraphe 是图形化开发的核心工具。安装过程不再赘述，重点是安装完成后的连接配置。
启动 Choregraphe 后，先设置机器人 IP。有两种方式：
- 在连接面板中直接填入机器人的 IP 地址；
- 通过“编辑 -> 偏好设置”里配置默认连接参数，这样每次启动都会自动尝试连接。
实体机器人默认开放 9559 端口给 NAOqi 服务，Choregraphe 和 Python SDK 都是通过这个端口通信的。机器人在同一局域网内，建议使用静态 IP，避免 DHCP 分配变化导致经常改配置。
连接之前，先做两步确认：
- 用 ping 命令测试电脑到机器人的网络连通性：
ping 192.168.1.100（改成你的机器人 IP），看丢包率和延迟。 - 检查防火墙是否放行 9559 端口。Windows 系统尤其容易在这里出问题，需要在防火墙高级设置里添加入站规则，把 Choregraphe 或 Python 的访问权限打开。
如果暂时没有实体机器人，可以点 Choregraphe 工具栏的模拟器按钮，它会启动一个虚拟机器人，界面里能看到 NAO 的 3D 模型和传感器反馈面板。模拟器模式下的开发流程和实机几乎一致，只是部分硬件相关参数需要后续在实机上重新校准。
3.4 第四步：编写并运行第一个测试脚本
环境配好之后，先用一个最简单的脚本验证全链路是否通畅。下面的脚本做了两件事：连接 NAO 的语音合成服务，让机器人说一句话；再读取它的电量，证明传感器数据通路正常：
import time from naoqi import ALProxy ROBOT_IP = "192.168.1.100" ROBOT_PORT = 9559 # 语音合成 tts = ALProxy("ALTextToSpeech", ROBOT_IP, ROBOT_PORT) tts.say("Hello, NAO. This is my first test.") # 读取电量 battery = ALProxy("ALBattery", ROBOT_IP, ROBOT_PORT) level = battery.getBatteryCharge() print("Battery level: {}%".format(level)) time.sleep(1)如果机器人成功开口说话，并且打印出电量数值，那恭喜，你的 NAO V6 开发环境已经全部打通了。之后你可以在这个基础上继续叠加动作、视觉、对话等模块。
再进一步，试试让它做一个简单的动作，比如点头：
motion = ALProxy("ALMotion", ROBOT_IP, ROBOT_PORT) motion.wakeUp() # 唤醒机器人（电机上电） motion.angleInterpolation( ["HeadPitch"], [0.3, -0.1], [1.0, 2.0], True )注意：
wakeUp()会让机器人从休眠状态进入待命状态，电机全部上电。如果是第一次操作，建议把机器人放在地面或者防倾倒的支架上，防止它做出意料之外的动作。rest()则会让它回到休眠状态，测试完毕记得调用。
4. 常见问题与排查技巧实录
4.1 问题一：import naoqi 报 ModuleNotFoundError
这个错误绝大多数情况是 PYTHONPATH 没配对，或者 Python 版本和 SDK 不匹配。先确认你用的 Python 版本和 SDK 要求的版本是否一致，再看sys.path里有没有 SDK 路径：
import sys for p in sys.path: print(p)如果 SDK 路径没出现，回到 3.2 节重新配置环境变量。如果是版本不匹配，去官方站点重新下载对应版本。还有一种情况：虚拟环境里装过别的包，导致 naoqi 模块被某个同名目录遮蔽，检查一下虚拟环境的 site-packages 里有没有残留的 naoqi 目录。
4.2 问题二：Choregraphe 一直连不上机器人
先从下往上排查：
- 机器人和电脑是否在同一网段？用
ipconfig（Windows）或ifconfig（macOS/Linux）查看电脑 IP，和机器人 IP 对比前三位是否一致。 - 机器人是否处于可连接状态？NAO V6 在休眠状态下网络服务可能仍在运行，但如果之前被设定的“飞行模式”之类的策略限制，会导致端口不可达。
- 9559 端口是否被防火墙拦截？临时关闭防火墙测试一下，如果能连上就说明是规则问题，再去细化放行规则。
- 是否用了错误的 IP？机器人 IP 可以在 Choregraphe 连接面板左下角扫描发现，或者在机器人 Web 管理页面查看，建议以这两个来源为准，不要凭记忆输入。
4.3 问题三：模拟器能跑，实机动作异常
这是最典型的环境差异问题。模拟器里 NAO 的运动学和物理反馈是理想模型，实机则有电机扭矩、重心偏移、地面摩擦力等因素影响。我的经验是：写动作时先把幅度、速度参数调小一半，在实机上观察实际表现，再逐步逼近目标参数。特别是angleInterpolation这类直接控制关节角度的 API，参数差一点，实机上的视觉效果就完全不同。
另外，实机运行时记得调用ALMotion的setStiffnesses把相关关节的刚度打开，否则电机会处于松垮状态，动作执行会失败或者很怪异。模拟器不会暴露这个问题，实机必现。
4.4 问题四：机器人连接时好时坏
如果你的手机、电脑、机器人共用一个 WiFi，而且路由器是家用级的，很容易出现并发连接数超限导致 NAO 掉线。解决办法是给机器人单独拉一根网线连路由器 LAN 口，同时给电脑也走有线或 5G 频段。还有一个容易被忽略的点：NAO V6 的 WiFi 天线功率一般，和路由器的距离、遮挡物都会影响稳定性，别让机器人隔着一堵承重墙和路由器通信。
5. 从环境配置到第一个完整行为模块
5.1 用行为框图搭一个“自我介绍”流程
环境跑通之后，我建议用 Choregraphe 搭一个完整的行为流程，来巩固对开发流程的理解。比如一个“自我介绍”行为：
- 开始事件触发后，先用
ALTextToSpeech说“大家好，我是 NAO”； - 同时让
ALMotion执行一个抬手的动作； - 停顿 2 秒；
- 播放一段默认动画或再做一个鞠躬动作；
- 最后回到闲置状态。
在 Choregraphe 里，这个流程就是几个盒子（Box）用连线串起来的事。把语音盒子和动作盒子并联在同一个输入端口下，它们就会并行执行。串联则用顺序连线，保证一个执行完再执行下一个。这个过程能帮你理解 Choregraphe 的时序模型，也方便后续把行为导出成 Python 代码来细看。
5.2 配置过程中的几条心得
最后分享几个我实际使用中的体会，都是文档里不会写的：
第一，环境配置不是一次性的。Choregraphe 和 SDK 升级、机器人 NAOqi 系统重置、电脑系统大版本更新，都可能导致之前配好的环境突然失效。建议把 3.1 节的文件包和配置脚本纳入版本管理，团队内部共享时，新手按照 README 走一遍就能恢复环境，不用每次重新摸索。
第二，所有连接类的配置，优先写成配置文件而不是硬编码在脚本里。我习惯在项目里放一个config.yaml或robot_config.py，统一管理 IP、端口、用户名密码，需要切换机器人的时候只改一处，不会因为 IP 散落在各处而出错。
第三，善用 NAOqi 的日志和调试接口。ALLogger模块可以设置各模块的日志级别，当你觉得某个行为表现不正常时，把日志级别调到 DEBUG，能看到完整的调用链和参数，排查效率比对着代码猜高得多。
配置 NAO V6 开发环境这件事，本质上就是三步：版本配对、网络打通、写通一个测试脚本。把这三步按顺序走完，后面的开发就是自由的。我整理的文件包里包含了安装包索引、配置脚本、示例代码和版本对照表，覆盖了 Windows 和 macOS 两种环境，你需要的其实就是按照这篇文章的顺序，一步步把环境跑起来。动手吧，配好之后你会发现，NAO 的世界比想象中有意思得多。
