人形机器人这波浪潮里，宇树G1确实让不少开发者第一次摸到了“人形”的门槛。但真正拿到手之后，你会发现最头疼的不是电机怎么转，而是资料散得太开了：官方文档一个版本一个样，社区的帖子各说各话，GitHub上示例代码的接口命名可能隔了几个月就完全不兼容。我这次折腾G1二次开发，踩了不少坑，也翻遍了能翻的资料，最后干脆把整个过程里真正有用的信息梳理成了一份路线图式的合集。这篇文章不是官方文档的复读，而是一个爬过坑的人把路标重新立了一遍。想快速跑通第一个程序的新手、计划做产业项目的团队、想研究具身智能和上层应用的玩家，都能在这篇里找到对应自己阶段的内容。
1. 先搞清楚G1是什么，再想怎么改
1.1 硬件平台的基本盘
做二次开发，第一步永远是吃透硬件，而不是急着找接口文档。根据公开信息，宇树G1是一台中等尺寸的人形机器人，整机自由度在23个以上，肩、肘、髋、膝、踝这些关键关节都覆盖到了，身高大概在1米3以内，重量在35kg上下，属于实验室和极客团队都能接受的入门级全尺寸人形平台。关节电机用的是无框力矩电机加谐波减速器方案，这个配置决定了它的力矩输出、响应速度和控制的精细程度，也直接影响了你二次开发时能做多激进的动作。
我建议拿到机器后先做三件事：第一，把每个关节的编号和运动范围摸清楚，哪些是腰、哪些是腿、哪些是臂，官方手册里一般都有表格，但你最好自己在终端里读一遍实际值，因为出厂标定和手册标注经常有细微偏差。第二，搞清楚传感器布局，尤其是IMU放哪儿、深度相机在什么位置、脚底是否有压力传感器，这决定了你后面做力控和视觉的时候数据从哪来。第三，了解机载计算单元的算力水平，因为上层算法跑本地还是跑远端，直接取决于这块板子能不能扛得住。
1.2 二次开发的边界在哪
G1的二次开发不是“想做多深就做多深”，它存在一个清晰的开放层次。最上层是整机遥控，用原厂App或遥控器就能操作，这不算二次开发；中间层是官方SDK接口，你可以读取状态、下发目标位置、控制关节速度和力矩，大部分应用开发都落在这层；再往下是运动控制器内部算法的修改，比如步态调度器、稳定性控制、状态机这些，官方开放得比较有限，只能通过参数配置和有限的自定义接口去调整，想从底层重写一套步态算法就得另想办法了。
我的建议是：绝大多数团队把精力放在SDK层就够了。G1原厂已经帮你解决了“站起来不倒”这个最难的工程问题，你要做的是基于它稳定的运动能力去叠加自己的业务功能，比如导航、巡检、抓取、交互。如果一上来就想在步态层面动刀子，那不仅是工作量的问题，是摔机风险和调试周期的急剧上升。
1.3 你能拿G1做什么
理清楚边界之后才是场景。从我看到的实际案例来看，G1的二次开发主要集中在这几类方向：一类是商业场景验证，比如迎宾导览、安防巡检、展馆讲解，这些本质上是用机器人的运动能力加定制化交互逻辑；一类是科研平台，拿来做双足运动控制算法的验证载体；还有一类是具身智能方向，把视觉语言大模型接到机器人上，让机器人理解指令并执行动作，这也是目前热度最高的玩法。不同的场景对开发深度和技术栈的要求差别很大，选方向之前先确认项目需求匹配哪一层开放能力，能帮你少走很多弯路。
2. 资料从哪找：SDK、文档与开发者在手把手教你之前
2.1 SDK版本管理是第一个大坑
G1的SDK其实是在持续迭代的，这一点可能和很多人想的不太一样。你以为拿到一个稳定版本就能一直用，实际上官方会不定期更新接口定义、消息格式和功能模块，有时候是老接口废弃，有时候是新增了传感器数据的字段，有时候是修改了控制指令的坐标系定义。我见过最坑的情况是：一份网上流传的示例代码明明之前能跑，换上新的SDK包之后编译直接报错，原因是消息结构体的字段名变了。
所以你在找资料的时候，第一件事不是看教程发布时间，而是确认这份资料对应的SDK版本号，最好和你设备里的固件版本匹配。我的习惯是：从官网开发者入口申请SDK包，优先用Release版本而不是最新的main分支源码，因为Release版本经过验证，稳定性有保障。下载下来之后先看两样东西——CHANGELOG和examples目录，前者帮你了解这版改了什么，后者是你写自己代码前的活样板。
2.2 通信链路选型和实时性认知
G1的二次开发通信方式以网口为主，也就是通过局域网连接你的开发机，整机一般也支持无线网络连接，但我强烈建议初期调试阶段用网线直连。理由很简单：无线网络存在延迟抖动和丢包，而对机器人下发的控制指令恰恰是对延迟极其敏感的，一个周期的抖动就可能导致动作不连贯甚至失控。
这里要建立几个基本认知。控制周期通常是毫秒级或十毫秒级的，你需要关注的是端到端延迟而不是单向网速；指令下发频率和状态反馈频率未必一致，有的平台反馈可达高频，但下发的控制指令如果太密反而会让机器人内部的运动控制器无所适从。我实际测试下来的经验是：把状态读取和控制下发放到同一个主循环里，固定周期跑，比频繁单独读取要稳定得多。通信链路的实时性是所有上层应用的基座，一开始设计不好，后面每一步都在还债。
2.3 SDK的核心构成：客户端、消息、回调
大部分厂商的SDK设计思路都类似G1：一个客户端对象负责连接管理，一系列消息结构体承载控制指令和状态反馈，再加上事件回调机制处理异常和保护事件。你上手的时候不要急着写控制指令，先建立一个最简客户端，连接上之后把状态数据打印出来，确认你能收到姿态、关节角度、关节速度和电池信息等核心数据，这一层通了，后面的事情都有基础。
我还想提一个很多新手忽略的点：SDK通常会内置安全机制，比如心跳超时保护、关节软限位、摔倒检测。你调试的时候千万不要为了方便把这些机制关掉，尤其是心跳超时保护，一旦开着，网络不稳定时机器人会自动进入保护状态，虽然可能会中断你的程序，但它是防止机器人失控的最后防线。我的话放在这里：二次开发的第一原则是安全，第二原则才是功能。
3. 运动控制二次开发：最难啃的骨头
3.1 状态机思维比调参数更重要
人形机器人本质上是一个高度耦合的非线性系统，想要稳定控制它，靠纯公式推导是玩不转的。G1内部已经有一套完整的状态机，站立、行走、蹲起、转身、摔倒恢复这些模式之间的切换逻辑是写好的，你二次开发时最重要的工作是理解这套状态机，让自定义动作插在正确的状态节点上，而不是绕过它。
我自己刚开始的时候犯过一个错误：想做一个自定义的摆臂动作，就直接往关节下发了目标角度，结果机器人在站立状态下做出了一个重心严重偏移的姿态，触发保护直接坐下。后来才明白，任何动作指令都必须考虑当前状态机所处的模式，站立模式本来就有重心约束，违背约束的动作会被控制器夹生处理。正确的做法是先切换到合适的状态，或者把自定义动作拆成一系列符合当前状态约束的小步进指令，逐帧下发，让它平滑过渡。
3.2 关节空间控制与任务的映射
G1的SDK层最直观的控制方式是设置各个关节的目标位置、速度和力。这就带来一个问题：人类的意图通常是任务空间的，比如“手抬到某个高度”“向前走三步”，而不是“髋关节转20度”。在做二次开发的时候，你一定要在任务空间和关节空间之间建立清晰的映射关系。
我的做法是：先手工规划关键帧动作，用仿真环境确认关节角度合理，然后再固化成程序里的动作列表。做这类工作最好是先在仿真里跑通，再上真机，这一步能省下大量摔机的维修成本。动作设计有几个经验值很值得记：关节角速度不要拉满，给控制器留出调节余量；姿态变化幅度单帧不要太大，分多帧渐变；关键帧之间做插值平滑，而不是直接跳变。这些不是台面上的技术，是摔过几次之后换来的。
3.3 步态参数调节的玄学与科学
如果你要调步态参数，比如步频、步幅、抬脚高度、摆腿周期，建议一次只改一个参数，每次改动幅度控制在10%以内，然后放到仿真里验证，再上真机。人形机器人的步态系统是一个典型的多参数耦合系统，你改了步幅，可能重心高度就需要配合调整，抬脚高度变化又会影响到地面接触稳定性。这些参数之间有隐性关联，官方文档给出的只是默认值，不代表是最优值。
调步态的时候特别要注意“贴地保护”这个概念。人形机器人行走时如果抬脚过高，会显得机械且不稳；抬脚过低，则可能在摆动相绊到地面。关键是让踝关节在触地前有一个平滑的阻尼过渡，而不是硬踩。我调出来的经验是：偏稳定的参数组合往往不是看起来最灵活的，但长时间运行下来它的鲁棒性是最好的。稳定性优先，永远是步态调参的第一原则。
3.4 力控与外部扰动：从“自己站”到“扛住事”
G1的二次开发不可能永远在理想环境下跑。我见过很多项目卡在同一个环节：机器人在平地走得好好的，一遇到轻微外力推搡就站不稳了。这不仅要靠原厂的姿态控制器，也需要你在外部反馈上做文章。
一种常见思路是利用臂关节内置的电流数据估算外力，把估算出的外力作为扰动项补偿到姿态控制里。另一种思路是做柔顺控制，让机器人在受到外力时不是硬扛，而是顺着力的方向做小范围让步，等外力消失后自动回到目标姿态。这里最关键的是传感器数据的信任度：电流信号有噪声，IMU加速度计受震动干扰大，多源数据的融合时机决定控制的成败。我的建议是从小增益开始调，逐步加大反馈力度，直到机器人对外力做出适度响应而不产生自激震荡。
4. 感知与上层应用：把G1变成一个具身智能体
4.1 视觉数据流：从图像到决策
G1的头部通常配备了深度相机或可见光相机，这些视觉信息是上层应用的入口。视觉二次开发的链路基本是：采集原始图像流，做预处理，通过目标识别或语义分割得到感知结果，再把结果映射为机器人的动作决策指令。
我建议你第一步先建立稳定的图像采集通道，把深度图和RGB图像同步保存下来，做时间戳对齐，因为深度相机和RGB相机之间的帧率、延迟不一致，不对齐的话会直接影响后续避障和识别的准确性。第二步才是做推理，这里你可以先借用现成的模型，比如通用目标检测、人体姿态估计这些，验证整条链路跑通后再考虑自训练模型。一个常见的误区是直接在机器人端做全部推理，其实完全可以把图像流传到开发机上处理，再把决策指令传回机器人，这样能大大降低机载计算的负载，不过延迟会高一些，适合非实时性要求高的场景。
4.2 建图与自主导航：让机器人自己知道在哪
要让G1在室内环境自主移动，你需要一套完整的导航方案：先建图，再定位，最后规划路径并下发步态指令。建图一般用SLAM算法，G1的深度相机可以提供点云数据，配合轮式里程计或视觉里程计，能构建出环境的二维栅格地图或三维点云地图。
定位环节比较成熟的方案是AMCL这类粒子滤波方式，或者直接基于点云配准的定位方式。路径规划可以借用成熟框架，先做全局规划再叠加局部实时避障。这里我要提醒一个容易踩的坑：G1是双足机器人，通行能力和轮式机器人完全不同。台阶、坡道、窄缝都可能成为障碍，即使全局路径规划出来了，局部轨迹也要针对双足运动特性做额外的可通行性约束，否则规划出来的路径在图上看着没问题，实际走不过去。
4.3 语音与大模型对接：具身智能的最新玩法
G1二次开发目前最火的方向之一就是接入大模型，让机器人理解语音指令并转化为动作序列。整体架构一般分成四段：语音识别把用户说的话转成文字，大模型将文字指令解析为结构化的动作描述，动作映射模块把动作描述换成关节指令序列，最后由运动控制层执行。
这个环节的难点不在模型本身，而在“从语言到动作”的映射。比如用户说“往前走一步然后挥挥手”，你得把“走一步”和“挥挥手”分别映射为步态控制指令和关节控制指令，并且要保证两个动作串联起来不会互相干涉。我的做法是先用一套预设的动作模板库覆盖常见指令，大模型只负责从模板库里选择并组织执行顺序，等链路稳定后再尝试让模型直接输出参数化的动作指令。模版库加生成式模型结合，是目前实操中稳定性和灵活性平衡得最好的方式。
5. 实操走通第一个G1二次开发程序
5.1 开发环境搭建：别在这步省时间
我建议用Ubuntu 20.04或22.04系统，Python版本3.8以上，C++项目则用CMake管理。SDK一般同时提供Python和C++两种接口，Python适合快速原型验证，C++适合做实时控制或部署到生产环境。安装SDK的时候不要只跑pip install，要顺手把examples目录下的依赖也装上。
这步最容易被忽略的是环境变量配置。SDK可能需要你指定一些路径变量，如果你不配置，运行示例程序时会莫名奇妙地提示找不到模块或找不到资源。我的排查经验是：先运行SDK自带的示例，例如连接测试或状态读取例程，能跑通说明环境没问题，再开始写自己的代码，否则你就一直在自己的代码和环境问题之间找bug。
5.2 开发机和G1建立连接与心跳机制
连接过程看着简单，其实暗藏细节。用网线直连时，把开发机的网卡IP配置成和G1同一网段，注意不要和G1冲突。用无线方式时，确保在同一个局域网内。连接后SDK会维护一个心跳机制，客户端要定期向服务端发送心跳包，以维持连接的有效性和时效性。
我在这里要说一个很具体的经验：调试时把心跳超时阈值调大一点，先保证能稳定地收发数据，跑通主逻辑之后再把阈值调回正常。原因很简单，调试的时候你经常会在代码里打断点或临时sleep，如果心跳超时设得太短，调试过程会频繁触发断开保护，让你误以为是自己的业务逻辑写错了。等主逻辑稳定后，恢复正常的超时参数，再测试长时间运行的可靠性。
5.3 读取机器人状态：第一个正确性验证程序
连接成功后，第一步建议写一个简单的状态读取程序。读取内容至少包括：机器人当前模式、IMU的欧拉角或四元数、全部关节的角度和速度、电池电压、错误码。下面是一个极简的伪代码框架，用来表示一个状态读取主循环：
# 伪代码示例，实际接口名以你所用的SDK版本为准 client = create_robot_client() client.connect("192.168.123.xx") while running: state = client.get_motion_state() print(state.imu_euler, state.joint_positions[0:5]) time.sleep(0.02)跑通这段代码其实就说明你的通信链路、SDK安装、连接配置全部正确了。我建议把读取到的数据保存到文件里跑一段时间，检查数值有没有跳变、有没有不合理的突变。如果状态数据平滑且符合物理常识，说明设备端一切正常，你可以放心进行下一步。
5.4 下发一个简单关节动作：让G1“点头”
状态通了之后，就可以尝试做第一个主动控制动作了。最简单而且风险最低的是头部的俯仰关节——动作幅度小，不影响重心，就算出错最多是头动一下。流程这样走：先读取当前头部关节的角度作为起始点，设置一个目标角度，通常是通过设置位置加速度限制，然后逐帧下发指令，让它平滑转动。
# 伪代码示例：一个“点头”动作 start_angle = state.joint_positions[head_pitch_index] for t in range(50): target = start_angle - 0.2 * (t / 50) # 缓慢下点头 client.set_joint_position(head_pitch_index, target, speed_limit=0.5) time.sleep(0.01)这个循环看起来简单，但它把“读取状态-计算目标-下发指令”这个闭环逻辑完整地串起来了。然后你按同样的逻辑，把目标角度改成抬起再回来，就能做出一个完整的点头动作。把这个基础能力理解透，后面的前进后退、蹲起、挥手，本质上都只是把目标关节和目标轨迹换了一下而已。
5.5 一个完整Demo：走三步并挥手
当你对单关节控制熟练以后，可以尝试做一个组合动作。我的建议是先写一个按序列执行的指令协调器，在这个协调器里维护一个动作队列，按顺序依次执行，每个动作执行前先检查机器人状态是否安全，执行完后等稳定了再进入下一个动作。
以“走三步然后挥手”为例，你只需要把三个子动作按顺序编排：先调用步态接口，控制前进三步；等机器人完全停下来，确认姿态稳定；再执行手臂关节的挥动动作。如果这里发现动作衔接不稳，问题往往不是动作本身，而是前一个动作结束后机器人尚未进入稳定状态就开始下一个动作了。在动作之间加延时或者加姿态稳定判定，通常能解决大部分衔接问题。这就是为什么说二次开发的本质是“编排”，而不是“发明”。
6. 常见问题排查手册：我踩过的坑都在这里
| 现象 | 可能原因 | 排查方法 |
|---|---|---|
| 连接不上机器人 | IP不在同一网段，或防火墙拦截 | 首先ping机器人端，看能不能通，再检查防火墙放行规则 |
| 状态数据全部为零或不变 | 客户端没有收到实际数据，可能是连接未完全建立 | 检查SDK内部日志，确认握手成功，查看服务端状态码 |
| 关节指令下发无响应 | 当前机器人处于保护状态或急停触发 | 确认状态机模式和错误码；如果急停触发，需要按指示解除急停 |
| 动作执行时机器人抖动 | 指令频率过高或单帧目标角度变化过大 | 降低下发频率，细化插值步长，增加速度限制 |
| 开发机程序崩溃 | 状态回调耗时过长阻塞主线程 | 数据回调里只做取值不做计算，把处理逻辑放到主线程 |
| 长时间的延迟变大 | 网络丢包重传或缓冲区堆积 | 查看SDK是否报告丢包；增加丢包补偿逻辑，不要盲目调低超时 |
这几类问题里，有三条最容易反复折磨人：一是连接不上但怎么查都找不出问题，最后发现是网线接触不良，这种物理层的坑最无语；二是机器人被人从背后轻轻推了一下，立刻触发摔倒保护，然后你写的所有逻辑全部暂停，这是好事，说明保护机制在工作，但你需要在应用层做好保护触发后的恢复流程；三是SDK版本与固件不匹配，导致某个接口行为异常，查了一个晚上最后发现是版本问题。
还有一个小技巧：机器人的日志信息一定要全量保存，不要只看程序输出。SDK一般会输出详细日志，包括警告、错误和性能统计，真正常出问题的是warning级别的信息，它们会在你的主逻辑出错前很久就给出预示。养成看日志的习惯，能帮你省出大量的排查时间。
另外一个经常被忽略的点是：温度对关节特性的影响。机器人长时间运行后，关节电机发热会导致响应和默认参数有偏差，所以长时间稳定性测试要在合理的温度区间内进行，不要在大冬天刚开机就猛跑高强度动作，冷机和热机的参数特性确实有差异，这一点和人很类似，先热身再干重活。
7. 资料路线图：我现在建议你怎么看资料、怎么查资料
7.1 资料分类与优先级
市面上关于G1二次开发的资料主要分为几类：官方产品手册和开发者文档、官方提供的SDK包与示例代码、ROS2相关的接口包、开源社区里的仿真模型和工具链、第三方博客与视频教程、零散的论坛讨论。这些资料的权威性和时效性完全不同，我给它们排个优先级：
首先是官方开发者文档和SDK包，这是唯一真正权威的信息来源。其次是官方示例代码，它是你写自己代码之前最好的参考模板，优先级非常高。然后是仿真环境相关的模型和工具链，比如通用机器人仿真平台里有人上传过G1的URDF描述文件或仿真模型，这在做动作预演时价值很高。再往下才是社区博客和视频教程，这些内容可以看，但一定要对照官方文档校正，因为博主可能用的是旧版本接口。最后是论坛和聊天记录类的零散讨论，只用来排查特定问题时参考。
7.2 一个实用动作：建立自己的离线资料库
网上的资料会失效，会更新，会和你的版本不匹配。我强烈建议你拿到一份资料之后，立刻同步下载保存到本地，按这样分类存放：官方文档按版本号分目录，SDK包按版本号分目录，示例代码注明对应SDK版本号和测试日期，仿真模型单独放一个目录，博客教程只要截图关键页面并存PDF。这个习惯在项目进行到后期时极其有用，你会感谢自己当初做了这个整理。
同时建议你在自己的项目仓库里维护一个“接口变更记录”，每次升级SDK之后，把更新内容、影响的接口、需要改的代码位置记录下来。这个文档刚开始维护的时候会觉得多此一举，等项目做了几个月再回来看，它就是整个团队最重要的资产——比起重新看一遍SDK源码，这份记录能让你在版本变化时一分钟定位到问题。
7.3 个人体会：二次开发的价值在于“编排”
把整个流程走下来之后，我最深的感受是：G1的二次开发，真正让你发挥创造力的地方不是发明新的算法，而是把已有的稳定模块编排成新的能力。官方解决了“怎么稳定走路”这个最难的工程问题，你的工作是回答“让它走去哪、怎么停下、怎么与人互动”。大量的项目失败不是因为技术不够深，而是因为对现有平台能力的边界理解不到位，把一个本应由原厂控制器负责的底层问题，强行扛到了应用层来解。
所以我的最后一个建议是：拿到G1，先花一周时间只做一件事——把官方示例代码全部跑一遍。每个示例对应一个能力边界，跑完一遍之后你会对“这台机器人能做什么、不能做什么”形成一个非常清晰的地图。有了这张地图，后面所有的二次开发都只是在这个地图上加新路线而已。
最后再分享一个小技巧：调试的时候永远在代码里留一个远程急停的“逃生舱”，可以是手机上连着的一个独立控制端，也可以是键盘上绑定的一个快捷键。人形机器人调试的不确定性远高于普通机械臂，看起来再稳的动作也有可能在某个电磁干扰、地面打滑的瞬间出现问题。多一个随时切断指令的手段，不是怂，而是长期做机器人调试的人骨子里的习惯。
