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?thumb=1. 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 URL：
https://taotoken.net/api - API Key：在控制台创建，形如
sk-xxxx - Model 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.json（Claude 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填你创建的 Key，ANTHROPIC_MODEL填模型 ID。permissions.allow里我顺手放行了本地起服命令，这样 AI 帮你调试时可以直接跑python -m http.server，不用每次手动确认。
3.2 config.toml（Codex / 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-demo"base_url同样写https://taotoken.net/api，model_id按需替换。[server]段是我自己加的约定，用来记录本地预览服务的端口和根目录，方便脚本读取。
3.3 Viewer 嵌入 HTML 骨架
这是核心。注意marmoset.js用本地路径，.mview用相对路径：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="utf-8"> <meta name="viewport" content="user-scalable=0"> <title>Marmoset Viewer 预览</title> <script src="marmoset.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 | 自动加载模型 | true |
| fullFrame | 全屏框架模式 | true |
| pagePreset | 是否用页面预设 | 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是否 200：
import 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_URL="https://taotoken.net/api" export TAOTOKEN_API_KEY="sk-你的Key"然后脚本里统一引用，避免硬编码。
几个实用技巧：
- 把
marmoset.js和常用.mview放同一个模板目录，新项目直接复制，不用每次找脚本； - HTML 里的
width/height用变量注入，方便批量生成不同尺寸的预览页； - 用 AI 客户端生成一个
build.py，自动把 Toolbag 导出目录里的.mview批量套进 HTML 模板； - 本地服务器用
nohup或后台方式常驻，避免每次手动起。
如果你要长期做编码和 Agent 类任务，可以考虑用 Coding Plan 把额度固定下来，比按次调用更可控。验证模型效果时，直接用模型对话页面测一下返回是否正常，再进正式配置。
最后留一个我踩过的坑：.mview文件别放桌面根目录，某些系统权限会拦。放项目子目录，路径全英文，基本就不会再遇到黑屏。控制台干净、模型能转，这条链路就算通了。
