1. 从一次启动失败说起初始化项目到底在做什么如果你正在跟 Blender-MCP 服务源码这条线大概率已经跑过前面几篇插件能装、面板能显示、按钮能点。但到了「初始化项目」这一步很多人会卡在同一个地方——Blender 启动了MCP 服务却没起来或者起来了但连不上模型通道。我试过把main.py、create.py、test.py三个入口反复跑最后发现真正决定「项目能不能初始化成功」的不是业务代码而是配置加载顺序和 Key/API 通道的骨架有没有搭对。这篇是 Blender-MCP 服务源码解读的第 4 篇聚焦初始化项目阶段的配置加载与启动流程。核心要解决三件事第一搞清楚 Blender 插件初始化时配置是从哪读的、按什么顺序覆盖第二把settings.json和config.toml的骨架写出来让本地能复现启动第三用 TaoToken 统一 Key/API 通道把模型请求接进去并给出可复制的验证动作。适合已经能跑通 Blender 插件基础模板、准备把 MCP 服务接上模型通道的读者。全文的配置片段都可以直接抄改路径和 Key 就能用。2. 初始化项目的配置加载链路与 TaoToken 前置2.1 配置加载的三个阶段Blender-MCP 服务在初始化时配置不是一次性读完的而是分三层第一层是 Blender 插件自身的偏好设置存在bpy.context.preferences.addons[__addon_name__].preferences里这一层由AddonPreferences.py定义用户在 Blender 界面里改。第二层是项目级配置文件通常是settings.json或config.toml放在项目根目录由main.py在启动时读取。第三层是运行时环境变量优先级最高用来覆盖前两层方便在不同机器上切换通道。理解这个顺序很关键如果你在settings.json里写了 API 地址但环境变量里也有一个同名变量最终生效的是环境变量。初始化项目时「配置没生效」的坑八成是优先级搞反了。2.2 TaoToken 在初始化阶段的位置TaoToken 在这里扮演的是统一 Key/API 通道的角色。你不需要在代码里硬编码某个模型厂商的地址而是把 base_url 指向 TaoToken 的 API 入口Key 用 TaoToken 生成的统一 Key。这样初始化项目时配置骨架里只需要维护一份通道信息后续换模型、加 Agent 都不用动业务代码。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里写干净的这个就行。2.3 初始化阶段要准备的东西在写配置之前先把这几样准备好一个 TaoToken 的 API Key在控制台生成、项目根目录的写权限、Blender 版本确认3.6 以上对 MCP 支持更稳。Key 的生成入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 生成后先复制到剪贴板后面配置要用。3. 可复制的初始化配置骨架3.1 settings.json 骨架写法先给settings.json的完整骨架。这个文件放在项目根目录main.py启动时会优先读它{ project: { name: blender-mcp-service, version: 0.1.0, debug: true }, mcp: { host: 127.0.0.1, port: 9876, transport: socket, timeout: 30 }, llm: { provider: taotoken, base_url: https://taotoken.net/api, api_key: , model: claude-sonnet-4-20250514, max_tokens: 4096, temperature: 0.7 }, logging: { level: INFO, file: logs/mcp_service.log } }几个要点api_key留空实际值从环境变量注入避免提交到仓库base_url写 TaoToken 的 API 地址不要带任何查询参数transport用 socket和后面 Blender 插件里的 socket 服务对应。3.2 config.toml 骨架写法如果你更习惯 TOML等价写法如下放在项目根目录main.py里用tomllibPython 3.11或tomli读取[project] name blender-mcp-service version 0.1.0 debug true [mcp] host 127.0.0.1 port 9876 transport socket timeout 30 [llm] provider taotoken base_url https://taotoken.net/api api_key model claude-sonnet-4-20250514 max_tokens 4096 temperature 0.7 [logging] level INFO file logs/mcp_service.log两种格式选一种就行不要同时存在否则加载逻辑会打架。我建议用settings.json因为 Blender 插件那边读 JSON 更顺。3.3 配置加载代码片段在main.py里初始化阶段加这段加载逻辑顺序是「默认值 → 配置文件 → 环境变量」import json import os from pathlib import Path DEFAULT_CONFIG { mcp: {host: 127.0.0.1, port: 9876, transport: socket}, llm: {base_url: https://taotoken.net/api, model: claude-sonnet-4-20250514}, } def load_config(config_path: str settings.json) - dict: config DEFAULT_CONFIG.copy() path Path(config_path) if path.exists(): with open(path, r, encodingutf-8) as f: file_config json.load(f) for section, values in file_config.items(): if isinstance(values, dict) and section in config: config[section].update(values) else: config[section] values # 环境变量覆盖优先级最高 if os.getenv(TAOTOKEN_API_KEY): config[llm][api_key] os.getenv(TAOTOKEN_API_KEY) if os.getenv(TAOTOKEN_BASE_URL): config[llm][base_url] os.getenv(TAOTOKEN_BASE_URL) return config这段代码的好处是即使配置文件缺失项目也能用默认值启动环境变量只在存在时才覆盖不会把配置清空。3.4 环境变量注入方式Linux/macOS 下export TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 下$env:TAOTOKEN_API_KEY你的Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api注意 base_url 不要写成带/v1或带 UTM 的地址TaoToken 的 API 入口就是https://taotoken.net/api路径拼接由 SDK 处理。4. 验证初始化与通道接入是否正常4.1 启动项目并观察日志配置写完后跑main.pypython main.py --config settings.json正常启动时日志里应该能看到类似输出[INFO] Loading config from settings.json [INFO] MCP service listening on 127.0.0.1:9876 [INFO] LLM provider: taotoken, base_url: https://taotoken.net/api [INFO] Initialization complete如果base_url那行显示的是空或者默认值说明环境变量没注入成功回去检查export是否在当前终端生效。4.2 用 curl 验证通道在启动服务的同时另开一个终端直接验证 TaoToken 通道是否通curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: ping}] }返回里如果有content字段且包含文本说明 Key 和通道都正常。这一步是初始化项目里最值得单独做的验证因为它把「配置加载」和「通道可用」两件事分开了出问题好定位。4.3 在 Blender 里触发一次 MCP 调用回到 Blender打开你的插件面板点那个触发 MCP 服务的按钮。如果前面配置都对Blender 控制台会打印 socket 连接成功的日志同时logs/mcp_service.log里会多一条请求记录。到这一步初始化项目就算真正跑通了。如果你更想先在对话界面里确认模型通道可以直接用模型对话入口试一句https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一条消息看返回是否正常再回到 Blender 里联调。5. 本篇常见错排查5.1 配置不生效优先级搞反最常见的现象是改了settings.json里的base_url但日志里还是旧值。原因通常是环境变量里有一个同名的旧值覆盖了文件配置。排查方法是在加载配置后打印一次最终 configimport pprint pprint.pprint(config)看llm.base_url和llm.api_key的实际值和预期对比。5.2 端口被占用9876 起不来如果日志报Address already in use说明 9876 被别的进程占了。改settings.json里的mcp.port为 9877 或更高同时记得 Blender 插件那边的 socket 客户端端口也要同步改两边不一致会连不上。5.3 Key 无效401 或 403curl 验证时返回 401先确认 Key 有没有多余空格尤其是从网页复制时容易带上换行。再确认请求头字段名对不对TaoToken 的 Anthropic 兼容接口用x-api-key如果你用的是 OpenAI 兼容格式则用Authorization: Bearer。两种别混用。5.4 模型名写错404 或 model not foundmodel字段要和 TaoToken 支持的模型名完全一致大小写、日期后缀都不能错。不确定的话去文档里查当前可用模型列表https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 复制准确名称再填。5.5 日志目录不存在导致启动失败logging.file指向logs/mcp_service.log如果logs目录不存在部分日志库会直接抛异常。启动前先建目录mkdir -p logs或者在代码里加Path(logs).mkdir(exist_okTrue)。6. 把通道固定下来再往下写业务初始化项目这一步做完你的 Blender-MCP 服务应该已经能做到读配置、起 socket、连上 TaoToken 通道、在 Blender 里触发一次调用。接下来再写 Operator 和面板业务时就不用反复折腾配置了。如果你准备长期在这个项目上做编码和 Agent 联调建议把 Key 管理放到 Coding Plan 里统一维护入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 这样多项目切换时不用每个仓库都配一遍。Key 的生成和轮换在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入细节以文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。下一篇会接着讲 Operator 的注册顺序和 socket 消息格式把「点按钮 → 发请求 → 模型返回 → 改场景」这条链路补完。
