AXERA-TECH/openclaw-ax8850-qqbot-media

AX8850 OpenClaw QQBot 本地图片与语音功能

这个仓库提供 OpenClaw QQ Bot 在 AX8850 上使用图片、视频和语音功能所需的模型、运行库与 qqbot-media Skill。

• 图片和视频：Qwen3-VL-2B + AXLLM
• 语音转文字：SenseVoice + sherpa-onnx
• 文字转语音：Kokoro + sherpa-onnx
• QQ 消息接入：openclaw-qqbot + qqbot-media

当前版本只需要让 AXLLM 常驻运行。ASR 和 TTS 会在收到相应消息时由脚本直接调用，不需要另外启动服务。

文件说明

openclaw-ax8850-qqbot-media/
├── qqbot-media/
│   ├── SKILL.md
│   └── scripts/
│       ├── axera_vlm_image.sh
│       ├── axera_vlm_video.sh
│       ├── axera_vlm_http.py
│       ├── axera_asr.sh
│       └── axera_tts.sh
├── vlm/
│   ├── axllm
│   └── Qwen3-VL-2B-Instruct-GPTQ-Int4/
├── SenseVoiceSmall-axmodel/
│   ├── ax650/
│   ├── test_wavs/
│   └── sherpa-onnx-*-axera-ax650-linux-aarch64-shared/
└── kokoro/
    ├── build/
    ├── kokoro-multi-lang-v1_0-axmodel/
    └── kokoro-multi-lang-v1_1-axmodel/

开始前准备

• 一台可正常运行 AXLLM 的 AX8850 设备。
• bash、python3、curl、ffmpeg 和 ffprobe。
• 已经配置好文字模型的 OpenClaw。
• 一个 QQ Bot 的 AppID 和 AppSecret。
• /root 至少留出 10 GiB 可用空间，CMM 建议大于 2.5 GiB。

下面按 root 用户写命令。如果使用其他用户，请把命令中的 /root 换成该用户的 home 目录。

先确认几个命令都能找到：

command -v bash
command -v python3
command -v curl
command -v ffmpeg
command -v ffprobe

安装 OpenClaw 和 QQ Bot 插件

如果板上还没有 OpenClaw，先执行：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
openclaw onboard --install-daemon

按照 onboard 向导选择文字模型并填写认证信息，然后安装 QQ Bot 插件：

openclaw plugins install @tencent-connect/openclaw-qqbot@1.7.1
openclaw plugins list

这里使用 1.7.1。这个版本带有后面要替换的 skills/qqbot-media 目录；2.x 版本已经调整目录结构，不能直接使用下面的复制命令。

安装后应能看到：

/root/.openclaw/extensions/openclaw-qqbot/

下载本仓库

安装 Hugging Face CLI：

curl -LsSf https://hf.co/cli/install.sh | bash
export PATH="/root/.local/bin:$PATH"

下载到 /root/openclaw-ax8850-qqbot-media：

hf download AXERA-TECH/openclaw-ax8850-qqbot-media \
  --local-dir /root/openclaw-ax8850-qqbot-media

下载中断时再次执行同一条命令即可，已经完成的文件不会重复下载。

下载完成后检查：

test -f /root/openclaw-ax8850-qqbot-media/qqbot-media/SKILL.md &&
  echo "qqbot-media: OK"
test -f /root/openclaw-ax8850-qqbot-media/vlm/Qwen3-VL-2B-Instruct-GPTQ-Int4/config.json &&
  echo "VLM: OK"
test -f /root/openclaw-ax8850-qqbot-media/SenseVoiceSmall-axmodel/ax650/model-10-seconds.axmodel &&
  echo "ASR: OK"
test -f /root/openclaw-ax8850-qqbot-media/kokoro/kokoro-multi-lang-v1_0-axmodel/voices.bin &&
  echo "TTS: OK"

四项都显示 OK 后，补上执行权限：

chmod +x /root/openclaw-ax8850-qqbot-media/vlm/axllm
chmod +x /root/openclaw-ax8850-qqbot-media/SenseVoiceSmall-axmodel/\
sherpa-onnx-*-axera-ax650-linux-aarch64-shared/bin/sherpa-onnx-offline
chmod +x /root/openclaw-ax8850-qqbot-media/SenseVoiceSmall-axmodel/\
sherpa-onnx-*-axera-ax650-linux-aarch64-shared/bin/sherpa-onnx-vad-with-offline-asr
chmod +x /root/openclaw-ax8850-qqbot-media/kokoro/build/bin/sherpa-onnx-offline-tts
chmod +x /root/openclaw-ax8850-qqbot-media/qqbot-media/scripts/*.sh

替换 qqbot-media

先确认旧版和新版 Skill 都存在：

test -f /root/.openclaw/extensions/openclaw-qqbot/skills/qqbot-media/SKILL.md &&
  echo "原 Skill: OK"
test -f /root/openclaw-ax8850-qqbot-media/qqbot-media/SKILL.md &&
  echo "AX8850 Skill: OK"

备份插件自带的版本，再复制本仓库中的版本：

skill_src=/root/openclaw-ax8850-qqbot-media/qqbot-media
skill_dst=/root/.openclaw/extensions/openclaw-qqbot/skills/qqbot-media
skill_bak="${skill_dst}.bak.$(date +%Y%m%d-%H%M%S)"

mv "$skill_dst" "$skill_bak"
cp -a "$skill_src" "$skill_dst"
chmod +x "$skill_dst"/scripts/*.sh

复制完成后，下面的文件应直接存在：

/root/.openclaw/extensions/openclaw-qqbot/skills/qqbot-media/SKILL.md
/root/.openclaw/extensions/openclaw-qqbot/skills/qqbot-media/scripts/axera_vlm_image.sh
/root/.openclaw/extensions/openclaw-qqbot/skills/qqbot-media/scripts/axera_vlm_video.sh
/root/.openclaw/extensions/openclaw-qqbot/skills/qqbot-media/scripts/axera_asr.sh
/root/.openclaw/extensions/openclaw-qqbot/skills/qqbot-media/scripts/axera_tts.sh

启动 AXLLM

打开一个单独的终端：

cd /root/openclaw-ax8850-qqbot-media/vlm
./axllm serve ./Qwen3-VL-2B-Instruct-GPTQ-Int4/ --port 8120

看到模型加载完成后，另开终端检查：

curl -fsS http://127.0.0.1:8120/health
curl -fsS http://127.0.0.1:8120/v1/models

OpenClaw 直接运行在板上时，将 VLM 地址写入 OpenClaw 配置：

openclaw config set env.vars.AXERA_VLM_BASE "http://127.0.0.1:8120/v1"
openclaw config get env.vars.AXERA_VLM_BASE

如果 OpenClaw 运行在容器中，请把地址改成容器能够访问板上 8120 端口的地址。脚本默认值为 http://172.17.0.1:8120/v1。

绑定 QQ Bot

打开 QQ Bot 快速注册页，创建机器人并取得 AppID、AppSecret。将下面的占位内容换成真实值：

openclaw channels add --channel qqbot --token "<APP_ID>:<APP_SECRET>"
openclaw gateway restart

检查运行状态：

openclaw channels list
openclaw gateway status
openclaw logs --follow

AppSecret 不要写进截图、Issue 或公开日志。

分别测试图片、ASR 和 TTS

图片理解

AXLLM 保持运行，然后执行：

AXERA_VLM_BASE=http://127.0.0.1:8120/v1 \
bash /root/.openclaw/extensions/openclaw-qqbot/skills/qqbot-media/scripts/axera_vlm_image.sh \
  "/root/openclaw-ax8850-qqbot-media/vlm/Qwen3-VL-2B-Instruct-GPTQ-Int4/image.png" \
  "请用中文描述图片中的主体和可见文字。"

语音转文字

ASR 不需要启动服务，直接执行：

bash /root/.openclaw/extensions/openclaw-qqbot/skills/qqbot-media/scripts/axera_asr.sh \
  "/root/openclaw-ax8850-qqbot-media/SenseVoiceSmall-axmodel/test_wavs/zh.wav"

脚本会把输入音频转成 16 kHz 单声道 WAV。短音频直接识别，超过 10 秒的音频会先经过 VAD。

文字转语音

TTS 同样不需要启动服务：

bash /root/.openclaw/extensions/openclaw-qqbot/skills/qqbot-media/scripts/axera_tts.sh \
  "/tmp/axera_tts_test.wav" \
  "你好，这是一段由 AX8850 生成的测试语音。"

test -s /tmp/axera_tts_test.wav && ls -lh /tmp/axera_tts_test.wav

脚本默认使用 kokoro/kokoro-multi-lang-v1_0-axmodel，并会自动查找所需的 sherpa-onnx 运行库。

在 QQ 中使用

完成上面的测试后，可以直接给 QQ Bot 发送：

• 图片：“描述一下这张图，并读出图中的文字。”
• 视频：“概括这段视频发生了什么。”
• 语音：直接说出问题。
• 文字：“请用语音回答。”

图片和视频由 Qwen3-VL-2B 识别，语音由 SenseVoice 转成文字；需要语音回复时，Kokoro 会生成 WAV，再通过 QQ 发回。

文件放在其他位置

ASR 和 TTS 脚本默认到 $HOME/openclaw-ax8850-qqbot-media 中查找文件。如果下载到了其他位置，设置：

openclaw config set env.vars.AXERA_MEDIA_ROOT "<下载目录>"
openclaw config set env.vars.AXERA_KOKORO_ROOT "<下载目录>/kokoro"
openclaw gateway restart

也可以直接指定更具体的路径：

• AXERA_SHERPA_HOME：包含 bin/sherpa-onnx-offline 的 sherpa-onnx 目录。
• AXERA_KOKORO_MODEL_DIR：包含 voices.bin、tokens.txt 的 Kokoro 模型目录。
• AXERA_VLM_BASE：AXLLM 的 /v1 地址。

常见问题

现象	怎么排查
openclaw 命令不存在	检查 OpenClaw 安装输出和当前用户的 PATH
找不到 skills/qqbot-media	确认安装的是 openclaw-qqbot@1.7.1
axllm 提示 Permission denied	执行 chmod +x /root/openclaw-ax8850-qqbot-media/vlm/axllm
8120 无法访问	确认 AXLLM 仍在运行，并检查端口是否被占用
QQ 图片无法识别	先执行图片测试，再检查 AXERA_VLM_BASE
ASR 找不到模型或运行库	检查 SenseVoiceSmall-axmodel 是否完整，并确认 sherpa-onnx 文件有执行权限
TTS 找不到 Kokoro	检查 kokoro 目录，或设置 AXERA_KOKORO_ROOT
视频出现 KV Cache 或输入长度错误	将 AXERA_VIDEO_FRAMES 调小，单次不能超过 8 帧
更新 QQ Bot 插件后图片或语音失效	插件更新可能恢复自带 Skill，重新复制本仓库的 qqbot-media 并重启 Gateway