我在用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 codexWindows用户推荐走npm前提是你已经装好了Node.jsnpm install -g openai/codex安装完之后先别急着登录先在终端里跑一下codex --version如果提示找不到命令大概率是Node.js的全局bin目录没进系统PATHWindows用户去“系统环境变量-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 # 存放这次建模任务的完整需求描述在工作目录里启动Codexcd 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 环境与安装类问题速查表在各类群里看大家提问最多的就是安装和启动问题我把常见的集中整理了一下。问题现象可能原因解决方案chatgpt windows安装未完成安装包权限不足或Node环境缺失确认Node.js版本不低于18用管理员权限终端重新安装chatgpt failed to startunable to locate the codex cli binary or required runtimeCodex CLI未正确安装或系统PATH没配好重新运行npm install -g openai/codex并检查PATH环境变量chatgpt 无法加载config.toml对话无法继续配置文件语法错误或存在非法项用codex --version输出定位配置目录检查TOML格式注意引号和英文标点the model is not supported when using codex with a chatgpt account当前账号没有对应模型的使用权限更换支持该模型的账号或API Key或者修改config.toml换用当前账号可用的模型cc switch local proxy failed while handling codex endpoint /responses本地代理或端点配置有冲突请求发送的基础地址有问题检查config.toml里base_url和wire_api配置清除本地代理相关环境变量后重试第一类问题都是环境配置层面的解决起来不难难的是很多人不清楚“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基于上次的成品脚本修改速度比从零开始快非常多。这些积累越滚越多你会发现自己建模型的时间成本已经降到了过去完全不敢想的程度。
