【实战】OpenClaw调用本地部署的Nacos注册的Library MCP 服务

未来已来，只需一句指令，养龙虾专栏导航，持续更新ing...

一、背景介绍

业务场景中，工具的Prompt（提示词）需要根据实际需求快速迭代和优化。传统方式下，任何Prompt的变更都可能需要重新部署应用，流程繁琐，无法满足快速更新、调试和验证的需求。

使用阿里开源的Nacos 作为 MCP Registry，实现 Prompt 动态更新，Nacos 在此架构中担任 MCP Registry 的角色，负责服务注册与配置管理，完美解决了Prompt动态更新的痛点。

• 动态配置管理： 可以将MCP工具的Prompt、描述等元数据作为配置项托管在Nacos中。
• 实时更新生效： 当需要调整或优化某个工具的Prompt时，只需在Nacos控制台修改对应的配置。MCP Server会实时监听并拉取最新的配置，无需重启服务或重新部署应用，即可实现Prompt的快速更新、调试与验证。

MCP

**MCP（Model Context Protocol，模型上下文协议）
用户
OpenClaw AI助手
MCP客户端

mcporter
MCP协议层
MCP服务器

Library服务
图书数据库/API

核心设计思想：MCP 采用客户端-服务器架构，AI 应用（客户端）通过标准化接口连接 MCP 服务器，服务器再与底层工具交互。这种隔离设计确保 AI 不会直接接触敏感资源，提升了安全性和可审计性。

OpenClaw 与 MCP 的关系

OpenClaw 是一个自托管的 AI 助手运行时，它通过 mcporter 组件作为 MCP 客户端，连接各种外部 MCP 服务器。mcporter 是一个 TypeScript 运行时和 CLI 工具，支持零配置发现、调用 MCP 服务，并自动生成类型安全的客户端代码。

为什么选择 Nacos 托管 MCP 服务？

Nacos 3.0+ 原生支持 MCP Registry 能力，将 MCP 服务注册到 Nacos 具有以下优势：

优势	说明
集中管理	服务配置统一存储，支持多版本管理
动态更新	工具描述和参数支持运行时热更新，无需重启
零代码改造	通过配置即可将现有 HTTP 服务转换为 MCP 服务
生态集成	与 Spring AI Alibaba、Dify、Higress 等无缝集成

---

二、准备工作

或者，直接参阅：【实战】HiMarket本地化部署指南

1. 确认 Nacos 版本与环境

版本要求：Nacos Server ≥ 3.0.1（MCP Registry 功能从 3.0 版本开始支持）

检查 Nacos 服务状态：

# 检查 Nacos 是否运行（默认端口 8080）
curl http://localhost:8080/nacos/v3/console/health/readiness

预期返回：

{"status": "UP", "components": {...}}

2. 确认 Nacos 中的 MCP 服务

登录 Nacos 控制台（http://localhost:8080/nacos），在左侧菜单找到 "AI MCP" 或 "MCP 管理" 模块，确认：

• ✅ 已创建命名空间（例如 public，这是 Nacos 的默认命名空间）
• ✅ 已注册名为 library 的 MCP 服务
• ✅ 服务类型为 streamable 或 sse（HTTP 流式传输协议）

发现与调用
OpenClaw 环境
mcporter.json 配置
mcporter CLI
OpenClaw Gateway
Nacos MCP Registry
命名空间: public
MCP Server: library

版本: 1.0.0

协议: streamable-http
命名空间: dev
命名空间: prod

3. 获取服务访问信息

Nacos 3.x 支持通过 MCP Router 或 Higress 网关 暴露 MCP 服务。典型的访问路径格式为：

http://{网关地址}/{MCP路由前缀}/{服务名}/sse

示例（通过 Higress 网关访问）：

curl -i "http://localhost:8080/mcp/library/sse" \
  -H "Authorization: Bearer <你的token>"

⚠️ 说明 ：URL 路径 http://localhost:8080/v3/console/ai/mcp?mcpName=library&namespaceId=public&username=nacos 是 Nacos 控制台内部 API，并非标准的 MCP 客户端接入点。实际接入时应通过 Higress 网关或 Nacos MCP Router 暴露的端点。

正确的 URL 格式：

• 通过 Higress 网关：http://{higress-domain}/mcp/{mcp-server-name}/sse
• 直接访问（streamable HTTP）：http://{service-host}:{port}/mcp

如下图所示：

---

三、配置 OpenClaw

1. 找到 mcporter 配置文件

mcporter 使用 mcporter.json 作为 MCP 服务器配置文件。

配置加载优先级（从高到低）：

1. --config 命令行参数指定的路径
2. MCPORTER_CONFIG 环境变量
3. 当前项目 ./config/mcporter.json
4. 用户主目录 ~/.mcporter/mcporter.json（或 .jsonc）

OpenClaw 集成配置：

# 1. 启用 mcporter 技能
openclaw config set skills.entries.mcporter.enabled true

# 2. 设置配置文件路径（根据实际路径调整）
openclaw config set skills.entries.mcporter.env.MCPORTER_CONFIG "~/.mcporter/mcporter.json"

2. 编辑 mcporter.json

创建或编辑配置文件：

mkdir -p ~/.mcporter
touch ~/.mcporter/mcporter.json

添加 library 服务配置：

{
  "mcpServers": {
    "library": {
      "url": "http://localhost:8080/mcp/library/sse",
      "headers": {
        "Authorization": "Bearer eyJhbGciOiJIUzI1NiJ9..."
      }
    }
  }
}

字段说明：

字段	类型	说明
url	string	MCP 服务的 SSE 或 Streamable HTTP 端点地址
headers.Authorization	string	Bearer Token 认证头，用于访问受保护的 MCP 服务
type	string	（可选）传输协议类型：sse 或 streamable-http

💡 配置合并机制 ：mcporter 支持系统配置（~/.mcporter/）和项目配置（./config/）的层级合并。全局服务在所有项目中可用，项目配置可覆盖全局设置。

配置类型对比：

服务类型	配置方式	适用场景
HTTP/SSE	url + headers	远程托管的 MCP 服务（如 Nacos 注册的服务）
Stdio	command + args	本地运行的 MCP 服务器（如 Python 脚本）

---

四、加载与验证

1. 重启 OpenClaw Gateway

更改配置后，需要重启网关进程以加载新配置：

openclaw gateway restart

2. 使用 mcporter CLI 验证

# 列出所有配置的 MCP 服务器
mcporter list

# 查看 library 服务的工具列表（带详细 Schema）
mcporter list library --schema

# 测试调用 list_categories 工具
mcporter call library.list_categories

预期输出示例：

📂 library 工具列表 (4 个工具):
• list_categories - 获取图书分类列表
• list_book_names - 列出所有图书（支持 available 参数过滤）
• search_books - 搜索图书（支持 title/author/category 参数）
• get_book_details - 获取图书详情（通过 isbn 或 title 查询）

3. 在 OpenClaw 中调用

配置成功后，OpenClaw可以通过自然语言或技能前缀调用：

用户意图	实际调用的 Skill	底层 MCP 工具
"列出所有可借的图书"	library__list_book_names(available=true)	list_book_names
"搜索刘慈欣的书"	library__search_books(author="刘慈欣")	search_books
"查询《三体》详情"	library__get_book_details(title="三体")	get_book_details
"有哪些图书分类？"	library__list_categories()	list_categories

工作原理：
Library服务 Nacos MCP mcporter OpenClaw 用户 Library服务 Nacos MCP mcporter OpenClaw 用户 "搜索刘慈欣的书" 意图识别 → 选择 library__search_books 调用 skill HTTP SSE 请求 路由到目标服务 返回图书列表 SSE 响应 结构化数据 "找到刘慈欣的3本图书..."

如下图所示：

---

五、Nacos MCP 服务管理进阶

1. 动态更新工具描述

Nacos 支持在不重启服务的情况下，通过控制台动态修改 MCP 工具的描述和参数定义：

1. 登录 Nacos 控制台 → AI MCP → MCP 列表
2. 找到 library 服务，点击 "编辑"
3. 修改工具描述（帮助 AI 更好地理解工具用途）
4. 保存后，改动实时生效

2. 版本管理与灰度发布

Nacos MCP Registry 支持多版本管理：

// 在 mcporter.json 中指定版本
{
  "mcpServers": {
    "library": {
      "url": "http://localhost:8080/mcp/library/sse",
      "headers": { "Authorization": "Bearer ..." },
      "env": {
        "MCP_SERVER_VERSION": "2.0.0"
      }
    }
  }
}

3. 通过 Nacos MCP Router 智能路由

对于复杂的 MCP 服务集群，可以部署 Nacos MCP Router：
OpenClaw

mcporter
Nacos MCP Router
智能路由
Library v1.0

基础查询
Library v2.0

高级推荐
Library Dev

测试功能

Router 提供三种核心工具：

• search_mcp_server：根据任务描述智能筛选 MCP 服务
• add_mcp_server：动态初始化指定的 MCP 服务
• use_mcp_tool：代理调用目标服务的具体工具

---

六、常见问题与排查

1. mcporter list 看不到 library 服务

检查项	排查命令/方法
JSON 语法错误	jq . ~/.mcporter/mcporter.json
配置文件路径	echo $MCPORTER_CONFIG
配置加载顺序	mcporter list --verbose（查看配置来源）
网关重启状态	systemctl status openclaw-gateway

2. 调用失败：401 Unauthorized

• ✅ 确认 Nacos 的 Access Token 未过期（Nacos 默认 Token 有过期时间）
• ✅ 确认 Authorization header 格式为 Bearer <token>（注意 Bearer 后的空格）
• ✅ 检查 Nacos 是否开启认证（nacos.core.auth.enabled=true）

3. 调用超时或连接被拒绝

# 测试 Nacos 服务连通性
curl http://localhost:8848/nacos/v3/console/health/readiness

# 测试 MCP 端点（替换为实际地址）
curl -N http://localhost:8080/mcp/library/sse \
  -H "Authorization: Bearer <token>"

• ✅ 确认 Nacos 服务地址和端口正确（默认 8848）
• ✅ 如果是远程服务，检查防火墙/安全组规则
• ✅ 确认 Higress/Nacos MCP Router 已正确配置并运行

4. 工具调用返回空结果或错误

• ✅ 在 Nacos 控制台验证 library 服务的工具配置是否正确
• ✅ 检查工具的后端地址格式（应为 http://host:port，而非 http:/host:port）
• ✅ 使用 mcporter call library.{tool_name} --args '{...}' 显式传递参数测试

5. 如何更新 Token？

编辑 ~/.mcporter/mcporter.json，替换 headers.Authorization 的值，然后重载 OpenClaw Gateway。

---

七、总结

通过以上步骤，你已经成功将 Nacos 托管的 library MCP 服务集成到 OpenClaw 中。

核心流程回顾：
运行阶段
OpenClaw 接收用户查询
mcporter 路由请求
Nacos MCP Router
Library 服务执行
返回结果给 OpenClaw
配置阶段
准备 Nacos 3.0+ 环境
注册 library MCP 服务
配置 mcporter.json

现在你可以：

• ✅ 在 OpenClaw 对话框中使用自然语言查询图书
• ✅ 通过 library__* 技能前缀精确调用图书管理功能
• ✅ 利用 Nacos 的动态更新能力，无需重启即可调整工具行为
• ✅ 通过 Nacos MCP Registry 管理多个 MCP 服务的注册与发现

🌟 扩展提示：Nacos MCP Registry 不仅支持 Library 服务，还可以托管 MySQL、Redis、GitHub、Slack 等各类 MCP 服务，构建企业统一的 AI 工具市场。结合 Spring AI Alibaba 框架，你可以快速将现有微服务"零代码"改造为 MCP 服务。