1. Marmoset Viewer 网页嵌入 3D 模型为什么打开是黑屏Marmoset Viewer 是 Marmoset Toolbag 附带的一个网页端 3D 模型预览组件它能把你在 Toolbag 里调好的材质、灯光、相机角度打包成一个.mview文件再配合一段marmoset.js脚本嵌进 HTML 页面里浏览。适合谁用做游戏美术、电商产品展示、数字藏品预览、或者需要把模型预览页接进 AI 辅助工具链的开发者。它最大的好处是别人拿到的是可交互的预览页而不是能直接编辑的工程文件既方便查看又在一定程度上保护了源模型。但很多人第一次导出后双击 HTML浏览器里只有一片黑控制台还甩出一行红字XMLHttpRequest cannot load file:///C:/Users/Administrator/Desktop/shenmifangke.mview?thumb1. Cross origin requests are only supported for protocol schemes: http, data, chrome, https...看到Cross origin就以为是跨域其实不是。真正的原因是浏览器对file://协议下的XMLHttpRequest有严格限制.mview是通过 XHR 异步加载的直接双击本地 HTML 时这个请求被拦了模型自然加载不出来。解决办法不是改跨域头而是起一个本地 HTTP 服务器让页面通过http://localhost访问XHR 就能正常读取同目录下的.mview。我试过最省事的做法是用一个单文件静态服务器比如 mongoose 的免费二进制版双击运行后它会自动打开浏览器并列出当前目录点进你导出的 HTML 就能看到模型。不过在实际项目里我更推荐用 Python 或 Node 起服因为可以顺手把 TaoToken 的统一 Key 配置、AI 辅助脚本一起挂进同一个工作目录后面接工具链时不用来回切环境。这一篇就按完整链路走一遍从 Toolbag 导出.mview到写 HTML 嵌入到本地起服验证再到把 TaoToken 的 Key 配置进settings.json/config.toml最后给出几个真实会踩的报错和排查动作。你照着做控制台应该是干净的模型能转、能缩放、能切图层视图。2. TaoToken 前置准备统一 Key 与工作目录规划在动手写 HTML 之前先把工具链的“地基”打好。Marmoset Viewer 本身不需要联网但你要把它接进 AI 辅助工具链比如让 AI 帮你生成嵌入代码、批量改相机参数、写自动化截图脚本就需要一个统一的模型调用入口。TaoToken 在这里扮演的角色就是一个 Key 走通多家模型省得你在 Claude Code、Cline、Codex 之间来回配不同的 Base URL 和密钥。先明确三个东西后面所有配置都围绕它们Base URLhttps://taotoken.net/apiAPI Key在控制台创建形如sk-xxxxModel ID按你用的模型填比如claude-sonnet-4-5、gpt-4o之类具体以文档里的模型列表为准工作目录我建议这样规划避免路径里出现中文导致.mview加载失败这是老版本 Viewer 的经典坑D:\marmoset-demo\ ├── index.html # 嵌入页面 ├── marmoset.js # Viewer 脚本本地化 ├── scene.mview # Toolbag 导出的模型 ├── settings.json # Claude Code / 通用配置 └── config.toml # Codex / Cline 类配置注意目录名和文件名全部用英文。中文路径在部分浏览器 本地服务器的组合下会出现 404控制台报Failed to load resource: net::ERR_FILE_NOT_FOUND排查半天以为是脚本问题其实是路径编码。关于 Key 的获取去控制台创建即可创建后只显示一次记得复制保存。如果你只是本地预览其实不配 Key 也能跑 Viewer但既然目标是“接入 AI 辅助工具链”那这一步就顺手做了后面写自动化脚本时直接可用。这里有个细节TaoToken 的 API 地址是https://taotoken.net/api注意末尾不带UTM 参数配置里写干净地址就行。官网入口带归因参数但配置文件里不要带否则某些客户端会把整串当路径解析报404 Not Found。3. 可复制配置settings.json 与 config.toml 骨架这一节给可直接复制的配置片段。分两类一类是 AI 客户端的 Key 配置一类是 Viewer 的 HTML 嵌入配置。3.1 settings.jsonClaude Code / 通用 JSON 配置路径按你的客户端要求放常见是项目根目录或用户配置目录。核心三件套Base URL、Key、Model ID。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 }, permissions: { allow: [ Read, Write, Bash(python -m http.server:*) ] } }这里ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址ANTHROPIC_AUTH_TOKEN填你创建的 KeyANTHROPIC_MODEL填模型 ID。permissions.allow里我顺手放行了本地起服命令这样 AI 帮你调试时可以直接跑python -m http.server不用每次手动确认。3.2 config.tomlCodex / Cline 类配置[model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的Key model_id gpt-4o [server] host 127.0.0.1 port 8000 root D:/marmoset-demobase_url同样写https://taotoken.net/apimodel_id按需替换。[server]段是我自己加的约定用来记录本地预览服务的端口和根目录方便脚本读取。3.3 Viewer 嵌入 HTML 骨架这是核心。注意marmoset.js用本地路径.mview用相对路径!DOCTYPE html html langzh-CN head meta charsetutf-8 meta nameviewport contentuser-scalable0 titleMarmoset Viewer 预览/title script srcmarmoset.js/script /head body script marmoset.embed(scene.mview, { width: 960, height: 600, autoStart: true, fullFrame: true, pagePreset: false }); /script /body /html关键参数说明参数作用建议值width / height画布尺寸按容器调整autoStart自动加载模型truefullFrame全屏框架模式truepagePreset是否用页面预设false如果你要全屏铺满把width/height设成窗口尺寸或者用 CSS 让容器 100%。marmoset.js一定要下载到本地同目录不要直接引https://viewer.marmoset.co/main/marmoset.js否则离线或内网环境直接白屏。4. 本地起服与浏览器验证控制台无报错才算过配置写完进入验证环节。这一步的目标很明确浏览器加载.mview控制台干净模型可交互。4.1 起本地服务器Python 自带的最省事进到工作目录执行cd D:\marmoset-demo python -m http.server 8000看到Serving HTTP on 0.0.0.0 port 8000就说明起来了。如果你没装 Python用 Node 的npx serve也行npx serve -l 8000或者用前面提到的单文件静态服务器二进制双击运行它会自动打开浏览器列出目录。4.2 浏览器访问与验证动作打开http://127.0.0.1:8000/index.html按 F12 看控制台。合格的验证标准Network 面板里scene.mview状态码是200不是404或(failed)Console 面板没有Cross origin、XMLHttpRequest相关红字模型正常显示鼠标左键旋转、滚轮缩放、右键平移都生效右上角图层切换Normals / Albedo / Gloss 等能点。如果模型出来了但贴图丢失多半是.mview里引用的贴图路径问题重新导出时勾选“嵌入资源”即可。4.3 用 AI 辅助验证可选既然配了 TaoToken可以让 AI 帮你写个自动检查脚本比如用 Python 请求页面并检查.mview是否 200import requests url http://127.0.0.1:8000/scene.mview r requests.head(url) print(status:, r.status_code) assert r.status_code 200, mview 未正确加载把这段丢给 AI 客户端让它补全异常处理和日志比手写快。这也是统一 Key 的价值同一个配置写脚本、改 HTML、查报错都能用。5. 本篇常见报错排查401、local proxy failed、reading choices这一节对照真实会遇到的报错逐个给排查方向。报错一401 Unauthorized出现在 AI 客户端调用时。原因通常是 Key 没填、填错或者 Base URL 写成了带 UTM 的完整官网地址。检查settings.json里的ANTHROPIC_AUTH_TOKEN是否是sk-开头ANTHROPIC_BASE_URL是否是https://taotoken.net/api不带参数。改完重启客户端。报错二local proxy failed/connection refused本地起服没成功或者端口被占。先确认python -m http.server 8000的窗口还开着再换端口试8001。如果客户端配置里写了host 127.0.0.1浏览器也要用127.0.0.1而不是localhost两者在某些系统上解析不同。报错三Error reading choices/reading choices多出现在流式响应解析时通常是客户端版本和 API 返回格式不匹配。先确认 Model ID 填对再升级客户端到最新版。如果还报把model_id换成文档里明确支持的型号。报错四Cross origin requests are only supported for...这就是开篇那个。根因是用了file://直接打开。解决必须走http://即本地起服。不要试图改浏览器跨域设置治标不治本。报错五模型黑屏但控制台无报错检查.mview是否和 HTML 同目录marmoset.embed里的路径是否一致。另外确认marmoset.js是本地文件且版本匹配版本不匹配会静默失败。报错六OAuth相关跳转失败如果你用的是需要 OAuth 的客户端确认回调地址没被本地服务器端口占用。把预览服务和 OAuth 回调分不同端口比如预览 8000、回调 8080。排查顺序建议先看 Network 里.mview的状态码再看 Console 第一条红字最后才怀疑配置。大部分问题都在前两步暴露。6. 把预览页接进工具链统一 Key 的长期用法模型能预览只是第一步。真正省时间的是把这条链路固化下来Toolbag 导出 → 本地起服 → AI 辅助改页面 → 自动截图/校验。统一 Key 的好处在这里体现得最明显。你不需要为每个工具单独申请密钥settings.json和config.toml里都指向同一个https://taotoken.net/api换模型只改model_id一行。写批量处理脚本时直接读环境变量export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYsk-你的Key然后脚本里统一引用避免硬编码。几个实用技巧把marmoset.js和常用.mview放同一个模板目录新项目直接复制不用每次找脚本HTML 里的width/height用变量注入方便批量生成不同尺寸的预览页用 AI 客户端生成一个build.py自动把 Toolbag 导出目录里的.mview批量套进 HTML 模板本地服务器用nohup或后台方式常驻避免每次手动起。如果你要长期做编码和 Agent 类任务可以考虑用 Coding Plan 把额度固定下来比按次调用更可控。验证模型效果时直接用模型对话页面测一下返回是否正常再进正式配置。最后留一个我踩过的坑.mview文件别放桌面根目录某些系统权限会拦。放项目子目录路径全英文基本就不会再遇到黑屏。控制台干净、模型能转这条链路就算通了。