宇树G1机器人远程开发环境搭建：VSCode+SSH配置指南

1. 宇树G1机器人远程开发环境搭建的整体思路宇树G1作为一台四足人形机器人平台出厂时搭载的是基于Linux的实时操作系统开发者拿到手之后第一件头疼的事往往不是运动控制算法而是怎么把代码从自己的笔记本上送进机器人本体。我前后折腾过三台G1从最早的串口登录到后来的VSCode远程开发中间踩的坑足够写一本小册子。这篇内容就是把我自己走过的弯路整理出来让后来的人少花几个通宵。核心目标很明确让开发者坐在自己的主力机上用VSCode直接编辑G1上的代码、运行调试、查看日志就像在本地开发一样顺手。要做到这一点需要打通三个环节——网络连通、SSH服务可用、VSCode远程插件配置正确。这三个环节任何一个出问题都会让你卡在“连不上”的状态里反复怀疑人生。适合谁来参考如果你刚拿到G1或者之前只用过图形界面工具、对Linux命令行不太熟这篇内容会非常对口。即使你已经有Linux基础但没接触过机器人本体的网络配置里面关于静态IP规划、SSH密钥管理的部分也能帮你省下不少排查时间。整个方案的选型逻辑是这样的G1本体通常通过网线或WiFi接入局域网开发者主机和G1需要在同一网段或者路由可达。SSH作为远程登录的标准协议几乎所有的Linux发行版都原生支持不需要额外装什么重型工具。VSCode的Remote-SSH插件则把远程开发体验拉到了接近本地的水平文件树、终端、调试器全部打通。这套组合的优点是轻量、稳定、可复现不依赖任何特定厂商的IDE。注意G1出厂系统可能已经开启了SSH服务也可能没有。不同批次的固件版本差异较大拿到手第一件事是确认SSH服务状态而不是盲目尝试连接。2. 网络连通IP配置与网段规划2.1 为什么IP配置是第一个拦路虎G1本体没有显示器你没法直接接上键盘鼠标去点图形界面改网络。所有网络配置要么通过串口终端完成要么通过已有的网络连接远程操作。如果你拿到的是全新机器大概率需要用串口线先登录进去把网络配通后续才能走SSH。我见过太多人卡在这一步用网线把G1和笔记本直连然后发现ping不通以为是SSH的问题其实是两边根本不在同一个网段。G1默认可能配的是192.168.123.xxx这类内部网段而你的笔记本网口可能是169.254开头的自动分配地址两者压根没法通信。2.2 静态IP vs 动态IP的取舍在机器人开发场景下我强烈建议给G1配静态IP。原因很简单你每次重启机器人如果IP变了VSCode的远程连接配置就得跟着改脚本里的地址也得改烦不胜烦。静态IP让G1在局域网里有一个固定门牌号所有工具链都指向这个地址省心。具体怎么配取决于G1接入网络的方式有线直连笔记本网口和G1网口用网线直连两边都配静态IP比如笔记本配192.168.1.100G1配192.168.1.101子网掩码255.255.255.0。通过路由器接入G1和笔记本都连到同一个路由器的LAN口或WiFi在路由器后台给G1的MAC地址绑定一个固定IP或者在G1系统内配静态IP。通过交换机接入多台设备组网时常见配置逻辑和路由器类似注意网段统一。2.3 串口登录与网络配置实操假设你手头有一根USB转串口线G1本体上通常有一个调试串口接口。连接步骤如下确认串口线驱动已安装Windows下会在设备管理器里看到COM口Linux/macOS下是/dev/ttyUSB0或/dev/tty.usbserial-xxx。用串口终端工具连接波特率一般是115200。Windows下可以用Putty或MobaXtermLinux/macOS下直接用screen或minicom。登录G1系统用户名和密码参考出厂文档常见的是unitree/unitree或者root/root。进入网络配置编辑/etc/netplan/下的yaml文件Ubuntu系或/etc/sysconfig/network-scripts/下的ifcfg文件CentOS系或者用nmcli命令。以netplan为例配置文件大概长这样network: version: 2 ethernets: eth0: dhcp4: no addresses: - 192.168.1.101/24 gateway4: 192.168.1.1 nameservers: addresses: [8.8.8.8, 114.114.114.114]改完之后执行sudo netplan apply然后用ip addr确认地址生效。提示如果G1系统是OpenEuler或麒麟这类国产发行版网络配置文件的路径和语法会有所不同。OpenEuler用nmcli或者直接改/etc/sysconfig/network-scripts/ifcfg-eth0麒麟V10则可能用图形化的网络管理器或者类似的ifcfg体系。核心逻辑一样指定静态地址、掩码、网关。2.4 验证连通性的正确姿势配完IP之后先在G1上ping网关再ping你的笔记本。然后在笔记本上ping G1。如果ping不通按以下顺序排查排查项检查方法常见问题物理连接网口指示灯是否亮网线坏了、接口松动IP网段两边IP和掩码是否匹配一个192.168.1.x一个192.168.0.x防火墙G1上iptables或firewalld是否放行默认规则拦截了ICMP路由路由表是否有对应条目网关配错网卡状态ip link show查看UP/DOWN网卡未启用我遇到过最诡异的一次是网线水晶头压得不好时通时断ping包丢一半。换根线立刻解决。所以排查时先怀疑物理层别一上来就改配置。3. SSH服务配置与密钥管理3.1 确认SSH服务状态网络通了之后下一步是确认G1上的SSH服务在跑。在G1的串口终端里执行systemctl status sshd如果显示active (running)说明服务已启动。如果没有执行sudo systemctl start sshd并设置开机自启sudo systemctl enable sshd。有些精简系统可能没装SSH服务端需要手动安装。Ubuntu/Debian系用sudo apt install openssh-serverCentOS/Fedora系用sudo yum install openssh-serverOpenEuler用sudo dnf install openssh-server。3.2 密码登录 vs 密钥登录密码登录最简单但每次连接都要输密码而且VSCode Remote-SSH在某些配置下对密码交互支持不够流畅。密钥登录一次配置永久免密安全性也更高。生成密钥对的命令ssh-keygen -t ed25519 -C g1-dev一路回车即可默认会在~/.ssh/下生成id_ed25519和id_ed25519.pub两个文件。然后把公钥推送到G1ssh-copy-id -i ~/.ssh/id_ed25519.pub unitree192.168.1.101如果ssh-copy-id不可用手动把公钥内容追加到G1的~/.ssh/authorized_keys文件里也行。3.3 SSH配置文件简化连接每次敲ssh unitree192.168.1.101太麻烦可以在本地~/.ssh/config里加一段Host g1 HostName 192.168.1.101 User unitree IdentityFile ~/.ssh/id_ed25519 Port 22之后直接ssh g1就能登录。VSCode Remote-SSH也会读取这个配置连接时直接选g1这个Host就行。注意Windows下如果遇到“bad owner or permissions on C:\Users\xxx/.ssh/config”这个报错是因为Windows对文件权限管得比较严。解决方法是在文件属性里把继承权限关掉只保留当前用户的所有权或者用管理员权限的PowerShell执行icacls命令修复权限。3.4 常见SSH连接故障速查报错信息原因解决方法Connection refusedSSH服务没启动或端口不对检查sshd状态和端口Permission denied用户名密码错误或密钥不对确认用户名重新推送公钥Host key verification failed主机密钥变了删除~/.ssh/known_hosts里对应条目Connection timed out网络不通或防火墙拦截先ping通再查防火墙No route to host路由问题检查网关和路由表我印象最深的一次是G1系统升级后SSH主机密钥重新生成了本地known_hosts里还是旧密钥连接时一直报Host key verification failed。删掉旧条目后恢复正常。这种问题在机器人反复刷机时特别常见。4. VSCode远程开发环境搭建4.1 安装VSCode与Remote-SSH插件VSCode从官网下载对应平台的安装包Windows下双击exe一路下一步macOS下拖进ApplicationsLinux下用deb或rpm包安装。安装完成后打开在扩展面板搜索“Remote - SSH”认准Microsoft官方发布的那个点击安装。如果你习惯中文界面可以再装一个中文语言包插件在扩展面板搜索“Chinese”即可。不过我个人建议开发环境保持英文因为很多报错信息和文档都是英文的中文界面反而可能让你在搜索解决方案时对不上关键词。4.2 配置远程连接安装完Remote-SSH后左侧活动栏会出现一个远程资源管理器图标。点击进去选择“SSH Targets”然后点齿轮图标编辑配置文件把之前~/.ssh/config里的g1配置加进去。或者直接在VSCode命令面板里执行“Remote-SSH: Add New SSH Host”输入ssh g1选择配置文件位置。连接时VSCode会在G1上自动安装一个轻量级的vscode-server这个过程需要G1能访问外网下载组件。如果G1没有外网需要手动下载vscode-server的离线包传到G1上安装。离线安装的方法是在本地VSCode里执行“Remote-SSH: Install Server on Remote Host”或者根据VSCode输出的commit id去下载对应版本的server包。4.3 远程开发环境的核心配置连上之后你可以在G1上打开工作目录安装需要的插件。注意VSCode的插件分为本地插件和远程插件有些插件需要在远程端也安装一份。比如Python插件、C/C插件在连接远程时VSCode会提示你在远程端安装。对于G1的软件开发通常涉及C和Python两种语言。C插件提供代码补全、跳转、调试支持Python插件类似。如果G1上已经有编译好的SDK配置好include路径和库路径代码补全就能正常工作。在远程端的settings.json里可以配置一些常用项{ python.pythonPath: /usr/bin/python3, C_Cpp.default.includePath: [ /home/unitree/sdk/include, /usr/include ], terminal.integrated.shell.linux: /bin/bash }4.4 远程终端与调试VSCode连接远程后按Ctrl打开的终端就是G1上的shell可以直接执行命令。调试C代码时配置launch.json指向G1上的可执行文件VSCode会通过gdbserver在远程启动调试会话。Python调试更简单直接选远程解释器打断点就能调。我实际用下来VSCode远程开发最爽的一点是文件保存即同步不需要scp来回传。而且终端、编辑器、调试器在同一个窗口里切换成本极低。对于G1这种需要频繁改参数、看日志的场景效率提升非常明显。提示如果G1的CPU性能较弱vscode-server可能会占用不少资源。可以在设置里关掉一些不必要的功能比如文件监视的轮询频率调低或者只打开必要的插件。5. 实操中的典型问题与排查记录5.1 网络配置类问题问题一G1重启后IP变了。这是DHCP动态分配导致的。解决方法是在G1上配静态IP或者在路由器上做MAC绑定。如果G1系统每次重启网络配置被重置检查是不是有cloud-init之类的服务在覆盖网络配置可以禁用或者修改其配置。问题二笔记本同时连WiFi和网线时路由冲突。笔记本用WiFi上网网线连G1结果发现ping不通G1。这是因为系统路由表里默认路由走WiFi去往G1网段的包可能走了错误的接口。解决方法是给网线接口配一个和G1同网段的IP并且不加默认网关让系统自动生成直连路由。问题三虚拟机里配静态IP连G1。如果你在VMware或PVE里跑一个Linux虚拟机做开发机网络模式选NAT时虚拟机在独立网段需要做端口转发或者改用桥接模式。桥接模式下虚拟机和G1在同一网段配置静态IP即可互通。PVE9下配置网络自动获取IP或者静态IP核心是改/etc/network/interfaces或者用ifupdown2管理。5.2 SSH类问题问题一SSH连接慢要等好几秒才出密码提示。这通常是SSH服务端在做反向DNS解析超时导致的。解决方法是在G1的/etc/ssh/sshd_config里设置UseDNS no然后重启sshd。问题二密钥登录不生效还是提示输密码。检查G1上~/.ssh目录权限是否为700authorized_keys是否为600home目录权限是否过于开放。SSH对权限要求很严格权限不对会直接忽略密钥。问题三批量登录多台G1时管理混乱。如果实验室有多台G1可以在~/.ssh/config里给每台配一个Host别名用不同的IP和密钥。批量执行命令可以用pssh或者ansible但注意机器人系统资源有限别跑太重的并发任务。5.3 VSCode远程类问题问题一vscode-server安装失败。最常见的原因是G1无法访问外网。解决方法是手动下载server包放到G1的~/.vscode-server/bin/目录下解压。commit id可以在VSCode的“关于”里看到。问题二远程连接频繁断开。检查网络稳定性如果是WiFi连接信号弱会导致断连。另外VSCode的Remote-SSH有心跳机制可以在settings里调整remote.SSH.connectTimeout参数。问题三远程端插件不工作。确认插件是否安装在远程端。在扩展面板里已安装的插件会标注“Install in SSH: g1”或者“Install Locally”。点错位置会导致插件在远程不可用。问题类型典型表现快速定位方法网络不通ping失败检查IP、网线、防火墙SSH拒绝Connection refused查sshd状态和端口认证失败Permission denied查用户名、密钥、权限VSCode连不上卡在Setting up查vscode-server日志远程插件失效功能不可用确认插件安装位置5.4 我踩过的最深的坑有一次给G1刷了新固件网络配置全部重置串口登录后发现SSH服务默认没启动。更麻烦的是新固件的包管理源指向了一个内网地址G1没法直接装openssh-server。最后是从另一台同型号G1上把openssh-server的deb包拷过来用dpkg手动安装才解决。这件事教会我拿到新机器或者刷完固件第一件事是确认SSH服务可用并且把常用的离线安装包备一份在U盘里。另一个坑是关于VSCode的。早期版本的Remote-SSH在连接时会尝试在远程端下载最新版server如果G1的glibc版本太老server跑不起来。报错信息很隐晦只说“Server installation failed”。后来在VSCode设置里指定了server的下载版本或者手动部署匹配的server包才解决。所以如果你的G1系统比较老注意VSCode版本和server版本的兼容性。6. 效率提升脚本化与自动化配置6.1 一键网络配置脚本如果你经常需要给G1重配网络可以写一个脚本放在U盘里插上执行就完事。脚本内容大致如下#!/bin/bash # configure_network.sh IFACEeth0 IP192.168.1.101 MASK24 GW192.168.1.1 cat /etc/netplan/01-g1-network.yaml EOF network: version: 2 ethernets: $IFACE: dhcp4: no addresses: [$IP/$MASK] gateway4: $GW EOF netplan apply echo Network configured: $IP/$MASK这个脚本假设系统用netplan。如果是其他发行版把对应的配置命令替换进去即可。核心思路是把重复的配置工作固化下来减少手误。6.2 SSH密钥批量分发多台G1的场景下手动ssh-copy-id太慢。可以写一个循环#!/bin/bash for ip in 192.168.1.101 192.168.1.102 192.168.1.103; do sshpass -p unitree ssh-copy-id -i ~/.ssh/id_ed25519.pub unitree$ip donesshpass需要提前安装用密码做初始认证推送完公钥后就可以免密了。注意这只是初始配置的便利手段日常使用还是走密钥认证。6.3 VSCode工作区配置固化把G1项目的.vscode文件夹配置好提交到代码仓库里团队其他人拉下来就能直接用。里面包含settings.json、launch.json、tasks.json分别对应编辑器设置、调试配置、构建任务。这样新成员入职装好VSCode和Remote-SSH插件连上G1打开项目文件夹环境就齐了。tasks.json里可以定义编译命令比如{ version: 2.0.0, tasks: [ { label: build, type: shell, command: mkdir -p build cd build cmake .. make -j4, group: { kind: build, isDefault: true } } ] }按CtrlShiftB就能触发编译输出显示在VSCode的终端里报错可以点击跳转到源码位置。6.4 日志查看与远程监控G1运行时的日志通常写在/var/log/或者程序自己的日志目录下。可以在VSCode里直接打开日志文件配合插件的语法高亮和搜索功能比在终端里tail方便得多。如果需要实时监控VSCode终端里跑tail -f即可。对于更复杂的监控需求可以在G1上跑一个轻量的Web服务把关键状态暴露出来然后在本地浏览器查看。但这属于额外扩展不是必须的。核心还是把SSH和VSCode这条链路做稳定。7. 一些个人体会这套环境搭好之后我基本告别了在G1上直接敲命令的日子。所有开发工作都在笔记本上完成G1只负责运行。这种分工让效率提升非常明显尤其是调试运动控制算法时改一行参数、重新编译、运行看效果整个循环可以在几十秒内完成。如果让我给刚上手的人一条建议那就是先把网络和SSH搞通别急着装VSCode。底层不通上层工具再花哨也没用。网络配置阶段多花十分钟确认IP、网关、防火墙后面能省下几个小时的无谓排查。另外G1的系统盘空间通常不大vscode-server和编译中间文件会占不少地方。定期清理build目录和~/.vscode-server里的旧版本避免磁盘满了导致各种奇怪问题。我就遇到过磁盘满导致SSH登录后无法创建临时文件报错信息完全看不出是磁盘问题查了半天才定位到。最后分享一个小技巧在G1的~/.bashrc里加一行export PS1\u\h:\w\$ 让终端提示符显示主机名和当前路径多台G1切换时不容易搞混。这个细节虽小但在实验室多机器人环境下很实用。