快速上手

1. 安装

在下载页选择适合你系统的安装包并运行：Windows 是安装版或免安装版，macOS 是 Apple Silicon 或 Intel 的磁盘映像。

两个平台的安装包目前都没有代码签名，所以首次启动需要确认一次——Windows 上是更多信息 → 仍要运行，macOS 上是右键点击 → 打开。之后它和其他应用没有区别。

不需要账号，也没有注册环节。起始素材包（家具、全景图、材质，全部为 CC0）就在应用内，因此第一个场景可以在断网状态下完成。

2. 连接智能体

启动 Cuberta。内置服务器就绪后，窗口标题会显示 MCP listening on 7345。

点击右上角的 Copy connect command。对 Claude Code 来说，剪贴板里会是这样一行，把它粘贴到终端：

claude mcp add --transport http cuberta http://127.0.0.1:7345/mcp \
  --header "Authorization: Bearer <token>" --scope user

然后在任意文件夹启动智能体。正是 --scope user 让这个服务器在任何目录都可用，而不只是在你当时所处的那一个。

其他 MCP 客户端的连接方式相同：地址 http://127.0.0.1:7345/mcp（Streamable HTTP），请求头 Authorization: Bearer <token>。令牌在首次启动时生成，保存在你自己的配置文件里——Windows 为 %APPDATA%\Cuberta\config.json，macOS 为 ~/Library/Application Support/Cuberta/config.json。

服务器只监听本机，令牌也从不显示在界面上：窗口会被截图和录屏，所以按钮直接把它放进剪贴板。

3. 第一条指令

智能体通过工具描述和五份可以自行阅读的指南来学习这个编辑器。先让它读对应的指南，是改进一条指令最有效的办法：

• 「先读 cuberta://guide/scenes，然后搭一间 6×4 米的温馨客厅，要有沙发、茶几和傍晚的暖光。完成后给我一张渲染图。」
• 「先读 cuberta://guide/world。搭一座小镇：带环路的街网、坡屋顶的独栋住宅、人行道边的路灯和树木，黄昏的光线。然后用场景检查器检查一遍，并给我街道视角和俯视的两张图。」
• 「载入参考板上的图片，尽可能还原照片里的那条街；看不见的部分你来补。」

每一步结束时都要一张渲染图。这是在返工成本还很低的时候发现理解偏差的最快方式。

4. 它工作的时候

智能体干活时你并没有被锁在外面。你的每个操作走的都是同一批命令，因此撤销历史和时间轴是共用的。

• 点击任意物体——智能体会知道「人类选中了它」。
• W / E / R 用操作器移动、旋转、缩放；按住 Ctrl 吸附。
• 右键 + WASD 飞行浏览。
• 画区域来指定哪里能建、哪里不能建。
• 从材质浏览器把贴图直接拖到物体上即可替换。
• 底部的时间轴可以把场景回滚到任意历史步骤；Ctrl+Z 撤销最后一步，无论那是谁做的。
• F1 列出全部快捷键。

5. 保存与导出

File → Save 会写出一个工程文件夹：scene.json，旁边是 meshes/（烘焙后的几何体）、renders/（智能体拍的图）和 refs/（你的参考板）。File → Open project… 打开该文件夹里的 scene.json。

File → Export to GLB… 输出一个内嵌全部贴图的 .glb。File → Export to FBX… 以同样方式输出二进制 FBX，坐标轴和单位已按 Unity、Unreal、Maya 和 Blender 设好。导出在独立进程中进行，场景再重窗口也不会卡住。

导出大场景之前，值得让智能体先烘焙、合并并切成瓦片：相关工具就在同一套里，成品在引擎中的流式加载会顺畅得多。

6. 遇到问题时

标题栏没有出现「MCP listening」。7345 端口可能被别的程序占用。关掉它，再重启 Cuberta。

智能体看不到工具。确认连接命令里带了 --scope user，并且客户端在那之后重启过。在 Claude Code 里，claude mcp list 会显示 Cuberta 是否已注册、是否连得上。

画面全白或视口空白。视口需要 WebGL 2。更新显卡驱动几乎总能解决。

导入的模型尺寸不对。模型都会归一到米制、轴心置于底部，尺寸对不上通常说明源文件声明了别的单位——让智能体重新缩放，或在指令里直接写清尺寸。

还是不行？写信告诉我们：你的系统、应用版本，以及当时的操作。