内容
# Hailo MCP 服务器适用于 OpenClaw
MCP（模型上下文协议）服务器，暴露 Hailo-10H AI 加速器的工具给任何兼容 MCP 的代理框架。所有推理都在 Hailo AI 加速器上本地运行 — 零云依赖。
## 架构
```
Telegram / CLI ──► OpenClaw Gateway ──► MCP Server (stdio) ──► Python 脚本 ──► Hailo-10H AI 加速器
│ │
│ mcp_server.py
│ │
│ ┌──────┼──────────┐──────────────┐
│ ▼ ▼ ▼ ▼
│ vlm_analyze whisper detect monitor_*
│ (Qwen2-VL) (Whisper) (YOLO) (YOLO+Telegram)
│ │ │ │
▼ ▼ ▼ ▼
LLM（云） Hailo-10H AI 加速器（本地）
```
OpenClaw 以 stdio 传输方式启动 `mcp_server.py` 作为子进程。MCP 服务器暴露了 6 个工具，委托给 Python 后端脚本，每个脚本都在 Hailo-10H AI 加速器上运行推理。
## 工具
| 工具 | 描述 | 后端脚本 |
|------|-------------|----------------|
| `vlm_analyze` | 使用 Qwen2-VL-2B 视觉语言模型的图像分析 | `vlm_analyze.py` |
| `whisper_transcribe` | 使用 Whisper 的语音转文本 | `whisper_transcribe.py` |
| `detect` | 使用 YOLO 的物体检测/计数（单张图像或短视频） | `detect.py` |
| `monitor_start` | 使用 Telegram 警报启动后台检测监控 | `detect.py --monitor` |
| `monitor_stop` | 通过会话 ID 停止正在运行的监控会话 | —（PID 管理） |
| `monitor_list` | 列出活跃的后台监控会话 | —（PID 目录扫描） |
注册到 OpenClaw 后，工具将以 `hailo__` 前缀显示（例如 `hailo__vlm_analyze`）。
---
## 第 1 部分：先决条件
### 硬件
- PC 或 Raspberry Pi 5
- **Hailo-10H** 加速器（HAT+、M.2 或 PCIe）
- USB 摄像头（或 RPi 摄像头模块）
### 账户和订阅
- **LLM 提供商** - 任何 OpenClaw 支持的提供商都可以使用。本指南以 OpenAI 为例，但其他提供商同样适用。
- **Telegram 账户**，用于接收警报和与机器人聊天 - 目前 MCP 支持 Telegram 作为消息接口。
## 第 2 部分：OpenClaw 设置
### 2.1 获取您的 Telegram ID
获取您的数字账户 ID 并保存。
### 2.2 安装 OpenClaw
遵循 [docs.openclaw.ai/install](https://docs.openclaw.ai/install)。
### 2.3 配置 LLM
使用 **"使用 openai-codex auth 登录"** 选项并选择 **GPT 5.5**：[docs.openclaw.ai/providers/openai](https://docs.openclaw.ai/providers/openai)。
### 2.4 配置 Telegram 频道
在安装过程中提示选择消息平台时，选择 **Telegram**。
通过 @BotFather 创建您的机器人（给它一个有意义的名称）：[docs.openclaw.ai/channels/telegram](https://docs.openclaw.ai/channels/telegram)。
在 OpenClaw 的 `openclaw.json` 配置文件中，使用您的 Telegram ID 设置 **allowlist** 策略，以便机器人仅响应您：
```json
"dmPolicy": "allowlist",
"allowFrom": ["您的 Telegram ID"]
```
保存 **机器人令牌** — 您稍后将需要它来进行 MCP 配置。
### 2.5 测试 OpenClaw 独立运行
此时，OpenClaw + Telegram 应该像一个正常的 LLM 聊天一样工作 — 此时还没有 Hailo。给您的机器人发送消息，并验证您是否收到响应。
## 第 3 部分：Hailo 设置
### 3.1 安装 Hailo 软件栈
安装完整的软件包：HailoRT（deb + whl），PCIe 驱动程序，Tappas（deb + whl）。: https://github.com/hailo-ai/hailo-apps/blob/main/doc/user_guide/installation.md#manual-installation-advanced 在“安装 Hailo 先决条件包”下（最后重启）
验证设备是否被识别：
```bash
hailortcli fw-control identify
```
### 3.2 安装 hailo-apps
遵循：[github.com/hailo-ai/hailo-apps — 安装](https://github.com/hailo-ai/hailo-apps/tree/main#install-hailo-apps)
### 3.3 测试 hailo-apps 独立运行
插入 Hailo-10H 和 USB 摄像头，然后运行一个基本的检测管道来确认一切正常：
```bash
source setup_env.sh # 激活虚拟环境
hailo-detect --input /dev/video0 # 假设 UB 摄像头映射到 0
```
您应该会看到一个带有边界框的窗口。按 Ctrl+C 停止。
### 3.4 安装其他依赖项
```bash
sudo apt install ffmpeg gstreamer1.0-tools gstreamer1.0-plugins-base \
gstreamer1.0-plugins-good gstreamer1.0-plugins-bad
```
## 第 4 部分：Hailo MCP 集成
### 要部署的文件
```
<SCRIPTS_DIR>/
├── mcp_server.py — MCP 协议服务器（6 个工具）
├── vlm_analyze.py — VLM 推理包装器
├── whisper_transcribe.py — Whisper 语音转文本包装器
└── detect.py — YOLO 检测 + 监控引擎
```
### 4.1 安装 MCP SDK
```bash
source setup_env.sh # 激活虚拟环境
pip install "mcp[cli]"
# 验证：
python -c "import mcp; print(f'mcp {mcp.__version__} OK')"
```
### 4.2 部署脚本
```bash
mkdir -p ~/hailo-openclaw
# 将所有 4 个 .py 文件复制到 ~/hailo-openclaw/
```
### 4.3 配置 OpenClaw
浏览您现有的 OpenClaw 配置文件 `~/.openclaw/openclaw.json`，并将其与此存储库中包含的紧凑型 `openclaw.json` 模板进行比较。将 Hailo MCP 服务器块合并到您的配置中，填写每个 `TODO` 字段：
| 字段 | 需要填写的内容 |
|-------|-------------|
| `gateway.auth.token` | 运行 `openclaw onboard` 生成，或设置任意十六进制字符串 |
| `auth.profiles` 键 | 您的电子邮件地址，例如 `openai-codex:you@gmail.com` |
| `channels.telegram.botToken` | 来自 @BotFather 的令牌（格式：`123456789:AABBcc...`） |
| `channels.telegram.allowFrom` | 您的 Telegram 聊天 ID（数字字符串） |
| `mcp.servers.hailo.command` | Python 虚拟环境的完整路径，例如 `/home/hailo/.../venv_hailo_apps/bin/python` |
| `mcp.servers.hailo.args` | `mcp_server.py` 的完整路径 |
| 所有 `env` 路径 | 您系统上的实际路径（参见下面的环境变量） |
| `HAILO_TELEGRAM_BOT_TOKEN` | 与上面的 `botToken` 相同 |
| `HAILO_TELEGRAM_CHAT_ID` | 与上面的 `allowFrom` 相同 |
**重要：** 在替换配置文件之前停止网关 — 运行中的网关会在文件更改时自动恢复旧配置：
```bash
openclaw gateway stop
cp openclaw.json ~/.openclaw/openclaw.json
openclaw gateway start
```
### 4.4 验证
```bash
openclaw config validate # 应该打印：Config valid
openclaw mcp list # 应该显示：hailo
```
检查日志中的错误：
```bash
tail -5 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | \
python3 -c "import sys,json; [print(json.loads(l).get('message','')) for l in sys.stdin if l.strip()]"
```
没有 `failed to start server "hailo"` = 成功。
## 第 5 部分：通过 Telegram 测试
| # | 发送给您的机器人 | 预期工具 |
|---|------------------|---------------|
| 1 | 一张照片 + “这张图片里有什么？” | `hailo__vlm_analyze` |
| 2 | 语音备忘录 | `hailo__whisper_transcribe` |
| 3 | “在 USB 摄像头上数 5 秒钟的物体” | `hailo__detect` |
| 4 | “监控 USB 摄像头的人” | `hailo__monitor_start` |
| 5 | “停止监控” | `hailo__monitor_stop` |
## 环境变量
这些变量在 `openclaw.json` 的 `mcp.servers.hailo.env` 块中设置，并在启动时由 `mcp_server.py` 读取：
| 变量 | 是否必需 | 描述 |
|----------|----------|-------------|
| `HAILO_APPS_ROOT` | 是 | `hailo-apps` 的路径 |
| `HAILO_VENV_PATH` | 是 | 带有 hailo-apps + MCP SDK 的 Python 虚拟环境的路径 |
| `HAILO_SCRIPTS_DIR` | 是 | 包含 `mcp_server.py` 的目录的路径 |
| `HAILO_VLM_HEF_PATH` | 是 | Qwen2-VL HEF 模型的绝对路径 |
| `HAILO_WHISPER_HEF_PATH` | 是 | Whisper HEF 模型的绝对路径 |
| `HAILO_TELEGRAM_BOT_TOKEN` | 用于监控 | 用于警报通知的 Telegram 机器人令牌 |
| `HAILO_TELEGRAM_CHAT_ID` | 用于监控 | 用于警报通知的 Telegram 聊天 ID |
| `HAILO_VLM_TIMEOUT_MS` | 否 | VLM 超时，单位：毫秒（默认值：60000） |
| `HAILO_WHISPER_TIMEOUT_MS` | 否 | Whisper 超时，单位：毫秒（默认值：300000） |
| `HAILO_DETECTION_TIMEOUT_MS` | 否 | 检测超时，单位：毫秒（默认值：120000） |
**注意**:MCP 配置中的 `env` 块是必需的，因为 MCP 服务器作为单独的子进程启动，不会继承 `openclaw.json` 中的全局 `env`。
## 常见问题
| 问题 | 解决方法 |
|---------|-----|
| `ModuleNotFoundError: No module named 'mcp'` | `command` 必须是完整的虚拟环境 Python 路径，而不是 `python3` |
| `PYTHONPATH is blocked for stdio startup safety` | 不要将 `PYTHONPATH` 放入 MCP 环境块 — `mcp_server.py` 内部处理 |
| 工具在对话中不显示 | 在 openclaw.json 中将 `tools.profile` 设置为 `"full"` |
| 编辑后配置恢复 | 停止网关后编辑，然后启动（参见步骤 3） |
| `missing api key for openai` | 使用 `openai-codex/gpt-5.5`（OAuth），而不是 `openai/gpt-5.5`（需要 API 密钥） |
| 监控窗口失败 / “无法打开显示” | 在 Pi 上运行 `xhost +local:`，或添加到 `~/.profile` |
