z-image-turbo MCP服务配置指南：OpenClaw与OpenCode集成

根据最新的 MCP（Model Context Protocol）生态标准，z-image-turbo项目的 MCP 服务本质上是一个标准的 JSON-RPC 2.0 服务器。它通过暴露 generate_image等工具，让支持 MCP 的客户端（如 OpenClaw、OpenCode）能直接调用本地 GPU 进行绘图。
以下是针对该项目的 MCP 服务详解，以及配置 OpenClaw 和 OpenCode 的具体步骤。

一、z-image-turbo MCP 服务核心机制

1. 服务本质

• 位置：位于项目 backend/目录下的 mcp_server.py。
• 协议：基于 Anthropic 开源的 MCP 标准，支持两种传输模式：
  • stdio（标准输入输出）：用于本地进程间通信，适合 OpenClaw、Claude Desktop。
  • HTTP/SSE（HTTP 服务器）：用于网络远程调用，适合 OpenCode、Web 应用。
• 工具：主要暴露 generate_image（文生图）、get_model_info（获取模型状态）等函数。
  2. 启动方式（基于 README）
  启动服务器有两种标准命令：

1
2
3
4
5
6
7
8

# 进入后端目录
cd backend

# 模式1: Stdio (用于本地IDE集成)
./run_mcp.sh --stdio

# 模式2: HTTP (用于网络调用，如OpenCode)
./run_mcp.sh --http --port 8001

HTTP 模式启动后，服务端点通常为 http://localhost:8001/mcp。

二、配置 OpenClaw 连接 z-image-turbo

OpenClaw 作为 Agent 平台，通常通过 stdio​ 模式直接调用本地 Python 环境。
1. 配置原理
OpenClaw 的配置文件（通常位于 ~/.openclaw/openclaw.json或项目配置中）需要声明 MCP Server 的启动命令和参数。
2. 具体配置步骤
根据 README 中的“Claude Desktop Integration”示例，OpenClaw 的配置逻辑完全一致。你需要编辑 OpenClaw 的 MCP 配置文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "mcpServers": {
    "z-image-turbo": {
      "command": "C:\\path\\to\\z-image-turbo\\venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\z-image-turbo\\backend\\mcp_server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      },
      "timeout": 300000
    }
  }
}

关键参数说明：

• command：必须指向你创建的 Python 虚拟环境（venv）中的 python.exe，确保依赖包正确。
• args：指向 mcp_server.py脚本，并指定 stdio传输。
• timeout：设置为 300000（5分钟），因为首次运行需要加载 6B 模型，耗时较长。
  3. 验证与使用
• 重启 OpenClaw Gateway：openclaw gateway restart
• 在 OpenClaw 聊天中，直接输入指令：“生成一张雪景图”，AI 会自动调用 z-image-turbo的 MCP 工具并返回图片。

三、配置 OpenCode IDE 连接 z-image-turbo

OpenCode（及类似 VS Code 的 AI IDE）通常支持通过 HTTP​ 模式连接 MCP Server，实现代码注释中的“画图”功能。
1. 启动 HTTP 服务
首先，确保 z-image-turbo的 MCP 服务以 HTTP 模式运行（见第一步）。
2. OpenCode 配置
在 OpenCode 的设置中（或工作区 .vscode/mcp.json文件），添加远程 MCP Server 配置：

1
2
3
4
5
6
7
8

{
  "servers": {
    "z-image-turbo": {
      "url": "http://localhost:8001/mcp",
      "headers": {}
    }
  }
}

3. 使用场景
配置成功后，在 OpenCode 的 AI 聊天框中，你可以输入：

“帮我画一个登录页面的草图”
AI（如 Copilot）会通过 HTTP 协议向本地的 http://localhost:8001/mcp发送请求，生成图片并插入到编辑器中。

四、常见问题与避坑指南

总结：
z-image-turbo的 MCP 服务是一个标准的协议桥接器。

• 对于 OpenClaw，配置的是启动命令（stdio）；
• 对于 OpenCode，配置的是网络地址（HTTP）。
• 只要服务成功启动并返回 {"result": "success"}的健康状态，即可在相应平台调用绘图功能。

项目地址和资源

• GitHub：https://github.com/aaryan-kapoor/z-image-turbo
• stable-diffusion.cpp使用指南