---
title: "通过 Hermes 与 OpenClaw 消息通道接入宝塔 MCP"
description: "介绍如何通过微信等消息通道让 Hermes 或 OpenClaw 接入宝塔 MCP，并提供两款 Agent 的配置文件写法、连接验证和常见问题排查方法。"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.bt.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 通过 Hermes 与 OpenClaw 消息通道接入宝塔 MCP

Hermes 和 OpenClaw 都可以通过微信、QQ、飞书、Telegram 等消息通道接收任务。将宝塔 MCP 配置到运行 Agent 的主机后，即可直接在聊天窗口中查询服务器状态，并按需调用网站、数据库、Docker、安全等宝塔面板能力。

```text
你 → 消息通道 → Hermes / OpenClaw → HTTPS MCP → 宝塔面板
```

消息通道只负责把指令送到 Agent，宝塔 MCP 则由 **Agent 所在主机**主动连接。因此，宝塔 MCP 的 IP 白名单应添加 Agent 主机访问面板时使用的公网出口 IP，而不是手机、微信服务器或浏览器所在电脑的 IP。

本文从**获取 MCP 安装提示词**开始介绍。尚未安装【宝塔 MCP 服务】或未完成端口、HTTPS 等准备工作的用户，请先参考[宝塔 MCP 安装指引](/ai-ops/mcp/installation)。消息通道本身的创建和登录不属于 MCP 配置范围；本文假设你已经可以通过消息向 Hermes 或 OpenClaw 正常发送任务。

:::warning 安全提示
安装提示词可能包含 MCP 地址、实例标识和授权令牌。消息可能保留在聊天记录、机器人日志或第三方平台中，请仅在自己控制的私聊通道中发送，不要发到群聊。能够登录 Agent 主机时，优先使用本文的配置文件方式，并把 Token 保存在环境变量文件中。
:::

## 开始前准备

开始配置前，请确认：

- 【宝塔 MCP 服务】已安装并处于“运行正常”状态
- 宝塔面板防火墙和云服务器安全组已放行 MCP 服务端口
- MCP 服务已配置客户端信任且覆盖访问地址的有效 HTTPS 证书
- Hermes 或 OpenClaw 已安装，且消息网关可以正常收发消息
- 已获取 Agent 所在主机访问宝塔 MCP 时使用的公网出口 IP

## 1. 获取 MCP 安装提示词并配置白名单

1. 登录宝塔面板，进入【软件商店】
2. 打开【宝塔 MCP 服务】的设置页面
3. 进入【接入与体验】
4. 点击【配置 IP 白名单】，添加 Hermes 或 OpenClaw 主机的公网出口 IP
5. 复制页面生成的 MCP 安装提示词

如果消息通道部署在另一台中转服务器上，但 Agent 实际运行在本机或其他云主机，应以**发起 MCP HTTPS 请求的 Agent 主机**为准。

## 2. 通过消息通道让 Agent 自动配置

在自己控制的私聊中，将安装提示词完整发送给 Hermes 或 OpenClaw。Agent 会下载提示词指向的安装文档，识别运行环境、配置位置、MCP 地址和认证方式。

![通过微信消息通道发送宝塔 MCP 安装提示词](/img/ai-ops/agent/hermes-openclaw-mcp/send-install-prompt-wechat.png)

下面以通过微信连接的 Hermes 为例。消息通道中的会话可能因为长时间未使用而自动重置，但这只会影响对话历史，不会自动删除已经写入主机的 MCP 配置。

![Hermes 通过消息通道下载并读取宝塔 MCP 安装文档](/img/ai-ops/agent/hermes-openclaw-mcp/hermes-read-install-doc.png)

Agent 返回配置计划后，重点核对：

- MCP URL 指向自己的宝塔 MCP 实例
- 使用远程 Streamable HTTP 和 Bearer Token，而不是来源不明的本地命令
- 写入的是当前 Agent 实际使用的配置文件
- 不会覆盖已有的其他 MCP 服务或消息通道配置
- Token 不会在回复、日志或截图中完整显示

如果 Agent 所在主机无法访问安装文档，可以登录主机按下面的配置文件方式手动接入。不要为了完成安装而关闭 TLS 校验或扩大白名单到任意来源。

![Hermes 检查宝塔 MCP 地址、配置位置和连接结果](/img/ai-ops/agent/hermes-openclaw-mcp/hermes-connection-check.png)

:::danger 不要照抄截图中的 TLS 结论
截图记录的是一次特定测试环境，出现了 `tls_required=false` 等任务摘要。这不代表应关闭证书校验。公网 MCP 必须使用客户端信任且覆盖访问地址的有效 HTTPS 证书；遇到证书错误时应修复证书链，而不是忽略校验。
:::

## 3. 手动配置 Hermes

Hermes 默认在 `~/.hermes/config.yaml` 的 `mcp_servers` 中保存 MCP 服务。为避免把 Token 直接写入主配置，先在 `~/.hermes/.env` 中添加：

```dotenv
BAOTA_MCP_TOKEN=<授权令牌>
```

然后将以下内容合并到 `~/.hermes/config.yaml`。如果文件中已有 `mcp_servers`，只新增 `baota-mcp` 子项，不要再次创建同名顶层键或覆盖其他服务：

```yaml
mcp_servers:
  baota-mcp:
    url: "https://<面板公网IP>:8765/bt-mcp-<实例标识>/mcp"
    headers:
      Authorization: "Bearer ${BAOTA_MCP_TOKEN}"
    enabled: true
```

Hermes 会从环境变量和 `~/.hermes/.env` 解析 `${BAOTA_MCP_TOKEN}`。完整配置结构和可选项请参考 [Hermes 官方 MCP 文档](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/mcp.md)与[配置说明](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)。

保存后重启 Hermes 进程或消息网关，并新建一段消息会话。加载成功后，MCP 工具通常以 `mcp_<服务名>_<工具名>` 的形式提供。

## 4. 手动配置 OpenClaw

OpenClaw 默认使用 JSON5 配置文件 `~/.openclaw/openclaw.json`。先在 `~/.openclaw/.env` 中添加：

```dotenv
BAOTA_MCP_TOKEN=<授权令牌>
```

再将以下 `mcp` 配置合并到 `~/.openclaw/openclaw.json`。JSON5 允许注释和末尾逗号；编辑时仍需保留原有的模型、通道和工具配置：

```json5
{
  mcp: {
    servers: {
      "baota-mcp": {
        url: "https://<面板公网IP>:8765/bt-mcp-<实例标识>/mcp",
        transport: "streamable-http",
        headers: {
          Authorization: "Bearer ${BAOTA_MCP_TOKEN}",
        },
        sslVerify: true,
        enabled: true,
      },
    },
  },
}
```

通过宝塔面板或 Docker 安装的 OpenClaw 可能把配置目录挂载到宿主机。宝塔面板当前安装方式可参考的持久化路径是：

```text
/www/dk_project/dk_app/dk_openclaw/data/config/openclaw.json
```

实际路径仍以当前插件的挂载配置或 `OPENCLAW_CONFIG_PATH` 为准。请修改持久化文件，不要只修改容器内会随重建丢失的临时副本。更多路径和重启方法可参考 [OpenClaw 常见问题](/faq/openclaw-troubleshooting)。

OpenClaw 也提供 MCP 命令用于检查和重新加载配置：

```bash
openclaw mcp list
openclaw mcp doctor baota-mcp --probe
openclaw mcp reload
```

配置结构、环境变量替换和命令行为请以当前版本的 [OpenClaw 配置文档](https://docs.openclaw.ai/gateway/configuration)、[配置参考](https://docs.openclaw.ai/gateway/configuration-reference)与 [MCP CLI 文档](https://docs.openclaw.ai/cli/mcp)为准。重新加载后，建议重新打开一个私聊会话再验证工具。

## 5. 执行首次只读验证

完成配置并重新加载 Agent 后，在消息通道中发送一条只读指令，例如：

```text
查看宝塔面板当前状态，只读取 CPU、内存、磁盘、系统负载和服务运行情况，不要修改任何配置。
```

如果 Agent 能调用 `SystemInfo`、`ServiceStatus` 等只读工具并返回真实服务器信息，且没有出现 TLS、`401` 或 `403` 错误，说明接入成功。

![Hermes 通过消息通道完成宝塔 MCP 首次只读调用](/img/ai-ops/agent/hermes-openclaw-mcp/hermes-readonly-verification.png)

截图中的资源数据和服务状态仅为当次测试结果。首次验证通过后，再根据实际需要逐步尝试其他操作。涉及删除文件、修改防火墙、重启服务、安装软件等高风险操作时，应先让 Agent 说明目标、影响和回退方式，并保留人工确认。

## 常见问题

### 消息可以正常收发，但 MCP 无法连接

消息通道和 MCP 是两条独立链路。先确认 Agent 主机能直接访问宝塔 MCP URL，再检查服务端口、安全组、证书、Token 和白名单。消息能到达机器人并不代表 MCP 已经连通。

### MCP 连接返回 `403 ip denied`

返回【宝塔 MCP 服务】的【接入与体验】页面，将 Agent 主机的实际公网出口 IP 加入白名单。不要添加手机 IP、消息平台服务器 IP，也不要将白名单长期设置为允许任意来源。

### MCP 连接返回 `401`

检查 Bearer Token 是否与当前宝塔 MCP 实例一致。如果 Token 曾发送到群聊、公开工单或可被他人读取的日志，应立即重新生成授权信息并更新环境变量文件。

### 配置完成后当前会话看不到宝塔工具

MCP 工具通常在 Agent 或会话启动时发现。Hermes 应重启进程或消息网关并新建会话；OpenClaw 可先运行 `openclaw mcp reload`，必要时重启网关并新建会话。

### OpenClaw 已连接但聊天中没有 MCP 工具

检查当前工具 Profile 是否允许 MCP，并确认没有通过 `tools.deny` 禁用 MCP 工具。使用最小工具 Profile 时，可能需要显式允许所需的 MCP 能力。完成变更后重新加载配置并新建会话。

### 出现 TLS 或证书错误

为 MCP 服务配置客户端信任且覆盖访问地址的有效 HTTPS 证书，并确认系统时间和证书链正常。不要把 `sslVerify` 改为 `false`，也不要使用 `curl -k` 绕过错误。

## 关于 Skill

宝塔 MCP 和宝塔面板 Skill 是相互独立的机制。仅配置 MCP 即可让 Hermes 或 OpenClaw 使用面板工具；如果当前 Agent 支持兼容的 Skills，并希望获得更完整的部署、排障和安全操作流程，可以再单独安装宝塔面板 Skill。安装方法请参考[宝塔面板 Skill 安装与使用指引](/ai-ops/agent/panel-integration/skill-installation)。

## 相关文档

- [宝塔 MCP 安装指引](/ai-ops/mcp/installation)
- [宝塔 MCP 介绍](/ai-ops/mcp)
- [使用 Codex 接入宝塔 MCP](/ai-ops/agent/panel-integration/codex-mcp)
- [使用 WorkBuddy 接入宝塔 MCP](/ai-ops/agent/panel-integration/workbuddy-mcp)
- [使用 Claude Code 接入宝塔 MCP](/ai-ops/agent/panel-integration/claude-code-mcp)
- [使用 TRAE 接入宝塔 MCP](/ai-ops/agent/panel-integration/trae-mcp)
- [使用 DeepSeek Harness 接入宝塔 MCP](/ai-ops/agent/panel-integration/deepseek-harness-mcp)
- [宝塔面板 Skill 安装与使用指引](/ai-ops/agent/panel-integration/skill-installation)
- [OpenClaw QQ / 飞书机器人配置教程](/practical-tutorials/openclaw-qq-feishu-bot)
- [Agent 接入宝塔 MCP 与使用 Skills](/ai-ops/agent/panel-integration)

Source: https://docs.bt.cn/ai-ops/agent/panel-integration/hermes-openclaw-mcp/index.mdx