Codex 接入 Blender 绘制3D模型

1. 前言

这次接入分为两层核心目标：

1. 把 CLI-Anything 作为 Codex 可发现的 skill 接入，让 Codex 识别这套工作流；
2. 部署 CLI-Anything 内置的 cli-anything-blender 工具，打通本机 Blender 的命令行调用链路。

简单来说：

• Codex skill 层：让 Codex 理解 CLI-Anything 工作逻辑；
• cli-anything-blender 层：提供 Blender 命令行调用能力；
• 本机 blender.exe：执行实际的渲染、预览等任务。

我们先来看看最终效果吧(想快速安装的,可以看最后有个快速方法安装)

2. 本地环境信息

本次实操的核心环境路径：

• CLI-Anything 仓库：D:\浏览器下载\CLI-Anything
• Blender 可执行文件：D:\Blander\blender.exe
• Python 环境：C:\Users\旷世\AppData\Local\Programs\Python\Python313\python.exe
• Codex skill 安装目录：C:\Users\旷世\.codex\skills

仓库已内置核心文件，无需从零开发：

• blender\agent-harness\（Blender 命令行封装）
• codex-skill\scripts\install.ps1（Codex 技能安装脚本）
• cli-hub\（CLI 管理与预览工具）

如果想自己下载就去github自己下载:
-https://github.com/HKUDS/CLI-Anything

为什么用这个CLI来接入,这个是我用过比较好用的开源项目了,他支持blender的所有接口

3. 第一步：确认 CLI-Anything 内置 Blender 适配层

验证仓库目录结构，确认以下路径存在(这是我的文件下载的存放路径,你们以你们的实际路径为准)：

• D:\浏览器下载\CLI-Anything\blender\agent-harness
• D:\浏览器下载\CLI-Anything\codex-skill

核心结论：

1. Codex 接入逻辑已实现，无需自定义安装脚本；
2. Blender CLI 封装已完成，无需从零设计命令。

blender\agent-harness\setup.py 已声明可安装命令：

cli-anything-blender=cli_anything.blender.blender_cli:main

执行 pip install -e . 后，系统会生成 cli-anything-blender 全局命令。

4. 第二步：安装 Codex Skill

执行安装脚本

powershell -NoProfile -ExecutionPolicy Bypass -File .\codex-skill\scripts\install.ps1

脚本核心作用

将 CLI-Anything 的技能资源复制到 Codex 技能目录：C:\Users\旷世\.codex\skills\cli-anything，包含：

• 文档类：HARNESS.md、commands/*.md、guides/*.md
• 脚本类：repl_skin.py、preview_bundle.py、skill_generator.py

关键操作

安装完成后必须重启 Codex，让 Codex 重新扫描技能目录，加载新接入的 CLI-Anything 能力。

5. 第三步：配置 Blender 系统路径

问题根源

cli-anything-blender 通过 shutil.which("blender") 查找 Blender 可执行文件（源码路径：blender_backend.py:14），默认不会扫描 D:\Blander\blender.exe。

解决方案

将 D:\Blander 加入用户环境变量 PATH：

1. 读取当前用户 PATH；
2. 检查 D:\Blander 是否存在，不存在则追加；
3. 为当前 Shell 临时补全 PATH，确保立即生效。
   我的blender安装在D盘,所以可以在环境变量里制定路径:
   此电脑 → 右键 属性 → 高级系统设置 → 环境变量
   (或Win + R输入sysdm.cpl)
   
   
   双击path进入环境变量,查看我的blender(这里是我开始安装blender时写错了文件夹名称)安装位置是否存在,不存在就新建一个加进去,以你实际的路径为准
   

验证命令

where.exe blender  # 验证路径解析
blender --version  # 验证版本（本次为 Blender 4.0.2）

6. 第四步：安装 Blender CLI 封装层

进入目录

cd D:\浏览器下载\CLI-Anything\blender\agent-harness

执行可编辑安装

python -m pip install -e .

安装说明

-e（editable install）特性：

1. 将 cli-anything-blender 命令安装到 Python Scripts 目录；
2. 源码修改后无需重新安装，立即生效。

验证命令

cli-anything-blender --help  # 确认命令可用

7. 第五步：安装 cli-hub 管理工具

cli-hub 负责 CLI-Anything 的预览、管理能力（非必需，但建议安装）：

进入目录

cd D:\浏览器下载\CLI-Anything\cli-hub

解决编码问题后安装

Windows 默认编码为 GBK，直接安装会触发 UTF-8 解码错误，需临时指定编码：

$env:PYTHONUTF8='1'
python -m pip install -e .

8. 第六步：全链路真实验证

验证流程

执行完整的 Blender 渲染链路：

1. 新建 scene JSON → 2. 添加几何体 → 3. 创建并绑定材质 → 4. 添加相机/光源 → 5. 生成渲染脚本 → 6. 调用 Blender 后台执行。

测试目录

C:\Users\旷世\Documents\Codex\2026-06-20\hkuds-cli-anything-https-github-com\outputs\blender-cli-test

核心产出文件

• scene.blend-cli.json（场景配置）
• _render_script.py（渲染脚本）
• render.png（最终渲染图）

验证价值

拆分问题定位维度：

1. CLI 层是否能正确生成 Blender 脚本；
2. Blender 层是否能执行脚本并输出结果。

9. 第七步：修复 Windows 中文路径兼容问题

首次执行触发 2 个典型 Windows 问题，以下是修复方案：

9.1 脚本文件编码问题

问题描述

生成的 _render_script.py 包含中文路径，文件写入未指定 UTF-8，Blender 读取时解码失败。

修复代码

修改 render.py:220：

# 原代码
# with open(script_path, "w") as f:
# 修复后
with open(script_path, "w", encoding="utf-8") as f:

9.2 Windows 反斜杠转义问题

问题描述

路径中的 \U 被 Python 误认为 Unicode 转义符，导致脚本报错。

修复代码

在 bpy_gen.py:12 新增安全字符串生成函数：

def _py_string(value: Any) -> str:
    return json.dumps(str(value), ensure_ascii=False)

应用场景

将以下路径拼接逻辑替换为安全写法：

• HDRI 路径加载（bpy_gen.py:152）
• 渲染输出路径（bpy_gen.py:540）
• 渲染完成日志输出（bpy_gen.py:560）

10. 第八步：修复 Blender 输出解码问题

问题现象

preview capture 功能触发 UnicodeDecodeError: 'gbk' codec can't decode，原因是 Python 读取 Blender 输出时使用系统默认编码（GBK）。

修复方案

统一设置 Blender 子进程输出编码为 UTF-8，修改 blender_backend.py：

• 30 行、56 行：添加 encoding="utf-8"、errors="replace"
• 85 行：临时脚本写入时指定 encoding="utf-8"

核心代码示例：

# 子进程调用示例
subprocess.run(
    ["blender", "--background", "--python", script_path],
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    encoding="utf-8",
    errors="replace"
)

11. 第九步：修复 Windows 符号链接权限问题

问题现象

执行 preview live start 时触发 WinError 1314，原因是 Windows 未开启开发者模式/终端无创建符号链接权限。

修复逻辑

修改 preview.py:215，实现“符号链接失败时自动降级”：

1. 尝试创建 current -> bundle_dir 符号链接；
2. 失败则复制 bundle 到 current 目录，并写入 current_target.txt 记录原路径。

核心价值：无需管理员权限/开发者模式，保持 current/manifest.json 访问逻辑不变。

12. 第十步：全链路最终验证

12.1 命令层验证

cli-anything-blender --help
cli-hub --help
where.exe blender

12.2 真实渲染验证

cli-anything-blender --json --project scene.blend-cli.json render execute render.png --overwrite
blender --background --python _render_script.py

验证结果：成功生成 render.png，无空白/报错。

12.3 预览功能验证

# 生成预览包
cli-anything-blender --json --project scene.blend-cli.json preview capture --recipe quick
# 启动实时预览
cli-anything-blender --json --project scene.blend-cli.json preview live start --recipe quick --mode manual
# 单元测试
python -m pytest cli_anything\blender\tests\test_core.py -q

测试结果：165 个用例全部通过。

13. 接入成果总结

已打通完整链路：
Codex → CLI-Anything skill → cli-anything-blender → blender.exe

解决的核心 Windows 兼容问题：

1. Blender 路径未加入系统 PATH；
2. 中文路径/反斜杠导致脚本解码失败；
3. 无权限创建符号链接导致实时预览失效。

当前链路状态：命令可执行、Blender 可调用、脚本可生成、渲染可输出、预览可工作。

14. 日常使用指南

14.1 前置操作

重启 Codex，让 Codex 加载新安装的 CLI-Anything 技能。

14.2 核心命令

# 查看帮助
cli-anything-blender --help

# 新建场景
cli-anything-blender scene new -o scene.blend-cli.json

# 生成预览
cli-anything-blender --project scene.blend-cli.json preview capture --recipe quick

# 启动实时预览
cli-anything-blender --project scene.blend-cli.json preview live start --recipe quick --mode manual

# 预览管理（cli-hub）
cli-hub previews inspect <预览目录>
cli-hub previews html <预览目录>  # 生成 HTML 预览页
cli-hub previews watch <会话目录> --open  # 实时监控并打开预览

15. 源码修改清单

为适配 Windows 环境，共修改 4 个核心文件：

文件路径	修改点	解决问题
blender/agent-harness/cli_anything/blender/utils/bpy_gen.py:12	新增 _py_string 函数，安全生成路径字符串	中文路径/反斜杠转义
blender/agent-harness/cli_anything/blender/core/render.py:220	脚本写入时指定 encoding="utf-8"	脚本编码解码错误
blender/agent-harness/cli_anything/blender/utils/blender_backend.py	统一子进程输出编码为 UTF-8	Blender 输出解码失败
blender/agent-harness/cli_anything/blender/core/preview.py:215	符号链接失败时自动降级为文件复制	Windows 无符号链接权限

16. 源码目录迁移/删除说明

16.1 初始限制（不可删除）

初期使用 pip install -e .（可编辑安装），Python 仅创建源码目录的引用，未复制完整代码到 site-packages，删除源码目录会导致命令失效。

16.2 转换为独立安装（可删除源码）

步骤 1：清理残留

删除 Python site-packages 中残留的临时目录（如 ~lick、~lick-8.4.1.dist-info）。

步骤 2：卸载可编辑版本

python -m pip uninstall -y cli-anything-blender cli-anything-hub

步骤 3：重新安装为普通包

$env:PYTHONUTF8='1'
# 不更新依赖，仅安装包本体
python -m pip install --no-deps "D:\浏览器下载\CLI-Anything\blender\agent-harness"
python -m pip install --no-deps "D:\浏览器下载\CLI-Anything\cli-hub"

16.3 验证独立安装

# 检查安装状态（无 Editable project location 即为成功）
python -m pip show cli-anything-blender cli-anything-hub

# 脱离源码目录验证命令
cd ~  # 切换到非源码目录
cli-anything-blender --help
cli-hub previews inspect <预览目录>

16.4 最终结论

完成上述步骤后，D:\浏览器下载\CLI-Anything 源码目录可安全删除，原因：

1. Codex skill 已复制到 C:\Users\旷世\.codex\skills\cli-anything；
2. cli-anything-blender/cli-hub 已安装到 Python site-packages；
3. 全链路验证脱离源码目录仍可正常运行。

17. 最终状态

组件	状态	依赖关系
Codex skill	独立存在	无（已复制到 Codex 目录）
cli-anything-blender	独立存在	仅依赖 Python 环境
cli-hub	独立存在	仅依赖 Python 环境
blender.exe	独立存在	已加入系统 PATH
CLI-Anything 源码目录	可删除	无运行依赖

---

18. 最快方法(AI安装法)

提示词:

HKUDS/CLI-Anything帮接入这个CLI,并接入我电脑的blender,你看可以吗,我已经下载好在D:\浏览器下载\CLI-Anything

然后AI就直接帮你接入了

19. 测试绘画

---

提示词:/CLI-Anything 帮我用blender画一个哆啦A梦

---

总体来说,该CLI建设复杂的3D建模效果不咋滴,但绘制2D和建筑这些有棱有角的比较擅长