从零把电脑和机器狗连接起来，写第一段代码并跑通。本章带你从头配置好一套可直接在机器狗上开发的环境（SSH + VS Code / Qoder + 文件传输 + 源码部署），无论你是想改现有功能还是从零做项目，都从这里开始。
本章包含：
小节 | 内容 | 难度 |
|---|---|---|
1.1 SSH 连接 | 用一条命令登录机器狗，打开发联环境的第一扇门 | ★☆☆ |
1.2 VS Code 远程开发 | 在电脑上用 VS Code 连接机器狗，像本地一样编辑/调试远程代码（推荐） | ★☆☆ |
1.3 用 Qoder 做 vibe coding | 用自然语言写代码，AI 辅助生成并运行（推荐） | ★★☆ |
1.4 文件传输 | 通过 scp / rsync 在电脑和机器狗间传文件 | ★☆☆ |
1.5 从源码部署（可选） | 从官方仓库编译安装 Luwu-OS（进阶） | ★★★ |
🧭 阅读路径：第一次上手先走 1.1 → 1.2 或 1.3；只想从源码装系统、不想用现成镜像的可直接看 1.5。
前置条件：
一台已刷好 Luwu-OS 镜像并开机的机器狗（见使用篇「开箱与基础操作」）；
机器狗和电脑连接在同一 WiFi 网络下，并知道机器狗 IP；
一台能跑 VS Code / Qoder 的开发电脑，建议 8GB 以上内存。
1.1 SSH 连接
确保机器狗和电脑连接在同一 WiFi 网络下（查看机器狗 IP：进入「图传模式」屏幕会显示 IP，或通过路由器查看）。
镜像版本说明：老版本镜像默认用户名密码均为
pi；新版本 Luwu-OS 镜像默认用户名密码均为luwu。请根据你的镜像版本使用对应的账号登录。系统信息：Luwu-OS 运行于 Raspberry Pi CM4/CM5（aarch64，Debian 13 trixie），所有系统代码位于
/opt/luwu-os/，SSH 默认已启用。
# 老镜像（用户名密码均为 pi）
ssh pi@<机器狗IP地址>
# 新 Luwu-OS 镜像（用户名密码均为 luwu）
ssh luwu@<机器狗IP地址>
1.2 VS Code 远程开发（推荐）
VS Code 配合 Remote-SSH 插件是在机器狗上进行二次开发的最佳方式。你可以在电脑上编写代码，直接在机器狗上运行和调试，无需反复传输文件。
1.2.1 安装配置
在电脑上安装 VS Code
点击左侧扩展图标（或按
Ctrl+Shift+X），搜索 Remote - SSH 并安装安装完成后按
F1打开命令面板，选择Remote-SSH: Connect to Host...输入
pi@<IP>或luwu@<IP>，回车在弹出的输入框中输入密码，等待连接
连接成功后点击「打开文件夹」，选择
/opt/luwu-os/即可浏览和编辑全部代码
💡 首次连接时 VS Code 会自动在机器狗上安装 VS Code Server，请耐心等待 1~2 分钟。
1.2.2 常用操作
操作 | 方式 |
|---|---|
打开远程文件夹 |
|
新建终端 |
|
上传文件 | 直接拖拽文件到 VS Code 左侧文件浏览器 |
断开远程连接 |
|
再次连接 | 左侧「远程资源管理器」→ 点击历史记录中的主机 |
1.3 用 Qoder 做 vibe coding 远程开发（推荐）
除了手动写代码，你也可以用 Qoder（智能体式 AI 编程平台）来 vibe coding ——用自然语言描述你想要的功能，由 AI 辅助生成、补全并运行代码。它同样支持通过 SSH 连接远程开发机，非常适合在机器狗上快速做二次开发、调试验证。
完整的 vibe coding 流程如下（本次教程会逐节展开）：
隐私提示：连接远程开发、AI 对话与代码生成时，Qoder 会携带本地上下文；在对外发布的文档 / 演示截图中，请避免出现真实 IP 地址、SSH 密码、API Key、设备序列号等敏感信息（可先用通用占位符或做脱敏处理）。
1.3.1 连接你的开发机
首次使用 Qoder，先在本地打开一个空白窗口，通过 SSH 远程开发 入口连接到机器狗（就是把你本地 IDE 的“打开远程主机”功能挪到了 Qoder 里）。连接成功后，左下角状态栏会显示当前远程主机（图中已做隐私脱敏，示例用 <机器狗IP> 占位）：
连接方式要点：
在 Qoder 的「远程开发 / 连接主机」入口填写
luwu@<机器狗IP>，选择/opt/luwu-os/作为工作目录；连接成功后，顶部标题栏会显示
luwu-os [SSH: <机器狗IP>]，左侧「资源管理器」顶部会列出该远程主机，可直接浏览、新建、编辑、保存远程文件；连接后左下角状态栏变为绿色
SSH字样，表示已固定在远程；底部「终端」标签页可直接执行
ssh、scp、rsync同步命令，或sudo bash configs/install.sh部署脚本。
1.3.2 浏览远程项目
连接成功后，左侧资源管理器会展示机器狗上的远程项目结构（见下图，已连到 luwu-os [SSH: <机器狗IP>]）。Luwu-OS 的全部代码位于 /opt/luwu-os/，文件树里最重要的就是这些目录：
常见子目录（也是二次开发最常改动的目录）：
apps/— 各应用源码（如apps/ai_chat_pro/、apps/voice_chat/、apps/ai/（旧版开发版）、apps/rc_mode/、apps/launcher/）；libs/— 底层运动、视觉等库（xgolib就在这里）；configs/— 系统配置与install.sh部署脚本；model/— 视觉识别用的模型文件；xgoBlocklyProjects/— 图形化编程 / AI 生成脚本的运行目录（上文的前进吧.py就会放在这里）。
左侧列表里
main.py等文件带高亮，说明当前已在编辑器打开；双击任意文件即可查看、编辑。
1.3.3 用自然语言写代码（vibe coding）
选好目标文件后（本例选中 apps/ai_chat_pro/main.py 作为上下文），在右侧 AI 对话面板直接用中文一句话描述你的需求即可，比如在对话框输入：
“写一个机器狗前进然后右转的程序”
AI 会先自动探索项目里的运动控制库，再结合上下文给出实现建议。下图是完整的对话过程：
从上图可以看到 AI 的典型回应链路：
探索源码：AI 先读取仓库，显示“已探索 4 源码”，并定位到运动控制库
xgolib（在libs/下），用于了解现有接口；总结能力：AI 把你问的需求映射到它能调用的能力，例如“我掌握了
xgolib提供了forward(前进)、turn(右转)、move_x(后退)…下面来写一个前进程序”；生成代码：AI 直接新建一个 Python 文件（本例为
前进吧.py），并给出完整实现（底部可见from xgolib import XGO、import time、# 创建机器人实例（自动检测机型与串口）、dog = XGO()等）。
💡 既然你选中的是某个具体文件，可以在需求里用
@显式引用它（如@main.py），AI 会优先读取该文件，生成的改动会更贴合现有代码。
1.3.4 审批并采纳建议
AI 给出方案后，编辑器会以 diff（对比） 形式高亮将要改动的地方：红色为删除、绿色为新增。同时 Ai 会在右侧给出逐项修改建议，供你决定是否采纳。下图是 前进吧.py 的 diff 与审批卡片：
从上图可以看到 AI 生成了具体的动作参数（编辑器左侧代码区）：
TURN_SEC = 1.5 # 转向耗时（秒）
PAUSE_SEC = 0.3 # 停顿与转向之间的停顿（秒）
dog = XGO() # 创建机器人实例（自动检测机型与串口）
dog.forward(18) # 前进：速度 18 前进 2 秒
time.sleep(2)
dog.move_x(VX_SPEED, 1) # 第 1 步：前进
同时，AI 还补充了运行时可能遇到的问题与调参建议（右侧绿色文本），例如：
前进距离不够 → 增大
FORWARD_SEC（步长约 0.2~0.3 秒）或增大VX_SPEED；转向不足 90° → 增大
TURN_SEC（步长约 0.2 秒）或增大TURN_SPEED；动作衔接不流畅 → 调整
PAUSE_SEC（0.1~0.5 秒）。
这些参数会受地面摩擦力、电池电量、机器狗机型等因素影响，所以建议先小步运行再现场微调。
确认无误后，在右下角的审批卡片中选择 采纳（Accept） 应用更改，或 拒绝（Discard） 放弃（可以看到本例显示“1 个文件已更改 39→7”，即新增/删除行数对比）。采纳后 AI 会继续迭代或生成后续代码。
1.3.5 生成并运行
采纳代码后，就可以在机器狗上实际运行、验证效果。AI 生成的文件通常会放到独立的运行目录（本例为 /opt/luwu-os/xgoBlocklyProjects/前进吧.py），直接在底部终端运行它：
cd /opt/luwu-os/xgoBlocklyProjects
python3 前进吧.py
运行后，终端会打印程序输出（前进、右转等，见下图底部主面板）；如果机器狗没有按预期动作，再回到 AI 对话里把实际现象告诉它，让 AI 根据上一步的调参建议继续修改参数即可。
在机器狗上运行调试时，也可以直接在当前终端逐条执行命令并观察输出（图中路径、IP、用户名等敏感信息已做脱敏）：
💡 在机器狗上调试单个应用时，可用 run.fifo 让 launcher 走完整启动流程（自动应用主题 / 按键路由），详见第二章 与 第三章 3.4。
1.4 文件传输
除了 VS Code 拖拽上传，也可以使用命令行传输文件：
# 上传文件到机器狗
scp /path/to/local/file pi@<IP>:/path/to/remote/
scp -r /path/to/local/dir pi@<IP>:/path/to/remote/
# 下载文件到电脑
scp pi@<IP>:/path/to/remote/file /path/to/local/
# 增量同步
rsync -avz /path/to/local/dir/ pi@<IP>:/path/to/remote/dir/
1.5 从源码部署（可选）
推荐：多数用户建议先用官方 Luwu-Imager 烧录预构建镜像，它会自动完成系统安装、SD 卡分区与初始配置。以下源码部署适合需要定制系统源码的场景。
Windows：LuwuImager-Setup-latest.exe
拿到的是项目源码而不是烧录好的镜像时，可克隆官方仓库后执行一键部署脚本：
git clone https://github.com/LuwuDynamics/luwu_os.git /opt/luwu-os
cd /opt/luwu-os
sudo bash configs/install.sh
sudo reboot
⚠️
install.sh仍在积极开发中，可能尚未覆盖所有硬件配置；如需完整安装体验，建议优先使用上方的 Luwu-Imager 方式。环境要求：Raspberry Pi CM4 或 CM5 及兼容底板；SPI LCD（ST7789V）通过 SPI0 连接；Debian 系 Linux。技术栈版本：Python 3.11+、C++17、Qt 5.15（Launcher 以 EGLFS/LinuxFB 渲染）、OnnxRuntime、Picamera2。
install.sh 完成的主要工作（共 14 步）：
步骤 | 内容 |
|---|---|
1 | 部署项目到 |
2 | 安装系统依赖（apt）： |
3 | 安装 pip 依赖： |
4 | 部署 |
5 | 用 |
6 | 部署 udev 规则（ |
7 | 部署 ALSA 音频配置（ |
8 | 启用 systemd 服务： |
9 | 启用 CM4 硬件自动识别： |
10 | 设置开机画面脚本权限 |
11 | 文件系统加固（ |
12 | 持久化系统日志（journald，上限 50MB） |
13 | 蓝牙开机自动启用（BlueZ |
14 | 欠压+电池联合监控（ |
requirements.txt 中列出的 pip 依赖（apt 中没有或需要更新版本的包）：
pyzbar>=0.1 # 扫码配网（底层依赖 libzbar0t64 需 apt 安装）
paho-mqtt>=2.0 # MQTT（群组表演）
xgolib>=1.1 # 机器人运动库
xgoedu-luwuos>=2.0 # 图形化编程教育库
xgo-blockly-luwuos>=1.0 # Blockly 图形化编程服务