SpatialClaw: Rethinking Action Interface for Agentic Spatial Reasoning
作者：Seokju Cho, Ryo Hachiuma, Abhishek Badki, Hang Su, Byung-Kwan Lee, Chan Hee Song, Sifei Liu, Subhashree Radhakrishnan, Seungryong Kim, Yu-Chiang Frank Wang, Min-Hung Chen
核心发表机构：KAIST、NVIDIA
论文链接：arXiv:2606.13673v1
发布于：arXiv 预印本（cs.CV）
一、核心贡献 / Core Contributions
- 提出SpatialClaw，一个无需训练的空间推理框架，核心创新在于将Python 代码作为智能体的动作接口，替代传统的一次性代码执行或结构化工具调用。
- 维护一个有状态的 Python 内核，预加载输入帧、感知工具（重建、分割）和科学计算库，使 VLM 驱动的智能体能够逐步编写、执行代码，并基于中间文本和视觉观察灵活调整分析策略，实现开放式的 3D/4D 空间推理。
- 在20 个空间推理基准（涵盖单图像、多视图、视频/4D、通用空间和通用视频任务）上，使用6 个不同规模的 VLM 骨干（Qwen 和 Gemma 系列）进行评测，均取得一致且显著的性能提升，无需任何基准或模型特定的适配。
- 平均准确率达到59.9%，超越此前最先进的空间智能体（SpaceTools）+11.2 个百分点；消融研究证实性能提升主要归功于代码接口的表达力，而非工具集的大小。
二、研究背景与动机 / Background & Motivation
空间推理——确定物体在三维空间中的位置、关系以及运动方式——是视觉-语言模型（VLM）面临的长期挑战。尽管 VLM 在识别和描述二维图像方面取得了显著进步，但当需要处理深度、相机姿态、时间对应关系等多步组合证据时，其内部分辨率能力仍然不足。为此，工具增强型智能体被提出：通过外接专业感知模块（如深度估计、分割、3D 重建）来弥补 VLM 的局限。然而，这类智能体的有效性不仅取决于感知工具本身，更关键地取决于动作接口——即智能体如何调用、组合和编排这些工具。
现有空间智能体主要采用两种动作接口设计。单次代码执行（如 pySpatial）要求 VLM 在一次代码生成中提交完整的分析策略，在观察到任何中间结果（如检测到的掩码、深度图、可视化）之前就已确定所有步骤，缺乏根据中间证据修正路径的能力。结构化工具调用（如 SpaceTools）通过预定义的 JSON/XML 接口逐次调用工具，虽然允许分步进行，但预定义的 API 限制了灵活性：智能体无法自由组合数值计算、编写条件判断或循环，也难以针对每个问题即时构造新的分析操作。这两种设计在处理开放、复杂的 3D/4D 空间推理任务（如从视频中推断相机运动、跨视图比较物体朝向）时均表现出明显的局限性。
因此，本文重新思考动作接口的本质：能否将代码本身视为最灵活的动作空间？受 Jupyter Notebook 式交互的启发，作者提出 SpatialClaw，让智能体每步生成一个可执行的 Python 单元格，并在持久化的内核中逐步执行、观察、修正，从而将中间结果转化为下一步决策的依据。这种方式不仅保留了结构化工具调用的分步特性，更赋予了智能体任意组合感知原语和数值计算的能力，使其能根据问题需求动态调整分析策略。
原论文对应图片（fig:teaser）：
三、方法 / Methodology
3.1 总体框架 / Overall Architecture
SpatialClaw 的整体推理流程是一个五阶段循环，如下图所示。每个样本在一个隔离的有状态 IPython 内核中求解，智能体逐步编写代码并观察执行结果，直至提交最终答案。
循环的五阶段包括：
- 规划（Planning）：一个轻量的规划器 LLM（不接收输入图像，仅基于问题文本和工具文档）生成高层次的初步计划。
- 代码生成（Code Generation）：主 VLM 智能体接收问题、规划、之前的执行轨迹以及通过
show()注册的视觉反馈，结构化输出包含Purpose、Reasoning、Next Goal和Code四个字段的 Markdown 响应，其中代码部分是一个可执行的 Python 单元格。 - 代码执行（Code Execution）：代码在持久化内核中执行。执行前经过静态安全分析（AST 分析+正则检查），拒绝不安全的模块和操作；通过后执行并捕获输出。
- 反馈组装（Feedback Assembly）：将执行结果（标准输出、变量摘要、通过
show()注册的图像等）组装为下一轮对话的上下文。 - 答案提交（Answer Submission）：当智能体调用
ReturnAnswer()时循环终止；若达到最大步数或连续失败上限，由终止节点尽力返回答案。
3.2 关键模块 / Key Modules
3.2.1 有状态持久化内核
内核是整个框架的基础。对于每个样本，系统启动一个专属的 IPython 内核，并注入以下变量和模块：
InputImages：输入帧列表（图像或视频帧）。Metadata：包含帧计数、帧索引、帧率等元数据。tools：一套感知和几何基元，包括tools.Reconstruct（封装 Depth Anything 3 的 3D 重建）、tools.SAM3（基于 SAM3 的图像/视频分割）、及tools.Geometry、tools.Mask、tools.Draw、tools.Graph、tools.Time等实用工具。- 科学计算库：
numpy、scipy、matplotlib等。 show()：将图像嵌入到下一轮对话上下文中供智能体视觉观察。vlm：允许智能体向独立的 VLM 会话发送查询（如vlm.locate进行视觉定位，vlm.ask_with_thinking进行推理）。ReturnAnswer()：提交最终答案。
内核在整个推理过程中持续存在，智能体创建的变量（掩码、点云、数值结果等）在所有单元格中保持作用域，避免重复计算。
3.2.2 安全沙箱与错误处理
由于代码完全由 LLM 生成，安全性和鲁棒性是关键。SpatialClaw 实施多层防御：
- 静态检查：每次执行前解析代码的 AST，拒绝文件 I/O、网络访问、动态代码原语（
exec、eval）、直接导入 GPU 后端库等不安全操作。被拒绝的单元格返回错误信息，智能体在同一推理步内修正。 - 运行时保护：每个单元格设置超时（wall-clock timeout），超时后清除内核用户命名空间并通过重新注入恢复环境；工具调用失败有自动重试机制。
- 错误反馈：所有异常（语法错误、空变量、类型不匹配等）都被格式化后直接路由到下一轮反馈中。特别地，对于“每帧类型合约”（Per-Frame Type Contract），当组合不同帧索引的感知输出时自动检查帧对齐，不匹配时立即抛出异常，防止静默的语义错误。
3.2.3 规划器与主智能体的协作
规划器在每个样本开始时运行一次，不观察图像，仅基于问题文本和元数据输出一个纯文本计划（包括任务分析、信息需求列表、计算计划、验证检查表等）。该计划被追加到主智能体的系统提示中，指导后续代码生成。规划器被禁止编写可执行代码或输出结论性语句，从而将规划与执行解耦。主智能体则根据实际执行中的中间反馈动态调整自己的步骤。
3.2.4 视觉反馈机制
工具产生的视觉结果（如图表、掩码覆盖图、3D 重建俯视图）被封装为VisualFeedback对象。智能体通过show()命令内联查看图像，同时还能获取相关文本摘要（如图表的最小/最大值、均值、趋势）。这使得智能体在后续步骤中同时依赖文本数值和视觉观察进行推理。
四、实验 / Experiments
4.1 数据集与评估指标 / Datasets & Metrics
评估覆盖20 个空间推理基准，涵盖广泛的静态和动态 3D/4D 任务：
- 单图像：ERQA, Omni3D, OmniSpatial, SPBench。
- 多视图：MindCube, MMSI, SPAR-Bench。
- 视频/4D：MMSI-Video, OSI-Bench, PAI-Bench, VSI-Bench-U, VSTI-Bench, DSI-Bench。
- 通用空间：BLINK, SpatialTree, ViewSpatial。
- 通用视频：CV-Bench, PerceptComp, Video-MME, Video-MME-v2。
对于样本数超过 1000 的基准，随机选取 1000 个样本进行评测。评分采用每样本计分：分类问题用准确率（Acc），数值问题用平均相对准确率（MRA）。最终结果为所有 20 个基准的平均准确率。所有实验共享相同的超参数（最大步数N max = 30 N_{\text{max}}=30Nmax=30）、系统提示和感知工具集，无任何基准特定的调整。
4.2 主实验结果 / Main Results
在 6 个 VLM 骨干（Qwen3.5-397B-A17B、Qwen3.5-122B-A10B、Qwen3.6-35B-A3B、Qwen3.6-27B、Gemma4-31B、Gemma4-26B-A4B）上，SpatialClaw 相对于无工具基线在所有骨干上均取得一致提升。使用 Gemma4-31B 骨干时，平均准确率达59.9%，比无工具基线（53.4%）高出 6.5 个百分点。与最先进的空间智能体对比（均使用相同骨干，Gemma4-31B）：SpatialClaw 59.9% 显著高于 SpaceTools（48.7%）、pySpatial（45.2%）和 VADAR（43.8%），平均超出 SpaceTools11.2 个百分点。提升在需要跨帧/跨视图链式几何计算的视频/4D 和多视图任务上最为显著（如 DSI-Bench 提升 17.6%，MMSI 提升 13.4%）。
为了直观展示不同元类别的性能优势，下图给出了 SpatialClaw 相对于结构化工具调用和单次代码执行在 13 个元类别上的胜出幅度：
可见，在 11 个类别上 SpatialClaw 胜出，最大增益（+6–9 个百分点）集中在需要链式几何计算的类别（如相机运动、多视图/视点推理、相对方向），而在视觉识别类别上优势较小，表明瓶颈已转移至感知质量。
4.3 消融实验 / Ablation Study
4.3.1 动作接口消融
在 Gemma4-31B 骨干上，将三种动作接口变体与无工具基线对比：
- 单次代码执行（一次性生成完整程序）：平均 55.2%
- 结构化工具调用（通过 JSON 命令逐次调用工具）：平均 56.7%
- SpatialClaw（迭代代码执行）：平均 59.9%
结果表明，迭代代码执行在所有变体中性能最高，且仅在 5/20 个基准上低于某种变体（通常差异很小），在剩余 15 个基准上均取得最佳或次佳结果。这证实代码接口的表达力是性能提升的关键。
4.3.2 组件消融
移除各种工具组件，使用 Qwen3.6-27B 骨干（平均准确率）：
- 完整 SpatialClaw：56.9%
- (I) 移除所有实用工具（仅保留感知工具 SAM3/DA3 和科学库）：56.4%（小幅下降）
- (II) 移除感知工具（仅保留实用工具和科学库）：51.4%（大幅下降但仍优于无工具）
- 无工具基线：48.7%
可见感知工具是性能的主要贡献者，但实用工具（掩码统计、几何计算等）也提供了额外组合能力。更值得注意的是，即使移除所有预定义的实用包装器，SpatialClaw 的性能仍与完整版本相当，说明核心优势在于代码接口自身的表达力——智能体可以通过科学计算库即兴完成与实用工具相同的逻辑。
4.3.3 工具使用模式分析
分析不同元类别中智能体对原语（如KDTree、norm、dot product）的使用频率，发现距离类问题倾向于使用 KDTree 和向量范数，方向类问题倾向于使用点积和角度运算。这种专业化并非硬编码，而是智能体从问题语义中自发选择的，体现了代码接口的灵活性。
五、相关工作 / Related Work
工具增强智能体：早期工作通过结构化 API 调用扩展 VLM 能力（如 SpaceTools、GCA、RieMind），但其预定义接口限制了组合灵活性。SpatialClaw 采用代码作为接口，属于 CodeAct 范式的具体实例化，但本文首次从空间推理角度进行系统对比，并通过轨迹级分析识别了代码接口何时以及为何带来提升。
单次代码执行智能体：pySpatial、VADAR 等方法让 LLM 生成一次性程序执行，无法在观察到中间结果后调整策略。SpatialClaw 的迭代、有状态执行允许智能体逐步修正，特别适合需要多步证据链的空间推理。
仅依赖 VLM 内在能力的方法：无工具基线（如直接问答）在简单视觉问题上有一定效果，但在需要精确 3D 几何的任务上表现差，凸显了外部感知工具的必要性。
六、局限性与展望 / Limitations & Future Work
尽管 SpatialClaw 在 20 个基准上取得了显著提升，但分析表明其当前瓶颈已从动作接口设计转向感知质量。失败模式分析（使用 LLM-as-Judge 评估 1000 个错误样本）显示，主要错误类型包括：几何推理错误（处理 3D 坐标、距离、角度等）、感知工具局限性（分割/检测局部错误导致证据传播）、VLM 幻觉（幻视对象/属性），以及无法从错误中恢复（过早承诺或循环振荡）。动作接口本身并非主要失败源。
未来方向包括：
- 提高感知质量：改进重建（Depth Anything 3）和分割（SAM3）模型的精度，或引入更鲁棒的多模态感知范式。
- 强化学习：通过强化学习优化智能体的工具选择、几何操作编码和错误恢复策略，减少几何推理错误。
- 更长序列与更高分辨率：当前最大输入帧数为 64，上下文长度约 262K tokens，对于极长视频可能不足；扩展上下文窗口或采用记忆压缩机制可处理更长时间跨度的推理。
七、总结 / Conclusion
SpatialClaw 提出了一种新颖的无训练框架，将Python 代码作为空间推理智能体的核心动作接口。通过在有状态的持久化内核中逐步编写、执行和修正代码，智能体能够灵活组合感知工具和数值计算，并根据中间视觉/文本证据动态调整分析策略。在 20 个空间推理基准、6 个不同规模的 VLM 骨干上，SpatialClaw 一致优于现有的单次代码执行和结构化工具调用方法，平均准确率达 59.9%，超越最先进基线 11.2 个百分点。消融研究证实性能提升主要归功于代码接口的表达力，而非工具集的大小。SpatialClaw 为开放域 3D/4D 空间推理提供了一种简洁而强大的解决方案，并揭示了动作接口设计在工具增强智能体中的核心作用。未来的主要提升途径在于提高底层感知模型的质量，而非进一步优化接口本身。
原文摘要:Spatial reasoning, the ability to determine where objects are, how they relate, and how they move in 3D, remains a fundamental challenge for vision-language models (VLMs). Tool-augmented agents attempt to address this by augmenting VLMs with specialist perception modules, yet their effectiveness is bounded by the action interface through which those tools are invoked. In this work, we study how the design of this interface shapes the agent’s capacity for open-ended spatial reasoning. Existing spatial agents either employ single-pass code execution, which commits to a full analysis strategy before any intermediate result is observed, or rely on a structured tool-call interface that often offers less flexibility for freely composing operations or tailoring the analysis to each task. Both designs offer limited flexibility for open-ended, complex 3D/4D spatial reasoning. We therefore propose SpatialClaw, a training-free framework for spatial reasoning that adopts code as the action interface. SpatialClaw maintains a stateful Python kernel pre-loaded with input frames and a suite of perception and geometry primitives, letting a VLM-backed agent write one executable cell per step conditioned on all prior outputs, enabling the agent to flexibly compose and manipulate perception results and adapt its analysis to both intermediate text and visual observations and the demands of each problem. Evaluated across 20 spatial reasoning benchmarks spanning a broad range of static and dynamic 3D/4D spatial reasoning tasks, SpatialClaw achieves 59.9% average accuracy, outperforming the recent spatial agent by +11.2 points, with consistent gains across six VLM backbones from two model families without any benchmark- or model-specific adaptation.
PDF链接:https://arxiv.org/pdf/2606.13673v1
