AI智能体驱动SketchUp：从Ruby API到自动化建模实战

我在用AI智能体操作SketchUp之前，一直觉得“让ChatGPT帮我在SU里建模”只是噱头。直到自己把Codex、Claude Code这种编程型智能体真正接到SketchUp的Ruby API上，才发现这条路完全走得通，而且效率高得惊人。如果你手里恰好有一堆重复性的建模任务，或者经常因为写不好Ruby脚本而卡在某个建模流程里，这篇内容基本就是给你准备的。

这篇文章我会从底层逻辑讲起，把“AI智能体如何操作SketchUp”这件事彻底拆开。不管你是用Codex、Claude Code、Workbuddy还是OpenClaw，只要理解了核心思路，都能把SU变成你的私人建模工具，让它按你的自然语言指令干活。

1. 整体思路：为什么用AI智能体操作SketchUp这件事成立

1.1 核心问题：SketchUp到底能不能被外部程序控制

先说一个很多SU用户不知道的事实：SketchUp自带一套完整的Ruby API，它能做到的事情远比你在界面上点鼠标要多得多。从创建几何体、修改材质、组织组件，到批量导出、生成报告、控制相机视角，Ruby API几乎覆盖了整个建模流程。

这意味着从技术层面来说，SketchUp并不只是一个“给人手搓”的建模软件，它同时也是一个可以通过脚本驱动的自动化平台。问题在于，SU的Ruby API文档虽然齐全，但学习成本不低，很多设计师并不会天天写Ruby代码。

这时候AI智能体就派上用场了。Codex、Claude Code这类编程型智能体，天生擅长读文档、写代码、跑命令、看报错，本质上就是把“自然语言需求”变成“可执行代码”的翻译器。你把“在原点建一个三米乘两米、高一米的盒子”丢给它，它能直接生成对应的Ruby脚本，再把脚本喂给SketchUp执行，建模就完成了。

1.2 为什么选择Codex这类编程智能体而不是普通ChatGPT

普通网页端的ChatGPT也能写Ruby脚本，但它只能输出文字，没法真正帮你运行、调试、再执行。流程一旦出错，你得自己复制代码、粘贴到SU的Ruby控制台、看报错、再回去问AI，一来一回非常折腾。

Codex和Claude Code这类工具不一样。它们是运行在你本机的智能体Agent，不只负责写代码，还能执行命令、读写文件、调用命令行工具。以Codex为例，它可以帮你启动一个SketchUp自动化脚本、读取生成的日志、根据报错自动修正代码、再重新执行一次。这已经接近“闭环自动化”了。

用Agent操作SketchUp还有一个隐藏优势：它可以维护上下文。我做复杂建模任务的时候，经常需要连续修改十几个细节参数，普通ChatGPT每次对话都要重新解释背景，而Codex在工作目录里保留上下文，改完一轮还能记住上一轮的结构策略，连续迭代非常顺滑。

1.3 一套思路，四款Agent通用

Codex能做这件事，Claude Code当然也能做，因为它们的核心能力是一样的：读文件、写代码、执行命令、看结果。Workbuddy和OpenClaw这类偏自动化流程的智能体，同样支持自定义脚本执行，只不过侧重点不同。

我这篇文章的实操部分主要围绕Codex展开，但底层的逻辑和方法论，你可以原封不动搬到Claude Code上。唯一要改的只是你习惯用的那个Agent的命令行入口而已。Claude Code用claude命令，Codex用codex命令，其余的理解逻辑几乎没有差别。

2. 环境准备：先把Codex和SketchUp两边的“接口”打通

2.1 安装Codex CLI，绕开最常见的几个坑

Codex目前主要靠CLI方式使用，安装方式取决于你的操作系统。macOS用户用Homebrew最省事：

brew install codex

Windows用户推荐走npm，前提是你已经装好了Node.js：

npm install -g @openai/codex

安装完之后先别急着登录，先在终端里跑一下：

codex --version

如果提示找不到命令，大概率是Node.js的全局bin目录没进系统PATH，Windows用户去“系统环境变量-Path”里加一下nodejs的全局路径就能解决。很多人在这一步卡住，其实跟Codex本身没关系，是Node环境没配好。

登录验证用ChatGPT账号就行，首次运行codex会引导你完成登录。这里有一个我踩过的坑：如果你已经通过ChatGPT的Plus或Pro账号登录，它能用的模型和额度取决于账号权限，组织形式是通过API Key直连还是ChatGPT账号登录，会影响后面能选哪些模型。建议一开始就用比较灵活的账号方案，避免后续因为模型权限问题反复折腾。

2.2 配置Agent的模型与API端点

Codex的配置文件默认路径是~/.codex/config.toml。如果你跟我一样经常用多种模型，甚至接第三方模型，可以重点看这几项配置：

model = "gpt-5-codex" temperature = 0.7 [model_providers] # 自定义API端点示例 thirdparty = { name = "thirdparty", base_url = "https://your-api-endpoint/v1", wire_api = "responses" }

如果要用DeepSeek这类开源模型的API，很多人会走自定义endpoint的方式接入，这样成本低、自由度也高。要注意的是，如果端点的API协议是/chat/completions而不是/responses，你需要在代码里手动把wire_api改成对应的协议类型，否则请求会直接报错。

Claude Code这边的配置也类似，claude config set model ...可以临时切换模型，也可以在~/.claude/settings.json里写默认配置。总之，让Agent先能正常工作，后面调用SketchUp才有戏。

2.3 SketchUp侧的准备：确认Ruby环境和执行入口

SketchUp的Ruby API是内置的，不需要单独安装Ruby运行时。但是你要弄清楚两件事：第一，SU安装目录里有没有对应的Ruby解释器入口；第二，SketchUp能不能以带参数的方式启动并自动运行你指定的Ruby脚本。

Windows环境下的常见路径长这样：

C:\Program Files\SketchUp\SketchUp 2023\SketchUp.exe

确认安装好后，建议先在SU的扩展程序菜单里打开“Ruby控制台”，输入一行最简单的命令试试：

UI.messagebox("Hello from Ruby API")

能弹窗说明Ruby API整体是通的，后面跑复杂脚本就有了基础保障。这一步不要跳过，因为很多人后面脚本不生效，回头排查才发现是Ruby环境本身就没跑起来。

2.4 让Agent能“看见”SketchUp：工作目录的组织方式

AI智能体操作本地软件，本质是在一个工作目录里读写文件和跑命令。所以我一般会建立一个专门的SU自动化项目目录，如下：

su_agent/ ├── scripts/ # 存放每次生成的Ruby脚本 ├── output/ # 存放建模结果、导出的DWG/图片 ├── logs/ # 存放运行日志 └── prompt.md # 存放这次建模任务的完整需求描述

在工作目录里启动Codex：

cd su_agent codex

这样做的好处是，Codex能自动读取目录里的prompt.md和已有脚本，快速理解你当前要做什么。比如我会在prompt.md里写清楚“这次需要用Ruby脚本创建一个参数化书架，层板间距可变，输出到output目录”，Codex一进来就知道背景，直接进入干活状态，而不是反复问你。

3. 核心实现：让Codex通过Ruby API驱动SketchUp建模

3.1 SketchUp Ruby API的入门必备知识

想真正让AI写出可跑通的SU脚本，你自己至少得理解Ruby API的几个核心概念。不然你连AI生成的代码对不对都判断不了，出了问题也不知道怎么描述给AI听。

最基本的几个对象：

• Sketchup.active_model：当前打开的模型文件，一切的入口。
• model.entities：模型里的所有实体集合，建组件、加面、加线都是往这个集合里加。
• Geom::Point3d：三维坐标点，Geom::Point3d.new(x, y, z)可以创建一个点。
• entities.add_group：把一组实体包成一个组，类似于SU界面里“创建组”的操作。
• entities.add_face：根据点序列创建一个面，注意这些点必须在同一个平面内，而且法线方向要正确。

举一个最简单的例子：创建一个面再拉伸成体。

model = Sketchup.active_model entities = model.entities # 画一个矩形面 pts = [ Geom::Point3d.new(0, 0, 0), Geom::Point3d.new(3000, 0, 0), Geom::Point3d.new(3000, 2000, 0), Geom::Point3d.new(0, 2000, 0) ] face = entities.add_face(pts) # 向上拉伸1000mm face.pushpull(1000)

这段代码能直接建出一个3米乘2米、高1米的盒子。pushpull就相当于SU里的“推拉”工具，但用代码写就是一行，而且可以精准控制数值。

3.2 让Codex写SU脚本的工作流

我自己用下来效果最好的流程总共四步，缺一步都不行。

第一步，把需求写清楚。这里不是跟AI闲聊，而是要像给朋友发工作brief一样，把尺寸、数量、层级关系、连接方式全部说清楚。如果你连自己要什么都描述不清楚，智能体也没法帮你建模。

第二步，让Codex先写脚本，不急着执行。我会让它先阅读几行SU Ruby API的示例代码，再结合我的需求生成脚本。Codex本身能联网读取文档，但很多时候它也会凭训练记忆生成Ruby代码，如果遇到不存在的API，它会跑出错误。提前跟它强调“请使用稳定版本的API，不要用已废弃方法”，能少踩很多坑。

第三步，执行脚本。如果是在SketchUp里手动执行，把生成的.rb文件放到SU能识别的位置，然后用Ruby控制台的load命令加载：

load "C:/path/to/your/script.rb"

如果是希望SU一启动就自动运行指定脚本，可以用命令行参数：

"C:\Program Files\SketchUp\SketchUp 2023\SketchUp.exe" -RubyStartup "C:\su_agent\scripts\create_shelf.rb"

这种方式适合批量自动化，不需要手动打开SU。只要你确认了脚本逻辑没问题，几十个模型文件也能自动化处理。

第四步，看报错反馈，让AI自己修。Codex最大的价值就在这里，脚本跑了报错，直接把报错信息丢回去，它能很快定位是坐标问题、API调用问题还是数据类型问题，修完继续跑。这个循环就是Agent生产力爆发的关键。

3.3 完整实操案例：用自然语言让Codex生成一个参数化楼梯

我拿一个自己实际跑过的案例来演示，需求是这样：一个直跑楼梯，宽度1200mm，高度3000mm，每级台阶高150mm，踏步深280mm，带两侧扶手，扶手高度900mm。

我先把这个需求原样告诉Codex，加上工作目录路径，让它直接在scripts目录生成Ruby脚本。它生成的脚本核心逻辑大概是这样的：

model = Sketchup.active_model entities = model.entities group = entities.add_group ent = group.entities width = 1200.mm rise = 150.mm depth = 280.mm height = 3000.mm total_steps = (height / rise).to_i # 创建台阶 (0...total_steps).each do |i| x = i * depth y = 0 z = i * rise pts = [ Geom::Point3d.new(x, y, z), Geom::Point3d.new(x + depth, y, z), Geom::Point3d.new(x + depth, y + width, z), Geom::Point3d.new(x, y + width, z) ] face = ent.add_face(pts) face.pushpull(rise) end

这段代码的奇妙之处在于，台阶数量是通过height / rise自动算出来的，所以如果你改了总高度，台阶数也跟着变，不需要手改每一阶。这就是参数化建模的基本思想，用代码定义规则，而不是手工创建几何体。

运行之后，模型里出现了一个带20级台阶的楼梯主体。接下来我又追加需求，让Codex把手扶栏杆也加上。它会在台阶两侧生成连续的栏杆线，然后沿路径拉伸成管状。这里用到的核心是add_line和followme，虽然逻辑比台阶复杂一点，但AI处理起来毫无压力。

3.4 把常规建模操作“翻译”成AI可理解的参数链条

使用过程中我逐渐意识到，能不能让AI建出理想的模型，很大程度取决于你能不能把“我想做一个XX”翻译成AI能理解的需求链条。同样是做一扇窗，你说“做一扇好看的窗户”，AI只能凭感觉发挥；你说“做一个宽1200mm、高1500mm的平开窗，窗框型材宽度60mm，中间有一道横梃，距底部500mm，带玻璃材质透明效果”，它就能非常准确地执行。

所以我在需求文档里会刻意训练自己的写作格式，按照“整体尺寸-子构件-相对位置-材质效果-输出要求”这五段来写。好的需求描述，能让Codex一次生成的脚本通过率提升到八成以上。

4. 复杂建模与多Agent协作的进阶玩法

4.1 把大型建模任务拆解成小任务，逐层交给AI

很多人第一次用AI建复杂模型，习惯一上来就让它“建一栋别墅”，结果不是AI崩了就是模型乱套。原因很简单：Agent能处理的上下文长度有限，太复杂的模型会有大量几何计算和对象引用，单次生成全盘脚本很容易出错。

正确做法是像写代码一样模块化。我自己做别墅模型时，会拆成外墙、楼板、门窗、屋顶、室内隔断五六个子任务，一个子任务跑完并确认没问题后，再继续下一个。Codex跑大任务时会自动维护上下文，但它依然更擅长一个个小目标地推进。

命令行的好处在这里再次体现出来。你可以把每个子任务生成一个独立的Ruby脚本，按顺序加载运行。比如：

codex exec "生成外墙轮廓，注意窗洞位置留出参数" codex exec "基于外墙数据生成门窗"

每个脚本独立维护，整个工程出问题时也容易定位是哪个环节出了问题。

4.2 Codex与Claude Code共用一套SU工作流

我实际工作中经常混合使用Codex和Claude Code，两家模型对Ruby语法的理解略有不同，思路也不一样。有时候Codex写出的脚本逻辑不对但语法漂亮，Claude Code写出的代码笨一点却能跑通。所以我会让两个Agent轮流改同一段脚本，交叉验证。

具体操作也很简单：Codex生成的脚本存在scripts目录里，把项目路径换到Claude Code里作为工作目录，让它读取同一份脚本做review或修复。Claude Code自带claude -p "请审查这个Ruby脚本并修复问题"这种非交互式命令，非常适合流程化调用。

4.3 Agent + SU批量处理：从单模型到生产流水线

如果你经常处理大量模型，比如一个文件里有100个户型需要批量生成并导出图片，用Agent操作SU就能实现接近“生产流水线”的效果。思路是这样：先用Codex写一个能接受参数的Ruby模板脚本，再写一个批处理脚本循环调用SU命令行，把每个户型的数据传给模板。

例如命令行可以这样：

for i in {1..100}; do "C:\Program Files\SketchUp\SketchUp 2023\SketchUp.exe" -RubyStartup "C:\su_agent\scripts\generate_unit.rb $i" done

脚本内部读取传入参数，根据户型编号从数据库里加载对应的尺寸信息，动态生成模型并导出图片到output目录。这套流程手动跑可能得熬几个夜，但Agent把脚本写出来后，剩下的事情就是挂着等结果。

4.4 与其他软件的数据互通：DWG、OBJ、图片导出

SketchUp最强的能力之一就是格式转换，AI同样能驱动这部分。让Codex调用model.export方法，可以把模型导出为DWG、DXF、OBJ、DAE等多种格式。比如我有个场景需要在某款渲染器里做渲染，就写了个脚本批量把SU模型导出为OBJ，同时生成材质清单，整个流程非常顺畅。

调用方式大概是这样：

model = Sketchup.active_model status = model.export("C:/output/model.obj")

这里有一个细节值得注意：导出格式是否带材质和贴图信息，取决于插件和导出选项。如果你发现导出的OBJ在别的软件里材质丢失，先检查SU端导出的插件版本，再检查是否需要在导出前强制绑定材质到面。

5. 常见问题与排查技巧实录

5.1 环境与安装类问题速查表

在各类群里看大家提问最多的就是安装和启动问题，我把常见的集中整理了一下。

第一类问题都是环境配置层面的，解决起来不难，难的是很多人不清楚“Codex的配置到底放在哪”。这里我建议第一次装完先跑codex --version，如果正常就再跑codex --help，看它默认的配置路径在哪，后面所有问题都能顺着这个路径排查。

5.2 运行脚本时的常见问题

脚本报错是必然会遇到的，关键是要学会看报错信息。SU的Ruby控制台报错一般会给出行号和错误类型，比如undefined method 'pushpull' for nil，意思是你调用了pushpull的对象是空的。

最常踩的坑是“点不在同一平面导致add_face返回nil”。如果你给出的四个点不是严格的矩形且法线有偏差，SU不会自动帮你纠正，它会直接返回一个空对象，后续所有操作全部失效。解决办法是在生成点之前，手动把坐标的某一维设置为常量，比如所有点的z都是0，保证它们在同一个平面上。

另一个高频问题是单位换算。SU内部默认单位是英寸，但你直接写3000并不代表3000毫米。我一开始没注意这个，导出的模型尺寸完全对不上。正确的做法是给数字加单位方法：3000.mm、1.2.m、500.cm，这样SU会帮你自动换算成英寸。

5.3 智能体“幻觉”API的应对思路

AI生成代码有个特点，它偶尔会“幻觉”出一些根本不存在或者已经废弃的API。比如有些方法的用法已经变了，但AI记忆里的还是老版本。这种情况不要直接改代码死磕，更好的做法是让Agent先把SU的Ruby API文档查出来再写。我通常会在需求里明确说“先总结你需要用到的API方法，标注对应的Ruby版本，再开始写脚本”。

如果它还是写出了不存在的函数，就把报错原样丢给它，同时补充一句“这个API在我的SketchUp版本里可能不存在，请换一种实现方式”。这样既能纠正问题，又能避免它反复在同一个坑里打转。

5.4 日志与调试技巧：别让SU“静默失败”

SU执行脚本出错时，有时候并不会弹窗提示，尤其是用命令行自动运行时，错误会直接写进日志文件。所以我强烈建议在所有脚本第一行加上一个日志打开指令：

model = Sketchup.active_model # 打开Ruby控制台日志，方便排查 Sketchup.send_action("showRubyPanel:")

再加一个兜底打印：

puts "脚本开始执行"

以后跑命令行自动化时，这些输出都会被捕获到日志文件里，方便Agent和人都能快速定位问题。别小看这两行代码，在批量执行100个模型时，它们能帮你从无止境的失败中迅速筛选到底哪些户型的数据有问题。

结尾：一点个人经验

在我自己的实践里，AI操作SketchUp这件事，真正的门槛从来不是技术，而是思维方式的转换。你不能再像以前一样，打开SU手动画线、推拉，而是要把每一个动作都拆解成“参数-几何体-操作”的逻辑链条。刚开始这么做会很别扭，但一旦习惯，你会发现自己对建模的理解反而更深了。

我踩过的最大的坑是：一开始过度相信AI生成的脚本，跑完也不检查模型尺寸，结果一个细节导致整批模型全部报废。现在不管Codex生成的脚本看起来多完美，我都会留一道工序，专门用脚本检查模型的边界框尺寸、面数、组件数量，确认无误后再进入下一步。这套流程已经帮我稳定输出了一大批模型，也让AI从“玩具”变成了真正能扛活的帮手。

最后再分享一个小技巧：每次建模任务结束后，把你和Agent的完整对话摘要和最终脚本归档到专门目录，形成属于自己的“提示词库”。下次遇到类似需求，直接让AI基于上次的成品脚本修改，速度比从零开始快非常多。这些积累越滚越多，你会发现自己建模型的时间成本，已经降到了过去完全不敢想的程度。