导航使机器人能够将感知和运动转化为有目的的自主行为。与产生稳定运动的移动能力不同，导航必须用于持续定位机器人、解读不断变化的环境、选择路线并避开障碍物，以安全到达目标。
将这一能力迁移到新的机器人或场景可能需要新的数据、仿真资产、机器人接口、训练、诊断和评估。为每个机器人-场景组合重复这项工作成本高昂且难以复现。
由智能体驱动的工作流减轻了这一负担。开发者定义机器人、场景来源和导航目标。编码智能体使用仓库技能来验证依赖项、准备资产、运行冒烟测试、启动训练、诊断故障并比较检查点。人工审批关卡控制场景验收、单环境冒烟测试和检查点晋升。
以 Spot 作为参考机器人，本教程文章将智能体驱动的 COMPASS 工作流应用于内置场景和 SAGE-10K 场景，同时展示 NVIDIA Omniverse NuRec 如何支持捕获的环境。它遵循策略工作流，涵盖冒烟测试、残差训练、检查点评估和运行时集成，包括可选的里程计。
什么是 COMPASS？
COMPASS（通过残差强化学习和技能合成的跨具身移动策略）是一个统一框架，利用来自单一具身的专家演示实现可扩展的跨具身移动。它复用预训练的 NVIDIA X-Mobility 策略中的导航行为。它训练一个残差专家——一种强化学习（RL）策略，针对选定的机器人和环境修正基础动作，而不是从头重新学习导航。来自多个专家的数据随后可以蒸馏为共享的跨具身策略。
本智能体驱动工作流所训练和评估的 COMPASS 策略架构如图 1 所示。
图 1. COMPASS 将 X-Mobility 基础策略适配为具身专家，并将其蒸馏为跨具身策略
COMPASS 将此开发工作流打包为仓库技能。本教程在开发过程中使用 Codex。训练好的策略和机器人控制器在运行时执行导航，无需编码智能体。
参考工作流概述
参考工作流使用 Boston Dynamics Spot 四足机器人。内置仓库是主要的可复现路径，SAGE-10K 将其扩展到生成的场景，NVIDIA Omniverse NuRec 为重建的目标环境提供可选路径。NVIDIA cuVSLAM 是一个 CUDA 加速的视觉里程计和同步定位与建图库，当机器人本身未提供兼容的里程计和变换时，可提供部署里程计。
对于其他环境，请使用仓库固定的 COMPASS 软件栈和以下硬件指南：
- 一台 Ubuntu 22.04 或 24.04 系统，至少 32 GB 内存，一块支持 RTX 的 NVIDIA GPU，至少 16 GB 显存，以及 Linux 驱动 580.95.05，这是针对 Isaac Sim 6.0 测试过的版本。Isaac Sim 6.0 的最低参考 GPU 是 GeForce RTX 4080。安装前请运行 Isaac Sim 兼容性检查器。 - Docker Engine 24 或更高版本，并安装 NVIDIA Container Toolkit。
- 一个 Hugging Face 账户和具有访问受限 nvidia/COMPASS 和 nvidia/X-Mobility Hugging Face 仓库权限的读取令牌。 - 经过测试的教程技术栈：NVIDIA Isaac Lab 3.0 与 NVIDIA Isaac Sim 6.0。
步骤 1：设置 COMPASS 智能体工作流
首先，准备好仓库，并在开始场景工作之前为编码智能体提供清晰的工作流契约。你将下载受限资产，使 COMPASS 技能可被 Codex 发现，运行技术栈检查，并在单环境审批关卡处停止。所有 $compass
块都是可在 COMPASS 仓库根目录的 Codex 聊天中复制的提示词，而非 shell 命令。在 Claude Code 中，使用 /compass
执行相同的工作流。
对于 Codex，首先在 .agents/skills
下公开仓库技能，然后使用 /skills
选择 COMPASS，或在提示词中提及 $compass
。Codex 支持符号链接的技能目录，因此当前仓库技能可以保留在其维护位置。对于 Claude Code，使用 /compass
调用相同的工作流。
mkdir -p .agents/skills
ln -s ../../.claude/skills/compass .agents/skills/compass
ln -s ../../.claude/skills/compass-doctor .agents/skills/compass-doctor
ln -s ../../.claude/skills/compass-newembodiment .agents/skills/compass-newembodiment
编码代理可以克隆、构建、下载非机密资产并验证技术栈。开发者必须在聊天之外接受受限仓库条款并输入 Hugging Face 令牌。代理绝不应请求、显示或在日志中存储该令牌。
安装 COMPASS 并下载资产
克隆 COMPASS 仓库，并使用仓库固定版本的容器按照 COMPASS 手册快速入门进行操作。在首次运行之前，接受对受限的 nvidia/COMPASS 和 nvidia/X-Mobility Hugging Face 仓库的访问权限，创建一个 Hugging Face 读取令牌，并确认它可以读取你账户可访问的公开受限仓库。仅在当前 shell 中暴露该令牌。不要将其粘贴到代理提示中，也不要将其提交到源代码控制中。
export HF_TOKEN=hf_xxx
./docker/run.sh assets
./docker/run.sh build
source ./docker/activate
资产步骤会将已注册的仿真资产下载到 ./assets/usd/
并将预训练的 X-Mobility 检查点 下载到 ./assets/x_mobility.ckpt
。401 或 403 响应通常表示仓库访问权限不完整或令牌作用域不足。在调试 Isaac Lab 之前，请先解决身份验证问题。
每个阶段都会在下一阶段开始之前生成可供审查的证据：
验证：软件与资产清单、环境报告以及冒烟测试日志准备场景：已注册的场景配置、占用地图以及目视检查证据训练：固定命令与配置、日志、遥测数据以及周期性检查点评估：匹配的协议、标准 COMPASS 指标、视频以及晋级建议打包：已批准的检查点、配置、评估记录以及产物清单
审批标准因项目而异，但每个关卡都应回答同一个问题：所需输入是否齐备，预期输出是否出现，是否存在未解决的错误，以及证据是否足以继续？
调用 COMPASS 技能
容器启动后，在仓库根目录打开编码代理，并描述机器人、场景、导航结果以及审批关卡。对于基线工作流，请将此提示复制到代理聊天中：
$compass 验证 Spot 的 COMPASS 环境。确认固定的
仓库修订版本、容器、GPU、Isaac Lab 与 Isaac Sim 版本、
仿真资产以及预训练的 X-Mobility 检查点。运行单环境
冒烟测试，保存验证报告，并暂停以等待批准。
$compass
技能会根据仓库检查所请求的工作流，并运行相关的验证步骤。如果运行失败，$compass-doctor
会执行只读健康检查并报告可能的原因，而不会在暗中更改环境。
图 2。一个编码代理调用 COMPASS 技能来验证环境、准备场景、运行冒烟测试，并在人工审批关卡处停止## 第 2 步：选择并准备一个导航场景
本节说明如何选择并准备三种场景来源之一：内置的 COMPASS 仓库、生成的 SAGE-10K 场景，或使用 Omniverse NuRec 渲染的捕获环境。你将了解每条路径的用途，以及在训练前必须完成哪些注册、占用地图和审批检查。
路径 1：使用内置仓库
从已注册的 combined_multi_rack
仓库开始，以获得最快且可复现的基线。机器人、场景和占用地图均已注册，这使其成为在引入新场景之前验证安装的最佳路径。
将以下提示复制到编码代理中，以运行基线并在冒烟测试后暂停：
$compass 在内置的 combined_multi_rack 仓库中训练并评估 Spot。
在单环境冒烟测试后停止，等待批准。
图 3. 一台 Spot 四足机器人在已注册的 COMPASS 中导航
combined_multi_rack
warehouse### 路径 2：使用 SAGE-10K 场景
SAGE-10K 数据集包含 50 种房间类型的 10,000 个生成的室内场景。它是一个场景数据集，而不是策略或模拟器。每个场景都提供几何结构、材质、布局元数据和预览。客厅和仓库场景遵循相同的准备路径，因此选择一个合适的候选场景，而不是下载整个数据集。
图 4. 一台 Spot 四足机器人位于为 COMPASS 验证准备而转换的 SAGE-10K 室内场景中
SAGE-10K 路径包含两个人工审批关卡。首先，在 NVIDIA Isaac Sim 中检查转换后的 USD，并在注册前确认几何结构、材质、比例和碰撞网格。在注册和占用地图生成之后，在完整训练之前批准单环境预览。占用地图标识出空闲和阻塞空间，用于确定有效的机器人起始位置和导航目标。
将以下提示复制到编码代理中，以筛选场景并在两个关卡处暂停：
$compass 为 Spot 寻找合适的 SAGE-10K 客厅或仓库场景，并展示最佳候选场景。
在我批准某个场景后，转换并注册该场景，生成并验证其占用地图，然后停下来等待检查。
在我批准该场景和地图后，运行一次单环境冒烟测试，并在完整训练前再次停下来。
图 5. Codex 筛选出兼容的 SAGE-10K 场景，并暂停等待开发者批准
路径 3：使用 NuRec 引入捕获的环境
当目标是在预期部署环境的重建中微调和评估 COMPASS 时，请使用 Omniverse NuRec。NuRec 将立体 RGB 捕获转换为可直接用于 Isaac Sim 的重建，包含对齐的视觉几何、碰撞网格以及可选的场景增强。文档中记录的 COMPASS 路径会注册渲染场景、验证其提供的占用地图和原点约定、检查机器人间隙，并在训练前运行单环境冒烟测试。
图 6. NuRec Real2Sim 策略（右）绕过桌子朝目标导航，与合成策略（左）进行对比
就本文而言，NuRec 是一条可选路径。动手训练流程继续使用 SAGE-10K，以便教程能够跟随一个场景从准备到评估的完整过程。对于捕获的环境，请使用 COMPASS NuRec 工作流 和 NVIDIA Isaac Sim NuRec 指南，包括客厅示例，用于场景准备、训练、评估、导出和 ROS 2 部署。
将以下提示复制到编码代理中，以准备一个已注册的 NuRec 场景并在训练前暂停：
$compass 为 <supported_robot> 准备已注册的 NuRec Real2Sim 场景 <scene_name>。
验证提供的占用地图与原点约定，检查碰撞与机器人间隙，
运行单环境冒烟测试，并在训练前停止以等待批准。
步骤 3：验证机器人-场景集成
一旦所选场景对 COMPASS 可用，在扩大训练规模之前先运行单环境预览。对于 SAGE-10K 场景，请先完成此前的视觉检查和场景注册审批关卡。确认 Isaac Sim 能够启动、场景能够加载、Spot 在有效位置生成、相机观测可用，并且机器人能够响应策略命令，不出现穿模、跌倒或产生未解决的仿真错误。
指示编码代理总结预览日志和视觉证据，识别任何阻碍因素，并停下来等待人工审批。只有在场景、机器人、观测和动作接口按预期协同工作后，才继续进行残差训练。
步骤 4：训练残差专家
本节说明 COMPASS 如何将预训练的 X-Mobility 策略适配到所选机器人和场景。你将启动残差强化学习、监控运行过程、保存候选检查点，并保留评估所需的证据。
启动残差训练
在单环境冒烟测试获得批准后，编码代理可以启动 标准残差 RL 工作流。以下命令使用 Spot 和内置仓库。在遵循生成场景路径时，请将环境键替换为已注册的 SAGE-10K 场景。
在冒烟测试获得批准后，编码代理可以启动标准残差 RL 工作流。以下示例运行内置仓库基线。在继续生成场景路径时，请将环境键替换为已注册的 SAGE-10K 场景。
python run.py \
-c configs/train_config.gin \
-o ./outputs/spot_combined_multi_rack \
-b ./assets/x_mobility.ckpt \
--enable_cameras \
--embodiment spot \
--environment combined_multi_rack
管理训练运行
残差训练是一个长时间运行的过程。编码代理应在持久会话或受管理的调度器中运行它，将日志和检查点写入配置的输出目录，并在不保持交互式会话打开的情况下报告进度。
训练前，记录命令、仓库修订版本、场景键、配置、检查点间隔和停止条件。如果运行被中断，验证最新检查点是否完整，并在继续之前确认支持的恢复选项。
监控训练并保存检查点
根据可用的 GPU 内存设置 --num_envs
，冒烟测试时仅使用一个环境。训练期间，监控奖励组件、目标进度、接触和跌倒、回合终止、吞吐量和 GPU 内存。
定期保存检查点，并在匹配条件下评估它们，而不是假设最终迭代是最好的。COMPASS 还支持分布式多 GPU 训练以应对更大规模的运行。训练时间因硬件、场景复杂度、环境数量和停止条件而异。
诊断故障并保留证据
在更改环境或训练配置之前，使用 COMPASS 诊断工作流调查故障。将认证错误路由到 Hugging Face 访问检查，将场景加载或碰撞错误路由到场景准备，将相机或动作接口错误路由到冒烟测试阶段，将内存错误路由到环境数量或多 GPU 配置。
保留训练配置、命令、仓库修订版本、场景注册、占用图、冒烟测试证据、日志、检查点和工件清单。在更改依赖项、场景资产、奖励或训练设置之前，需要开发者批准。
步骤 5：在提升检查点之前进行评估
本节展示如何确定残差检查点是否已准备好提升。你将学习如何在匹配条件下比较预训练基础策略和残差候选，解释标准 COMPASS 指标，标记任何衍生证据，并在打包前保留人工批准。
同时审查任务性能和安全性。标准 COMPASS 评估报告目标达成率、跌倒率和行进时间。其他证据，如目标进度、接触行为、超时或命令稳定性，应标记为衍生分析或自定义仪器。只有在匹配证据满足项目的导航和安全门限，并且人工批准打包后，才提升检查点。
以下提示是一个示例。根据你的工作流所需的机器人、场景、检查点和证据进行调整：
$compass 在选定的场景中，在匹配的种子、目标、初始状态、rollout 长度和主动终止条件下，将预训练的 X-Mobility 基础策略与可用的 Spot 残差检查点进行比较。报告标准的 COMPASS 评估指标，保存匹配的视频和确切的评估命令，清楚标注任何衍生证据，并在提升或打包检查点之前停下来等待人工批准。
步骤 6：将策略连接到机器人运行时
本节说明训练完成的策略在开发完成后如何连接到机器人运行时。你将了解参考策略的输入与输出、cuVSLAM 何时可以提供部署里程计，以及未注册的机器人何时需要新具身工作流。编码智能体负责协调开发与验证；它不在运行时控制机器人。
理解策略的输入与输出
COMPASS 资产步骤会下载用于冒烟测试和残差训练的预训练 X-Mobility 检查点。训练会为所选机器人和场景创建残差检查点。导出和部署会将训练好的策略打包用于推理；它们不会将基础模型和残差作为两个需要开发者手动连接的 ROS 2 组件暴露出来。
在参考 ROS 2 集成中，compass_inference 将前视相机图像、导航目标或路线，以及由里程计推导出的机器人速度转换为导出的策略输入。它在
/cmd_vel
上发布前向线速度和角速度命令。循环状态和上一动作是推理实现的内部内容，而非外部 ROS 集成输入。请针对目标部署验证坐标系、更新频率、归一化、命令限制、停止行为以及物理机器人控制器。
图 7. 在推理时，COMPASS 策略使用 RGB 输入、里程计和目标点，以及可选的地图和路线数据，为机器人控制器生成线速度和角速度命令
在需要时添加 cuVSLAM 里程计
当部署的机器人需要在无 GPS 或 GPS 间歇性环境中进行基于相机的状态估计，且尚未提供兼容且经过验证的里程计和变换时，请使用 cuVSLAM 库。它的里程计可以支持 COMPASS 导航器，但其地图不是导航策略的输入。
cuVSLAM 不属于 COMPASS 策略训练的一部分，也不需要智能体技能。将其作为独立的、版本匹配的 ROS 2 组件运行，将其里程计输出连接或重映射到 /chassis/odom
，提供所需的 odom-to-base_link
变换，并验证标定、时间戳、话题名称和坐标系约定。可选的 $cuvslam-onboard
和 $cuvslam-troubleshoot
技能可以在开发期间帮助配置和诊断此状态估计组件。
示例提示：
$cuvslam-onboard 将 cuVSLAM 配置为 <机器人及相机装置> 上 COMPASS 导航器的里程计来源。选择兼容的版本和跟踪模式，验证标定和时间戳，将里程计和 TF 连接到预期的 COMPASS 接口，并在启用导航前停下来等待批准。
将工作流扩展到另一台机器人
对于未注册的机器人，$compass-newembodiment
会引导开发者完成机器人配置、环境注册、动作映射以及单环境可视化冒烟测试。为新具身进行接入与为现有机器人训练专用模型是两项独立的工程任务，但二者使用相同的验证与审批模式。
本教程止步于检查点评估。导出为 ONNX、JIT 或 TensorRT、ROS 2 集成以及物理硬件部署，都需要针对目标机器人和运行时进行单独验证。场景质量、训练时长和检查点性能会因具身、环境、奖励设计和可用算力而异，因此该工作流并未定义通用的成功阈值。
COMPASS 入门
从参考路径开始，然后一次扩展一个组件：
- 搭建参考环境。克隆 COMPASS 仓库，按照COMPASS 手册快速入门操作，接受受限模型条款，并下载COMPASS 仿真资产和X-Mobility 检查点。 - 运行智能体工作流。在 Codex 中针对受支持的机器人和内置场景调用
$compass
，在冒烟测试后保留审批，并在匹配条件下训练和评估专用模型。 - 有意识地扩展和打包。对未注册的机器人使用
$compass-newembodiment
。保存配置、检查点、日志、匹配的评估结果以及下一次工程决策所需的视频。
要复现并扩展该工作流，请查看以下资源：
SAGE-10K 数据集，用于生成室内场景Omniverse NuRec 开发者页面、COMPASS NuRec 工作流和Isaac Lab NuRec 指南，用于捕获场景重建和导航策略训练NVIDIA Isaac Sim和NVIDIA Isaac Lab文档，用于仿真和机器人学习技术栈Isaac ROS Visual SLAM 文档，用于可选的基于 cuVSLAM 的部署里程计