启元机器人开发指南：普通版能玩什么，开发版能改什么，想动手该从哪下手

写在前面

这篇写给两种人：正在考虑买启元机器人、想知道"开发版到底多了什么"的人；以及已经买了或者白嫖了真机、准备动手但不知道从哪下手的人。文中的架构描述、接口数量、开发模式分级全部核对自启元官方公开材料（AtomGit 仓库 q1-sdk/t1-sdk、dev.primebot.com 文档与下载页、产品页），查阅日期 2026-10-27。个别地方拿鸿蒙/手机生态做类比，那是类比不是官方说法。"六层开发深度"的划分是笔者为讲解画的示意，官方没有这个分级，但每一层的依据都是官方文档原文。

启元开放平台提供了很多能力，对于刚上手的开发者可能一上来有点蒙圈，本篇篇把机器人里面长什么样讲清楚，再顺着架构从最表层到最深层，把六层开发各自能做什么、要什么条件逐层过一遍，最后按人群给出可以直接执行的下手顺序。

一、先认识这两台机器

启元是上纬新材（科创板 688585，做过风电叶片材料，2025 年被智元机器人要约收购）旗下的消费级机器人品牌，2026 年 9 月 20 日发布两款产品，技术带头人是稚晖君（彭志辉），首席科学家是北大董豪。两款机器人都拆"标准版/开发版"两档卖：

	启元 Q1	启元 T1
形态	88cm、约 15kg 的小尺寸人形，可折叠装机，全身 22 个力控关节	100cm，约16.3kg，可变形：轮足人形与四足两种形态切换，站立约 1m，带双臂
定位	人机互动、动作编排、桌面级陪伴	随行移动、影像创作、家务类操作
标准版	¥19,999	¥19,999
开发版	探索版 ¥26,999	T1 Pro ¥29,999
开发版多出的东西	SDK/HDK 权限、机身扩展口（USB-A、USB-C、RJ45、12V/5A）	SDK 权限，另加 Orin Nano 算力、双目+鱼眼相机、更多 TOF

图1｜T1 两款机器外形

图2｜Q1 两款机器外形
两款机器人内部是同一套设计思想，本文讲的所有开发分层对两款都成立，机型差异只在具体接口表：T1 多出舵机和颈灯控制、相机是双目（Q1 单目），两款的动作枚举表同名不同内容。

二、拆开看：一般机器人的架构，启元也不例外

想买机器人的人常把它想象成"一个大号嵌入式设备"，不是的。现代智能机器人的通用架构是一块实时控制域加一块非实时计算域，再挂一圈智能关节，启元是这套教科书结构的标准样本：

图3｜Q1 内部架构与六层开发对照。左：机器人本体的三个域与对外接口，依据 q1-sdk v1.0.0.0《快速入门与集成指南》§1 网络拓扑与 §5 开发者模式表绘制；右：笔者按干预深度整理的 L0-L5 六个开发层，每层的权限条件标注在框内。层划分为科普示意，非官方术语。

对着图说人话。机器人躯干里有两台 Linux 电脑：运控板（内网地址 10.1.1.100）跑实时系统，负责平衡、步态、关节伺服这些以毫秒计的事，同时给触摸、相机、电池这些硬件提供抽象服务；大脑板（10.1.1.101）跑非实时的 AI 活，视觉识别、语音交互、官方功能，以及一个技能运行时，负责装载和执行 rpk 技能包。两台板子之间、板子与你之间，走同一根网线串起来的局域网，通信协议是 ROS2 的 DDS 总线。最外面是身体：22 个带编码器和力矩传感的关节电机（Q1），编码器状态以 1kHz 回报给运控板。

这个架构里藏着理解启元开发的一切钥匙，就三句话。

第一句：机器人买回来那天起就已经"会"很多东西了。走路、跳舞、听你说一句话做反应，全部是官方程序常驻在两块板子里跑着，不需要你。你的开发不是从零驱动硬件，是往一个已经在运行的分布式系统里注入新行为。

第二句：所谓 SDK，就是这张总线网络的"通讯录 + 话术手册"。启元把它写成 54 个消息定义文件（aimdk_msgs 包），规定了机器人对外广播哪些状态频道、开放哪些服务窗口、每种消息什么格式。SDK 里没有一行驱动电机的代码，因为驱动的活运控板自己干了。

第三句：普通版和开发版的分界线，就是上面这张图里那条蓝色的总线。普通版机器人不是没有总线，是总线对你关门：默认"标准生产模式"下，外部设备发现不了它的网络服务，机身网口也不通。开了开发者模式，它才对外播报"我会什么、谁想让我动都可以来找我"。差价七千买的就是这扇门加门后的房间。

三、从门缝往里看：六层开发，一层一层说

下面从最浅到最深过一遍每一层能做什么、要什么。你可以把它当一张"我到底买亏了没有"的对照表：每一层都标了它对版本的要求。

L0 内容层：不写一行代码的"开发"

标准版能做的全部事情基本都在这一层，但这一层的体验并不寒酸，消费级产品的卖点恰恰聚在这。手机 APP 里可以编排官方动作库的舞蹈串烧、调表情、配台词；PrimeStore 内容商店里喜马拉雅故事、QQ 音乐、有道口语这些服务可以直接在机器人上跑；SkillHub 技能商店里别人做好的技能，你可以直接下载安装。再往外是 PrimeFLOW 外观定制平台，改机器人的"皮肤"；以及拖拽示教，手把着机械臂摆一遍，机器人记下这段轨迹，以后照着做。

这一层的产物是内容和动作包，不是程序。类比手机生态，它是"主题商店 + 快捷指令"而不是"应用开发"。对普通用户，这层已经把一台 19,999 的机器玩满了；对想干点的你，这层的价值是搞清楚官方到底给了什么原材料。

L1 技能层：写一个"装进机器人"的程序

这是多数开发者真正要走的路线，也是唯一一条产物会"住进机器人"的路。你写一个 Python 目录加一份 manifest.json，manifest 声明四件事：适配哪款机型、要调用哪些机器人接口（相当于权限清单）、用户说什么话触发它、以及一组安全守卫参数（移动限速、低电量拒接、触摸确认动作）。打完包是 .rpk 文件，经 PrimeConsole 导入验证后发布 SkillHub，机器人侧的技能运行时装载执行。

拿鸿蒙对照最直观：rpk 之于启元，就是 HAP 之于鸿蒙，声明驱动、平台授权、商店分发，三件套一模一样。区别在闸门的硬度：鸿蒙的权限声明在编译期强制校验，声明外的 API 你根本调不到；启元当前的 rpk 运行时对"程序实际调了什么"不逐条核对，manifest 更多是一份君子协定。它把正确答案都写在纸上了，就差把闸门合上。

这层有个巨大的友好性：开发验证全程可以不碰真机。官方技能自带 Mock 后端，PrimeConsole 可以在没有机器人的情况下导入 rpk、跑上肢动作仿真、验证 manifest 合法性。我认识这个生态就是从这条无真机链路进去的。技能包经商店分发后标准版机器人也能安装，但技能要真正调用 SDK 层接口干活，取决于运行时对总线资源的代理深度，目前官方示例技能的完整运行形态都在开发版机器上验证。

L2 SDK 直连层：你的程序成为机器人的"外挂大脑"

到这一层，开始动用那扇开发者模式的门。开发版机器人打开开关（手机 APP 设置→开发者功能→阅读须知→选基础开发→保存→重新上下电），你的 Ubuntu 22.04 电脑用网线接机身 RJ45 口、配静态 IP 10.1.1.99，编译 aimdk_msgs，source 环境变量，ros2 topic list 里刷出 /aima/ 开头的话题流，你的程序从此是这台机器人分布式系统里平等的一个节点。

能干什么？三个方向。感知方向，订阅相机单帧 JPEG 或 RTSP 视频流、头部触摸事件、电池状态，读语音识别结果的话题。决策方向，完全在你的电脑里，接你自己的视觉模型、你的 Agent、你自己的规则引擎，机器人管不着。执行方向，通过服务调用切运动模式（Q1 的 McAction 枚举有 61 个生效动作，站立、行走、轮足、全身控制、上肢自定义各占编号段），发 100Hz 的速度指令或上肢关节目标角，让机器人说话（TTS 有六级优先级仲裁）、做表情、打灯语。

这层最值得写进决策手册的是两个约束。一个技术约束：控制权仲裁。遥控器、语音、官方技能、你的程序都想动机器人，协议的处理方式是注册制，你的程序登记一个输入源、拿一个 0-100 的优先级（SDK 二开默认档 30，遥控器在更高档）、以及 1 秒心跳租约，断心跳控制权自动收回。它假设你的代码一定会崩，并且为崩溃做好了安排。一个商务约束：启用须知里白纸黑字，开启开发者功能后不再享受维保服务。厂商的逻辑跟解锁 bootloader 的安卓机一样，你让它做的事超出了它的测试范围，摔坏了不怪它。

L3 端侧部署层：程序从电脑搬进机器人

L2 的程序永远拖着一根网线，想剪掉它，就得把算法编译进大脑板。启元为此开源了三套 Docker 工具链：x86 原生编译（在自己机器上编译、跑仿真验证）、x86 交叉编译 ARM（在开发机上编译出能跑在机器人板卡上的可执行文件，scp 拷进板子部署）、ARM 原生编译（干脆在机器人板卡上开容器直接编）。交叉编译指南里连"部署前必须修复路径"这种坑都写明了，是认真做过的人写的文档。

这层的典型场景：视觉模型要低延迟、或者产品形态不允许外挂一台笔记本（比如做移动巡检、家庭陪伴的商业部署），推理必须离机在线。企业开发者在这层真正获得"私有算法进机器人"的通道，数据可以不出机身。代价是彻底离开舒适区：板卡的算力内存是定死的，Orin 和 RK 两个平台的依赖各有麻烦，交叉编译的依赖地狱是端侧部署的老朋友。

L4 低层运控层：绕过官方动作，直接给关节发指令

开发版 App 里的开发层级还有一档"高级开发模式"，允许关闭特定官方模块、接管底层运动控制框架，用 /aima/hal/joint/command 直接对 22 个关节下指令（1kHz 语义）。这是做新步态、做力控算法研究的人的入口。

要清楚它的分量：高层运控（平衡、步态保护）被关掉之后，机器人摔倒了没人管，因为安全兜底的那层软件是你自己关的。官方文档写得很坦率，这条路的适用场景是"深度算法开发"，言下之意，普通人碰不到，碰到了请先掂量自己要不要一台会摔的机器人。

L5 硬件层：动螺丝刀的开发

最外面一层，SDK 完全不参与。开发版机身的 USB-A、USB-C、RJ45、12V/5A 供电口是留给外设的，官方开源了 HDK 硬件开发接口、整机外壳 STEP 三维模型和 DIY 外壳说明（推荐 3D 打印/复模），你可以做定制皮肤、加装载具、接树莓派当边缘盒子。这一层对应厂商语境里的"潮玩个性化"，对开发者的实际意义是：末端执行器改装、外挂传感器这类 SDK 接口表里没有的能力（比如夹爪），目前只能在这层用硬件手段解决。

六层横着一排看

层	一句话	需要什么版本	需要真机吗	产物在哪跑
L0 内容	编排动作表情、买皮肤、装商店技能	标准版即可	演示需要	机内资源
L1 技能	写 rpk，让机器人执行你的任务逻辑	开发版部署；仿真验证不需真机	验证不需要	机器人内（技能运行时）
L2 SDK 直连	你的电脑成为机器人的一环	开发版	联调需要	你的 PC（Ubuntu 22.04）
L3 端侧部署	算法搬进大脑板，断网可用	开发版	是	机器人内（你的进程）
L4 低层运控	直发关节指令	开发版 + Advanced 模式	是	机器人内，自担安全
L5 硬件	外壳、外设、改装	开发版（HDK）	是	物理世界

四、普通版能接入的，其实不止玩

这张表最容易让人误判的是第一行。标准版不等于"不能开发"，准确说法是：标准版能接入的全部能力都在内容层和商店层，你的"开发"活动止步于官方划定的范围：APP 编排、外观定制、示教录制、安装 SkillHub 上架的技能。这已经覆盖了陪伴、教育、娱乐场景里绝大多数个性化需求，对家庭用户这不是妥协，是本分。

判断自己到底需不需要开发版，可以只问一个问题：我要让机器人做的事，官方动作库加技能商店里有没有现成的或者类似的？有，标准版；没有、而且"让机器人做我没见过的事"正是我买它的理由，开发版。多花的七千块不是配置差价，是"这台机器归谁管"的权限差价。

五、决定动手了，按这个顺序下手

先画一条时间线，把六层落到具体步骤上：

图4｜从开箱到技能上架的 20 步旅程，四个阶段分别对应图1 的 L0→L1→L2/L3→技能分发。步骤依据 q1-sdk v1.0.0.0 快速入门 §2/§3、McInputSource 与 mc_action_switcher 示例代码、carry-clothes rpk 实例整理；三处新手常见卡点（维保条款、网卡绑定、状态机等待）在图下注明。

然后按人群给三条起步路径，每条都第一周就能见到效果。

学生/爱好者，没预算：不动机器人也能入场。Mac/Windows 装 PrimeConsole（macOS/Windows/Linux 都有原生包），下载官方 URDF 模型，用 MuJoCo 在笔记本上养一台数字孪生的 Q1；克隆官方技能仓库跑 --sim 仿真，改 manifest 字段看行为变化；把 SDK 仓库的 54 个消息定义当小说读完。这条链路我全部实走过（系列第 1、2 篇就是路书），等到真机到手那天，前面所有产物原样复用。

内容创作者/家长/老师：标准版 + L0/L1 浅水区。先花一周把 APP 编排和示教玩透，理解官方给了哪些"积木"；想把自己的课程、互动脚本变成机器人行为，走 L1，Python 会基础就行，用官方示例改造起步（天气播报、萝卜蹲游戏这两个示例的代码量都在三百行以内），用 PrimeConsole 的无真机仿真迭代。

开发者/企业：直接按 L2→L3→L1 的顺序打。第一步在 Ubuntu 22.04 环境把 SDK 编译接通，跑通 PlayTts 和一条关节控制，建立"总线节点"的心智模型；第二步按业务选 L3（算法要进机身）或 L1（能力要交付到别人手里的机器人），企业场景两者通常都要；第三步把验证过的能力沉淀成 rpk 上架，完成商业闭环。签合同前记得把"开发者模式弃维保"这条商务风险算进运维成本，以及盯一下版本矩阵，SDK 在 v0.x 到 1.0 之间有真实的接口迁移（音频链路整体换过协议），教程按 commit hash 锁版本看。

六、一句话收束各层

把整篇压成一张卡片存手机也行：

机器人架构是"两台 Linux 板 + 一圈智能关节 + 一条 ROS2 总线"。普通版和开发版的区别不是硬件强弱，是那扇总线的门开不开，以及开了之后要不要签"弃维保"。普通版能做的事：官方动作库、内容商店、技能商店、外观定制、示教。开发版能做的事：从往技能商店写 rpk（L1）、把电脑接上总线当外挂大脑（L2）、把算法编进机身（L3）、直驱关节（L4），到物理改装（L5）。想动手没有真机也能动手：模型和仿真资料全开源，Mac 上就能把 L1 的验证链路跑通。

我自己在 Mac 上养那台虚拟 Q1 的时候，最深的感受是这套生态把"想清楚再买"这条路修得很平：买之前你可以先确认自己真能在这台机器上做出东西。建议你在掏那七千块差价之前，也先花一个周末走一遍。

七、局限说明

本文是科普性梳理，不是逐接口的开发手册，接口数量（54）、动作枚举数（61）、价格与版本等硬数字均引自官方公开材料与本人实测核对，核对日期 2026-10-27，但 SDK 正处于 v0.x 到 1.0 的快速变更期，音频链路已在版本间整体迁移过一次，本文描述的接口形态可能随后续版本调整，以官方仓库对应 commit 为准。"六层开发深度"是本文为讲解自创的分层示意，官方文档并无此分级，各层权限的官方依据是《快速入门与集成指南》§5 的开发者模式五层表，我把它的权限语义与实际开发工具链对照后重排为按干预深度的六层，读者引用时请理解这是我的一家之言。文中对"标准版机器人能加载开发版技能包"的表述基于技能商店的公开形态推断，我没有标准版真机做验证；L1 技能在标准版上的完整运行边界（哪些接口被运行时代理、哪些被屏蔽）属于官方未完全公开的部分，本文按保守口径表述。全文未连接任何真机，所有"能做什么"的判断来自文档与示例代码阅读，不构成性能承诺。

参考资料

• 【1】 启元 Q1/T1 产品页与发布会公开资料（两款机器人形态、定价、双 SKU 权限分层、机身扩展口）。https://www.primebot.com/q1.html
• 【2】 PRIMEBOT/q1-sdk，《PrimeBot_SDK快速入门与集成指南》§1 网络拓扑、§2 开发者模式切换、§5 五层权限表（本文架构与开发模式分级的官方依据），锚定提交 7310314eee058323a2c15ab1f4f947df4112573e。https://atomgit.com/primebot/q1-sdk
• 【3】 PRIMEBOT/t1-sdk，锚定提交 a460300（Q1/T1 接口差异：舵机 SetServo、颈灯 SetNeckLight、单双目相机的数据来源）。https://atomgit.com/primebot/t1-sdk
• 【4】 PRIMEBOT/carry-clothes，锚定提交 301b02a（rpk 技能包 manifest.json 的机型锁定、接口授权、安全守卫、selfProvided 声明实例）。https://atomgit.com/primebot/carry-clothes
• 【5】启元机器人开发者社区下载页（三套编译工具链 x86 原生/x86 交叉 ARM/ARM 原生、PrimeConsole 桌面端、URDF V3.0）。访问日期 2026-10-27。https://dev.primebot.com/download
• 【6】 启元二次开发功能启用须知（"开启开发者功能后不再享受维保服务"商务条款，v1.0.0.0 手机 APP 内原文）。
• 【7】 本系列配套实测工程（数字孪生、SDK 能力清点、rpk manifest 审计的脚本与原始输出，均在文末各篇的 AtomGit 仓库，tag v1.0.x）。

启元机器人开发者社区

想在自己的设备上走通这条链路，或获取 Q1/T1 SDK、URDF、PrimeConsole 与技能开发资料，欢迎访问 启元机器人开发者社区。在这里插入图片描述