企业官网建设流程全解析

柜子安静地立在桌面上，机械臂末端的夹爪已经贴上了抽屉把手，轨迹规划显示"到位"，接触力传感器也读到了数值，可抽屉就是纹丝不动。日志里joint_pos从头到尾是 0，仿真时间照常走，画面照常渲染，一切看起来都对——这是我第一次在 Isaac Sim 里把带关节的家具搬进 Orbit 场景时遇到的局面。后来折腾了大半天才明白，问题既不在轨迹也不在控制器，而在这个柜子在物理世界里压根没有被当成一个"整体"，它只是一堆各自独立的刚体碎块，关节约束根本没生效。

这篇内容就围绕这件事展开：在 Orbit 这套机器人学习框架里，怎么把一个带铰链、带滑轨的关节物体（柜门、抽屉、微波炉门、冰箱门这类）正确地接进场景，怎么读写它的关节状态，怎么让机械臂真的把它推开、拉开，以及过程中那些文档里不会写、但一定会踩的坑。适合已经能把 Orbit 的基本环境跑起来、想让机器人做点"真东西"而不是摆弄方块的人看。如果你连InteractiveScene都还没配置过，建议先把前面的基础流程走通再回来，不然下面很多细节会缺少参照。

1. 关节物体在仿真里到底是怎么被"组装"起来的

1.1 柜子和方块在物理求解器眼里不是一回事

很多人第一次接触关节物体，会下意识把它理解成"几个刚体 + 几个约束"，觉得只要把门和柜体摆在一起、中间加个铰链就完事了。这个理解在概念上没错，但在 PhysX 的求解流程里，一个真正的关节物体（articulation）和一个由多个刚体拼出来的组合体，走的是两条完全不同的路径。

普通的刚体，求解器只需要知道它的位姿、速度、质量和惯量，各自独立积分，碰撞了就用冲量法解接触。而 articulation 是一棵树状的刚体链，求解器会把它当成一个整体系统，用统一的广义坐标去解，关节约束不是"外力"，而是内建的坐标约束。这意味着两件事：第一，关节之间的耦合是强约束，不会像约束器那样被拉开；第二，整棵树的根节点必须明确，求解器需要知道从哪个 prim 开始往下收集连杆。

这也解释了一个非常典型的现象——你在 USD 里看着层级完美，门挂在柜体上，关节也建了，但一进仿真整个柜子就散架，或者门直接飞出去。原因几乎总是同一个：求解器没认出这是一棵 articulation 树，于是把每个RigidBodyAPI都当成独立刚体，关节约束被降级成普通约束，强度完全不够，一碰就崩。

1.2 四类关节，决定了你能做什么动作

日常家居和工业场景里的关节物体，基本逃不出下面四种关节类型。搞清楚它们的物理含义，比记住 API 名字重要得多。

实际做任务时，绝大多数交互都是 Revolute 和 Prismatic 这两类。这里有个很容易被忽略的细节：同一个柜子上，门的旋转轴和抽屉的滑动轴，方向往往不是同一个世界坐标轴。门的转轴通常是竖直的 Z 轴（俯视开门），也可能是水平的 Y 轴（上翻门）；抽屉的滑动轴一般是柜体正面法线方向。你在 USD 里定义的axis是局部坐标系下的轴，跟着父连杆一起转的。如果柜子本身在场景里被旋转过 90 度，那这个 axis 的含义就和你直觉里的世界轴对不上了。

1.3 被动关节这个概念，是整篇的地基

真正让很多人卡住的，是"被动"这两个字。

机械臂的关节是主动关节：它带驱动器（drive），你给它一个位置目标，它用力矩去追。而柜门、抽屉是被动关节：它没有电机，你不推它就不动，你推它它才动，松开手它靠阻尼和摩擦慢慢停下来。

在 Orbit 里，这两类东西用的是同一套Articulation资产类，区别全在actuators的配置上。如果你把一个柜子按机械臂的默认方式配置——给个非零的stiffness——那这个柜门就变成了一个"自带伺服的门"，它会死死地锁在你设定的目标位置上，机械臂推上去的感觉就像推一堵墙。反过来说，如果你把stiffness和damping全设成 0，门又会变得像在真空里飘着，碰一下能转好几圈。

正确的做法是把stiffness设为 0，damping给一个不大不小的正值，让关节有阻尼但没刚度。这个阻尼值就是"这个柜门有多涩"的物理表达，取值区间通常在 1 到 20 之间，具体看物件质量和你的操作力度。我在一开始没意识到这一点，把柜子配成了主动关节，然后花了两个小时怀疑是碰撞体没生成。

记住一句话：机械臂是被驱动的，柜门是被推动的。配置上唯一的区别就是刚度，但行为上天差地别。

2. 资产进场景之前：USD 结构必须先捋干净

2.1 ArticulationRootAPI 挂错一层，后面全白干

这是我在整个流程里踩得最深的一个坑，也是最值得单独拎出来讲的一条。

USD 里的关节物体，需要一个 prim 上挂着PhysicsArticulationRootAPI，求解器从这个 prim 开始向下遍历，把所有带RigidBodyAPI的子 prim 收进同一棵树。这个 API 挂的位置极其关键：

• 挂在最顶层的 Xform上：整棵树被正确识别，这是你要的。
• 挂在柜体那个 link 上：门和抽屉不在这个子树下面，会被遗漏，结果就是柜体能动能转，门却是死的。
• 完全没挂：所有刚体各自独立，关节失效，一碰就散。

诊断方法其实很简单，不用猜。加载资产之后，直接打印一下这个资产的连杆数量和关节数量：

cabinet = scene["cabinet"] print("num bodies :", cabinet.num_bodies) print("num joints :", cabinet.num_joints) print("body names :", cabinet.body_names) print("joint names:", cabinet.joint_names)

一个标准的双门带两抽的柜子，num_bodies应该是 5（柜体 + 左门 + 右门 + 上抽 + 下抽），num_joints应该是 4。如果你看到num_bodies只有 1，说明整个资产被当成单个刚体；如果num_joints是 0，说明关节没被收进来。这两个数字对不上，后面所有调试都是白费力气。

还有一种更隐蔽的情况：资产在 USD 层面结构是对的，但用 Orbit 的 spawn 配置加载进来之后，因为在prim_path上又套了一层 Xform，ArticulationRootAPI的相对位置变了。这时候表现是"有时对有时不对"，取决于你引用的是哪一层。我的习惯是加载完立刻做一次上面的打印，把数字写进注释里，以后改动资产一眼就能看出有没有退化。

2.2 轴向、限位和零点，三个最容易想当然的地方

USD 的关节定义里，真正影响行为的其实只有几个字段，但每一个都能让人调半天。

**轴向（axis）**决定了绕哪根轴转或者沿哪根轴滑。它在关节的局部坐标系里定义，单位是归一化向量。这里最容易犯的错是把"我眼睛看到的轴"直接写进去，而没考虑父连杆的局部坐标系朝向。一个稳妥的做法是在可视化界面里打开关节的 axis 显示，一边转一边看，确认方向符号也对——符号反了的话，你的限位[0, 1.5]就变成了反方向 1.5 弧度，门会往里开。

**限位（lower / upper）**是硬约束。旋转关节单位是弧度，滑动关节单位是米。我见过最离谱的一次是抽屉的行程被写成[0, 0]，等于这个抽屉在物理上被焊死了，怎么推都不动，但视觉上完全正常。排查的时候一定要先把所有关节的限位打出来看一眼。

零点是由关节的localPos0、localRot0、localPos1、localRot1这一组值决定的，它定义了"父连杆和子连杆在关节值等于 0 时应该怎么对齐"。这一组值如果和建模时摆的姿势不一致，表现就是资产一加载进来，门"啪"地一下弹到某个奇怪的角度，或者抽屉瞬间弹出一半。遇到这种开场就错位的情况，基本可以断定是零点和初始摆放姿势不匹配，而不是物理参数的问题。

2.3 碰撞体与质量：别让一个柜门比机械臂还重

关节物体的碰撞体经常是"能看不能碰"。很多从建模软件导出的资产，视觉网格做得很精细，碰撞体要么缺失，要么是一堆细碎三角面。缺失的表现是机械臂直接穿过去；细碎三角面的表现是接触力忽大忽小、门抖动得厉害。

实用的处理原则：关节物体用简化碰撞体，别用视觉网格。柜体用几个盒子拼，门用一块薄板，抽屉用五面盒子。面数少、形状凸，接触求解稳定得多，速度也快。

质量这块有一个反直觉的点：柜门如果按真实木材密度算，可能只有一两公斤，而机械臂末端能输出的推力也就几十牛。听起来够用，但仿真里因为接触模型是软约束，实际有效推力会打折扣，加上门还有阻尼，很容易出现"推得动一点点但推不到位"。我的经验是把门和抽屉的质量适当放大到真实值的 1.5 到 2 倍，接触响应会更"实"，反而不容易抖。当然这是工程折中，如果你的任务对质量精度敏感，那就去调求解器参数，别动质量。

另外记得检查惯量。有些资产是从别的格式转过来的，惯量张量是单位阵，导致门转起来像一张纸，一点力就转飞。惯量不对的时候，表现往往是"接触瞬间速度暴增"，这个特征很好认。

3. 在 Orbit 里把它登记成一个可交互资产

3.1 SceneCfg 与 ArticulationCfg 的最小闭环

Orbit 的场景组织方式是声明式的：你先写一个继承自InteractiveSceneCfg的配置类，把场景里所有的东西列出来，框架负责实例化、克隆到多个环境、管理生命周期。关节物体也用同一条路子，只不过它的配置类型是ArticulationCfg而不是RigidObjectCfg。

下面是一个能跑起来的最小闭环，我把它当成模板用：

import omni.isaac.orbit.sim as sim_utils from omni.isaac.orbit.assets import ArticulationCfg, AssetBaseCfg from omni.isaac.orbit.scene import InteractiveSceneCfg from omni.isaac.orbit.utils import configclass from omni.isaac.orbit.actuators import ImplicitActuatorCfg CABINET_CFG = ArticulationCfg( prim_path="{ENV_REGEX_NS}/Cabinet", spawn=sim_utils.UsdFileCfg( usd_path="/path/to/your/sektion_cabinet.usd", activate_contact_sensors=True, rigid_props=sim_utils.RigidBodyPropertiesCfg( disable_gravity=False, max_depenetration_velocity=5.0, retain_accelerations=False, ), articulation_props=sim_utils.ArticulationRootPropertiesCfg( enabled_self_collisions=False, solver_position_iteration_count=16, solver_velocity_iteration_count=4, fix_root_link=True, ), ), init_state=ArticulationCfg.InitialStateCfg( pos=(0.6, 0.0, 0.0), rot=(1.0, 0.0, 0.0, 0.0), joint_pos={ "door_left_joint": 0.0, "door_right_joint": 0.0, "drawer_top_joint": 0.0, "drawer_bottom_joint": 0.0, }, joint_vel={".*": 0.0}, ), actuators={ "passive_joints": ImplicitActuatorCfg( joint_names_expr=[".*"], stiffness=0.0, damping=8.0, friction=0.05, ), }, ) @configclass class CabinetSceneCfg(InteractiveSceneCfg): robot = ROBOT_CFG.replace(prim_path="{ENV_REGEX_NS}/Robot") cabinet = CABINET_CFG table = AssetBaseCfg( prim_path="{ENV_REGEX_NS}/Table", spawn=sim_utils.CuboidCfg( size=(1.2, 0.8, 0.05), rigid_props=sim_utils.RigidBodyPropertiesCfg(kinematic_enabled=True), collision_props=sim_utils.CollisionPropertiesCfg(), visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(0.4, 0.4, 0.45)), ), init_state=AssetBaseCfg.InitialStateCfg(pos=(0.6, 0.0, -0.03)), )

几个参数值得单独说。fix_root_link=True把整个柜子的根连杆钉死在世界上，柜子不会被机械臂推着满地跑，这在桌面操作任务里几乎是必开项。enabled_self_collisions=False关掉连杆之间的自碰撞，因为很多资产的相邻连杆碰撞体在关节处本身就是穿插的，开了自碰撞会以为一直在碰撞，抖到停不下来。activate_contact_sensors=True打开接触传感器，方便后面读取接触力做调试。

3.2 spawn 还是 reference：prim_path 决定的加载方式

ArticulationCfg里spawn和prim_path的组合方式，决定了资产是"复制一份进来"还是"引用一份进来"，这个差别在多环境训练里影响很大。

如果usd_path指向的是一个完整的、独立的柜子资产文件，spawn会为每个环境各复制一份，物理属性完全独立，可以单独随机关节阻尼、摩擦、质量——这正是域随机化需要的。但如果prim_path就指向当前 stage 里已经存在的某个 prim（比如你用别的方式已经把柜子摆好、绑好材质了），那spawn就应该设成None，框架会直接接管这个 prim。后一种方式适合精调过的资产，但代价是所有环境共享同一份物理数据，随机化会失效。

还有一个细节：{ENV_REGEX_NS}这个占位符会被替换成每个环境的正则命名空间，比如/World/envs/env_3。柜子的prim_path里必须带上它，否则所有环境都会往同一个位置 spawn，最后只剩下一个。这个错误的表现很迷惑——num_envs设成 64，但看起来只有一个场景有柜子，其他环境都是空的。

3.3 actuators 配置：把驱动摘掉才算"被动"

上一节里actuators那一块看着不起眼，其实是整个配置的灵魂。

ImplicitActuatorCfg是隐式驱动器，它把刚度阻尼直接写进 PhysX 的 drive 参数里，不需要每帧计算 PD。对被动关节来说，stiffness=0.0是要点，damping才是你要调的"涩度"。friction可以给一个很小的值，模拟关节内部的静摩擦。

这里有个很实际的取舍：如果把damping设得太大（比如 50 以上），门会变得像泡在蜂蜜里，机械臂推上去要走一段才动，而且推到位之后回弹明显，做精细的"拉开到指定缝隙"任务基本不可能。设得太小（比如 0.5），门会在惯性下自己晃荡，稍微碰一下就到最大角度，成功判定很容易误触。

我的做法是先按damping=8起手，然后跑一次纯手动推的测试——脚本里直接给门一个恒定的小速度，看它在没有外力之后多久停下来。停下来用了一秒以内，说明阻尼偏大；转了三圈才停，说明偏小。调到手感合适再往下做。

4. 关节状态的读、写与手动验证

4.1 读接口和 joint 索引的对齐问题

Orbit 的Articulation资产上暴露的关节状态是张量形式的，形状是(num_envs, num_joints)。这里有一个必须小心的点：joint_names的顺序不一定和你在 USD 里建的顺序一致，求解器收集连杆和关节的顺序取决于遍历顺序，你可能以为是门、门、抽屉、抽屉，实际读出来是抽屉、门、门、抽屉。

所以永远不要用写死的下标去索引关节，用名字查：

cabinet = scene["cabinet"] joint_names = cabinet.joint_names print(joint_names) # 先看一眼真实顺序 ids, names = cabinet.find_joints(["drawer_top_joint", "drawer_bottom_joint"]) print(ids, names) idx = ids[0] pos = cabinet.data.joint_pos[:, idx] # (num_envs,) vel = cabinet.data.joint_vel[:, idx] lim = cabinet.data.joint_limits # (num_envs, num_joints, 2)

顺便说一句，joint_limits这个量很多人不知道可以读。排查"抽屉推不动"的时候，先看一眼joint_limits，如果上下限相等，问题就找到了，根本不用往下查。

4.2 先做一次"裸驱动"测试，再谈机械臂

这一条是我最想推荐的实践：在接机械臂之前，先单独验证关节本身能不能动。

方法很简单，临时把柜子的驱动器改成主动，给个刚度，然后下位置目标，看关节值是否跟着走：

# 临时验证用，验证完记得改回 stiffness=0 cabinet.write_joint_state_to_sim( joint_pos=torch.zeros_like(cabinet.data.joint_pos), joint_vel=torch.zeros_like(cabinet.data.joint_vel), ) for step in range(120): target = torch.zeros_like(cabinet.data.joint_pos) target[:, idx] = 0.6 # 目标：拉开 0.6 米 cabinet.set_joint_position_target(target) sim.step() if step % 20 == 0: print(cabinet.data.joint_pos[:, idx])

如果这个测试里关节值平滑地从 0 涨到 0.6，说明资产、关节、限位、索引全都是对的，后面出问题就一定出在机械臂或接触上。如果这个测试里不动，那问题必然在资产侧，你省下了怀疑控制器的几个小时。

这个思路我管它叫"分层验证"——把一条链路切成资产层、场景层、控制层三段，每段单独给一个能判真假的最小测试。仿真调试最怕的是全链路一起猜，猜一天也猜不出来。

4.3 重置链路：root state 和 joint state 要一起写

训练时每个 episode 结束都要 reset。对普通刚体，重置就是写一下根位姿；对关节物体，只写根位姿是不够的——关节角度会保留上一轮的最终状态，门还开着，抽屉还拉着。

正确的重置要写两处：

def reset_cabinet(env_ids, cabinet, default_root_state, default_joint_pos): cabinet.write_root_state_to_sim(default_root_state[env_ids], env_ids=env_ids) cabinet.write_joint_state_to_sim( default_joint_pos[env_ids], torch.zeros_like(default_joint_pos[env_ids]), env_ids=env_ids, )

write_root_state_to_sim写的是根连杆的位姿和速度，write_joint_state_to_sim写的是所有关节的角度和角速度。两个都写，顺序无所谓，但都要写。

这里有个隐蔽的坑：如果你只重置了env_ids指定的环境，但default_joint_pos是全量的，索引就会错位。Orbit 的约定是第一个维度是环境，所有写到仿真里的张量都要先按env_ids索引一次。这个错误的表现是"重置之后部分环境的门是开的"，很难第一时间联想到索引问题。

5. 机械臂真上手推的时候，问题才刚开始

5.1 推不动：一条从日志到参数的排查链

资产验证通过了，机械臂接上了，然后抽屉还是推不动或者推不到位。这时候不要瞎调参数，按下面的顺序一条条走，基本能在半小时内定位。

第一步，看关节值有没有变化。打印cabinet.data.joint_pos在操作前后的差值。完全不变说明接触力没传递过去，变了一点点又回去说明力不够或者被阻尼吃掉，变化超调说明参数太软。

第二步，看接触有没有建立。开了接触传感器之后可以读净接触力。如果净接触力一直是 0，那说明机械臂末端根本没碰到把手——这时候问题在轨迹，不在物理。这类情况特别常见，尤其是把手很细的时候，视觉上看着碰到了，碰撞体还差几毫米。

第三步，看关节限位和阻尼。前面说过，限位相等就是焊死，阻尼过大门会赖着不走。

第四步，看质量和惯量。如果门重得离谱，或者惯量是单位阵，接触响应会非常怪。

第五步，看求解器迭代次数。articulation 的solver_position_iteration_count默认值往往只有 4，对层级深、连杆多的资产不够，关节约束会显得"软"，推上去先变形再动。调到 16 到 32 之间通常就好了，代价是速度。

我用一张表把这条链路固化下来，每次遇到问题直接对号入座：

5.2 一碰就飞：能量注入的几个来源

"推不动"的反面是"一碰就飞"，后者更吓人，因为画面直接崩坏，还容易让人误以为是坐标问题。

飞出去的本质是系统在某个瞬间被注入了不该有的能量。常见来源有四个。

第一是质量太小。门如果只有 0.1 公斤，而机械臂末端速度不低，一动量交换就是巨大的速度。把质量提到合理范围就稳了。

第二是穿透后的反弹。如果末端速度很快、步长又大，一帧之内穿进了门的碰撞体内部，下一帧求解器会把穿透量一次性弹开，速度极大。解决办法是降低末端速度、开连续碰撞检测、或者把max_depenetration_velocity限制在一个小值上。这个参数在RigidBodyPropertiesCfg里，默认值有时偏大，改到 1 到 5 之间比较稳。

第三是关节限位缺失。限位是[0, 0]会焊死，但如果是[-inf, inf]或者干脆没定义，门就可以无限旋转，转起来之后离心效果会让它越来越快。所有关节都必须有有限限位，这是硬要求。

第四是求解器迭代不足导致的约束违约。约束没解到位，穿透量累积，然后突然反弹。这一类只能靠加迭代次数和减步长。

5.3 手柄滑脱与接触点抖动

抓把手做拉门动作时，另一个高频问题是夹爪从把手上滑掉。仿真里没有真实的摩擦自锁，全靠摩擦系数和法向力，稍微不对就滑。

几个实用的调整方向：

• 摩擦系数。把把手和夹爪的材质摩擦调到 1.0 以上，静摩擦和动摩擦都要给。只给动摩擦不给静摩擦，夹爪会一直缓慢滑移。
• 接触偏移。Orbit 的碰撞体配置里有接触偏移参数，正偏移会让碰撞体"胖"一圈，能显著减少漏接触，但会让末端看起来提前碰到东西。0.002 到 0.005 米是比较常用的折中。
• 夹爪闭合速度。闭合太快会在接触瞬间产生冲击，把物件弹开。慢一点，让接触力爬升，夹持稳定得多。
• 把手的碰撞体精度。细长把手如果用凸包近似，很容易被"包"成一个粗棒子，接触点位置和视觉差别大。这种情况宁可把把手单独拆成一个圆柱碰撞体。

至于抖动，多数是接触点在两个面之间来回跳。表现为末端位置的小幅高频振动，力读数也在抖。处理办法是降低末端刚度（如果是阻抗控制）、加一点阻尼、或者干脆用位置控制做慢速推进，别用纯力控。

5.4 物理步长与求解器迭代的配比

这两个参数经常被当成"调大就行"，其实它们有配比关系。

物理步长dt决定了每帧积分的精度，迭代次数决定了每帧约束求解的收敛程度。直觉上，dt减半，约束误差大致降到 1/4（因为穿透量是速度乘时间，而速度误差又和时间相关），所以减半步长往往比加倍迭代更有效。但代价是计算量翻倍。

我的经验配置是：

还有一个容易被忽略的点：控制频率和物理频率要解耦。Orbit 里可以用decimation让一个控制步对应多个物理步。关节物体的接触响应很快，物理步太粗就会漏掉接触瞬间，控制步太细又会让策略网络学到高频噪声。我的习惯是物理 1/120、控制 1/60，也就是decimation=2。

6. 训练和评测阶段还需要补的三件事

6.1 观测里该放哪些关节量

关节物体的状态是做这类任务的核心观测。最基本的三个量：关节位置、关节速度、关节到限位的归一化距离。

第三个量特别有用，因为它把不同行程的抽屉统一到了一个尺度上。一个开 0.4 米的抽屉和一个开 0.7 米的抽屉，原始位置数值差很多，但"开了百分之多少"是同一个语义。归一化写法：

limits = cabinet.data.joint_limits # (num_envs, num_joints, 2) lower, upper = limits[..., 0], limits[..., 1] span = (upper - lower).clamp(min=1e-6) norm_pos = (cabinet.data.joint_pos - lower) / span # 0~1

除了关节量，通常还要放末端位姿、末端到把手的相对位姿（如果把手位置可获取的话）。相对位姿比绝对位姿好用得多，策略更容易泛化到不同摆放位置。

如果你打算做视觉策略，那还要考虑把关节物体渲染进相机视野，并且注意相机分辨率和把手尺寸的匹配——细把手在低分辨率下几乎看不见。

6.2 关节阻尼、摩擦、质量的随机化

域随机化是 sim-to-real 的关键一环。对关节物体来说，最需要随机的三个量是关节阻尼、表面摩擦、连杆质量。

Orbit 里现成的 event term 覆盖了刚体质量和材质，但关节阻尼的随机化通常需要自己写。这不是框架偷懒，而是关节阻尼的随机化要直接写进 PhysX 的 drive 参数，得绕一层。常见的做法是在 reset 时手动设置：

def randomize_joint_damping(env, env_ids, cabinet, damping_range=(4.0, 16.0)): num = len(env_ids) # 每个环境一个随机阻尼，广播到所有关节 d = torch.empty(num, device=cabinet.device).uniform_(*damping_range) d = d.unsqueeze(-1).repeat(1, cabinet.num_joints) cabinet.write_joint_damping_to_sim(d, env_ids=env_ids)

关键点是每个环境独立采样，不要全局采一个值然后所有环境共用，那样起不到泛化作用。另一个点是采样范围别太宽，阻尼从 1 到 100 的随机化会让训练极不稳定，因为极端值下的动力学完全不同。经验范围是标称值的 0.5 倍到 2 倍。

材质摩擦的随机化走框架现成的接口就行，注意要同时随机静摩擦和动摩擦，并且保持静摩擦略大于动摩擦，否则物件会自己缓慢滑动。

6.3 成功判定的写法与阈值标定

"抽屉拉开了"这个判定，看起来简单，写起来坑不少。

最朴素的写法是joint_pos > threshold。问题在于：机械臂可能在触发的瞬间就把抽屉推回去了，或者只是短暂地撞了一下就超过阈值。所以判定必须带持续时间。

def check_success(cabinet, idx, threshold, hold_steps, state): pos = cabinet.data.joint_pos[:, idx] over = pos > threshold state["cnt"] = torch.where(over, state["cnt"] + 1, torch.zeros_like(state["cnt"])) return state["cnt"] >= hold_steps

hold_steps一般取 10 到 20 个控制步，对应 0.2 到 0.4 秒。太短容易误判，太长会让 episode 末尾拖着走。

阈值怎么定？我的做法是先用人工示教或脚本跑出最好的成绩，然后取那个值的 80% 到 85%。比如人工能拉开 0.35 米，阈值就定 0.3。定 0.9 倍会让策略过度追求极限，学出一堆撞门的暴力动作；定 0.5 倍又太容易，策略学不到精细控制。

还有一个容易忽略的场景：门被推开后又被关上。如果你的任务定义是"最终状态是开的"，那判定要用当前帧的状态，不能用历史最大值。用最大值的话，机械臂只要撞一下就成功，学出来的策略会非常怪。

7. 一份踩坑对照表和几条硬经验

把上面散落的东西收一收，下面这张表基本覆盖了我在这类任务里遇到的绝大部分问题，可以直接拿去当检查清单用。

几条我认为最值钱的经验，单独列出来：

第一条，永远先做空场景验证。把柜子单独放进一个没有机械臂的场景，用脚本直接驱动关节，确认它能动、能停、有限位。这一步花十分钟，能省下后面两小时。

第二条，打印永远比猜快。遇到问题时先把num_bodies、num_joints、joint_names、joint_limits、joint_pos这五个量打出来，九成的异常在这五个数字里就能看出来。别急着改参数。

第三条，不要一次改两个变量。关节物体的调试涉及质量、阻尼、限位、迭代次数、步长五六个参数，它们互相影响。一次只改一个，改完立刻复现同一个测试，把结果记下来。我吃过太多"改了一堆参数突然好了但不知道为什么好"的亏，下次遇到同类问题还是不会调。

第四条，接触力是最诚实的证据。你觉得碰到了，不算碰到；net_contact_force有数值，才叫碰到。开接触传感器的那一点点性能开销，跟调试时间比起来完全值得。

第五条，把失败案例存下来。调试过程中那些"推不动""一碰就飞"的配置，别急着删，存成一个单独的配置文件，注释写清楚症状。等你第二次遇到，直接对照表一查就定位了。这些东西比任何文档都更贴近你自己的资产和任务。

最后提一句框架版本的事。Orbit 这套东西迭代很快，类名和参数名在不同版本之间会变——有的版本里驱动器配置叫ImplicitActuatorCfg，有的版本里资产类从Articulation拆出了专门的类型，后面整个框架还改过一次名字。我踩过最无语的一次坑是照着半年前的示例写配置，字段名对不上，报错信息还很含糊。所以遇到说不通的报错，先去看当前版本源码里的 configclass 定义，比搜任何教程都靠谱。资产的 USD 结构倒是稳定的，理解了那条树，换版本也就是改改字段名的事。