qRobotClaw

语音网关服务，桥接硬件设备与 OpenClaw 平台。提供 VAD → ASR → OpenClaw LLM → TTS 完整语音交互链路。

部署运维模式

当用户要求部署、启动、升级、排障 qRobotClaw 时走此路径。

前置资源

源码托管于 GitHub: https://github.com/qrobotclaw/qrobotclaw.git，部署时通过 git clone 拉取。

步骤0：开启并验证 OpenClaw Responses API

qRobotClaw 强依赖 OpenClaw 的 Responses API 端点。必须先完成此步骤，验证通过后方可继续。

0.1 开启 Responses API 端点

使用 OpenClaw 的 config.patch 工具开启 Responses API。这会触发热更新（SIGUSR1），不会中断正在运行的任务。

调用工具: gateway config.patch
参数 raw: {"gateway":{"http":{"endpoints":{"responses":{"enabled":true}}}}}

0.2 等待热更新完成

config.patch 触发后，等待约 3-5 秒让 Gateway 完成重载。验证当前会话是否存活，如果收到自动回复说明热更新已完成。

0.3 获取 API Key 和端口

# 方法1：用 node 解析（推荐，精确提取）
GATEWAY_TOKEN=$(node -e "const fs=require('fs'); const c=JSON.parse(fs.readFileSync('/root/.openclaw/openclaw.json','utf8')); console.log(c.gateway.auth.token)")
GATEWAY_PORT=$(node -e "const fs=require('fs'); const c=JSON.parse(fs.readFileSync('/root/.openclaw/openclaw.json','utf8')); console.log(c.gateway.port)")

# 方法2：用 grep 快速查看
grep -E '"token"|"port"' /root/.openclaw/openclaw.json

记录：

GATEWAY_TOKEN = gateway.auth.token 的值
GATEWAY_PORT = gateway.port 的值

0.4 验证 Responses API 可达

curl -sf -H "Authorization: Bearer $GATEWAY_TOKEN" \
  "http://127.0.0.1:$GATEWAY_PORT/v1/responses" \
  -X POST -H "Content-Type: application/json" \
  -d '{"model":"openclaw","input":"ping"}'

注意: 模型输出可能较慢,这里可以设置两分钟超时,而不是过短的时间,以免模型还未输出就超时退出

⚠️ 如果验证失败：

返回 401 → Token 错误，检查 gateway.auth.token
返回 404 → 端点未开启或路径错误，确认 responses.enabled: true，路径是 /v1/responses
连接拒绝 → 端口错误或服务未启动，检查 gateway.port 和进程状态
返回 Invalid model → model 值不是 openclaw，确保传 "model":"openclaw"

如果确认配置正确但仍验证失败，可能是热更新未生效，可强制重启 Gateway：

调用工具: gateway restart
参数 note: "重启 Gateway 使 Responses API 配置生效"

⚠️ 必须验证通过后才能继续后续步骤。

部署流程

1. 环境检查

sudo apt-get update && sudo apt-get install -y python3 python3-venv python3-pip ffmpeg libopus-dev build-essential

2. 克隆代码

sudo mkdir -p /opt && cd /opt
sudo git clone https://github.com/qrobotclaw/qrobotclaw.git qrobotclaw

3. 安装依赖

cd /opt/qrobotclaw
python3 -m venv venv && source venv/bin/activate
pip install --upgrade pip && pip install -r requirements.txt

4. 写入配置

创建 /opt/qrobotclaw/data/.config.yaml，内容见 references/config-template.md。必须替换所有 REPLACE_WITH_* 占位符，其中：

REPLACE_WITH_OPENCLAW_PORT = 步骤 0.3 获取的 GATEWAY_PORT
REPLACE_WITH_OPENCLAW_API_KEY = 步骤 0.3 获取的 GATEWAY_TOKEN

5. 启动服务（systemd）

sudo tee /etc/systemd/system/qrobotclaw.service > /dev/null <<'UNIT'
[Unit]
Description=qRobotClaw Voice Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/qrobotclaw
ExecStart=/opt/qrobotclaw/venv/bin/python app.py
Restart=on-failure
RestartSec=5
StandardOutput=append:/opt/qrobotclaw/logs/qrobotclaw.log
StandardError=append:/opt/qrobotclaw/logs/qrobotclaw.log
KillSignal=SIGINT
TimeoutStopSec=10
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
UNIT

sudo mkdir -p /opt/qrobotclaw/logs
sudo systemctl daemon-reload && sudo systemctl enable --now qrobotclaw

前台验证：cd /opt/qrobotclaw && source venv/bin/activate && python app.py

6. 验证

ss -tlnp | grep -E ':8000|:8003'
curl -sf http://127.0.0.1:8003/openclaw/ota/
sudo systemctl status qrobotclaw

三项均通过即部署完成。

运维

sudo systemctl start|stop|restart|status qrobotclaw
sudo journalctl -u qrobotclaw -f

升级

停服务 → 备份 → git pull 更新代码（保留 data/.config.yaml）→ 更新依赖 → 重启。

sudo systemctl stop qrobotclaw
sudo cp -r /opt/qrobotclaw /opt/qrobotclaw.bak.$(date +%F-%H%M)
cd /opt/qrobotclaw && sudo git pull --ff-only
source /opt/qrobotclaw/venv/bin/activate && pip install -r requirements.txt
sudo systemctl start qrobotclaw

语音对话模式

当 qRobotClaw 连接 OpenClaw 进行语音对话时，以下约束作为对话行为指南。

角色

你是一个运行在智能硬件终端上的语音助手，用户通过语音与你交流，你的回复会被 TTS 语音合成后播放给用户。

输出要求

纯文本：禁止使用任何 Markdown、XML、代码块、表格、列表编号等格式化标记
简洁：控制在两三句话以内，最好 50 字以内
口语化：像面对面聊天一样自然
数字读法：用汉字读法，例如"一百二十三"而不是"123"
无 Emoji：不要输出任何 emoji 或特殊符号
不要输出无法朗读的内容：如网址、特殊符号、文件路径等

工具调用

上下文中会包含终端设备支持的 MCP 工具列表（音量控制、屏幕亮度、摄像头、退出语音对话等）
用户请求可以通过工具完成时，优先调用工具，不要用文字描述操作步骤
调用工具后，用简短的语音告知用户结果即可

场景示例

"现在几点了？" → "现在是下午三点十五分"
"帮我打开客厅灯" → 调用工具 → "灯已经打开了"
"今天天气怎么样" → "今天晴天，气温二十五到三十二度，适合出门"

LightClawRobot