# kongClaw **Repository Path**: panjyang/kong-claw ## Basic Information - **Project Name**: kongClaw - **Description**: 运行在行空板上的openclaw客户端 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-23 - **Last Updated**: 2026-03-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # OpenClaw Python Client (kong-claw) 行空板 M10 上的 OpenClaw 语音/文本交互客户端。 ## 功能特性 - WebSocket 连接到 OpenClaw Gateway (遵循官方协议握手) - 语音识别 (ASR) - 支持 Whisper / faster-whisper / 火山引擎 - 语音合成 (TTS) - 支持 edge-tts / pyttsx3 / 火山引擎 - 音频录制和播放 (通用 sounddevice 或行空板原生 Audio) - 行空板 LCD 屏幕显示 (240x320, unihiker GUI 库) - OLED 屏幕显示 (I2C, 可选) - 控制台显示 (调试/开发) - 行空板按键触发对话 - 配置文件 + 环境变量 + CLI 参数三级配置 - 完整 argparse CLI ## 系统架构 ``` 行空板 M10 ├── 显示 (LCD 240x320 / OLED / Console) ├── 输入 (板载按键 / 键盘回车) ├── ASR (Whisper / faster-whisper / 火山引擎) ├── TTS (edge-tts / pyttsx3 / 火山引擎) ├── Audio (unihiker Audio / sounddevice) └── OpenClaw Client (WebSocket) ↓ OpenClaw Gateway (:18789) ``` ## UI 界面说明 程序支持三种显示后端，根据运行环境和 `--display` 参数自动切换。 ### 1. 控制台模式 (`--display console`，默认) 纯文本终端界面，适合开发调试和非行空板环境。 **文本交互模式** (`python3 main.py`)： ``` OpenClaw 文本交互模式 输入 'quit' 退出 | 'history' 查看历史 | 'qr' 显示 Gateway 二维码 -------------------------------------------------- 你: 你好 AI: 你好！有什么可以帮助你的吗？ 你: history === 对话历史 (1 条) === [1] 你: 你好 AI: 你好！有什么可以帮助你的吗？ ``` **语音交互模式** (`python3 main.py --voice`)： ``` [状态] 就绪 [显示][L3] 按下按键开始对话 ← 按回车或行空板物理按键触发 [状态] 录音中... [音量] [████████████░░░░░░░░] 60% ← 实时音量条 [状态] 识别中... [状态] 处理中... [状态] 合成中... [状态] 播放中... [状态] 就绪 ``` ### 2. 行空板 LCD 模式 (`--display unihiker`) 240×320 像素彩色 LCD 屏幕，深色主题，专为行空板 M10 设计。 **主界面布局：** ``` ┌──────────────────────────┐ │ OpenClaw │ ← 标题 (红色 #e94560) │ 行空板语音助手 │ ← 副标题 (灰色) │ │ │ 状态: 就绪 │ ← 状态栏 (白色) │ │ │ 😊 │ ← 动态表情 70×70 │ (Smile/Wink/Think) │ 就绪=😊 录音=😉 思考=🤔 │ │ │ ▁ ▁ ▁ █ █ █ █ ▁ ▁ ▁ ▁ ▁│ ← 12段音量指示条 │ (绿→橙→红 渐变色) │ 低音量=绿 中=橙 高=红 │ │ │ 你: 今天天气怎么样？ │ ← 用户输入 (青色 #00b4d8) │ │ │ AI: 今天天气晴朗，气温 │ ← AI回复 (浅蓝 #90e0ef) │ 25度，适合外出... │ 最多显示120字 │ │ │ 按键对话 | 长按查看历史 │ ← 底部提示 (灰色) └──────────────────────────┘ 背景色: 深蓝黑 #1a1a2e ``` **对话历史页面**（长按按键触发）： ``` ┌──────────────────────────┐ │ 对话历史 (1/3) │ ← 页码 │ │ │ [5] 你: 帮我写首诗 │ ← 每页3条 │ AI: 春风拂面柳丝长... │ │ │ │ [4] 你: 今天天气 │ │ AI: 今天晴朗25度... │ │ │ │ [3] 你: 你好 │ │ AI: 你好！有什么... │ │ │ │ [上一页] [下一页] │ ← 分页按钮 │ [返回] │ ← 返回主界面 └──────────────────────────┘ ``` **二维码页面**（文本模式启动时自动显示 3 秒，或输入 `qr` 触发）： 显示 Gateway HTTP 地址的二维码，方便手机扫码访问。 ### 3. OLED 模式 (`--display oled`) 128×64 像素单色 OLED 屏幕 (I2C SH1106/SSD1306)，仅显示精简文本： ``` ┌────────────────┐ │[就绪] │ ← 状态行 │ │ │U:你好 │ ← 用户文字 (16字截断) │A:你好！有什... │ ← AI文字 (16字截断) └────────────────┘ ``` ### 状态流转与表情映射 | 状态 | 表情 | 说明 | |------|------|------| | 就绪 | 😊 Smile | 等待用户输入 | | 录音中... | 😉 Wink | 正在录制语音 | | 识别中... | 🤔 Think | ASR 处理中 | | 处理中... | 🤔 Think | LLM 生成回复中 | | 合成中... | ✌️ Peace | TTS 合成语音中 | | 播放中... | ✌️ Peace | 播放语音回复 | | 连接断开... | 😬 Nerve | Gateway 断连 | | 错误 | 😱 Shock | 发生异常 | | 未识别到语音 | 😅 Sweat | ASR 无结果 | ## 快速开始 ### 1. 安装依赖 **开发环境 (PC):** ```bash pip install -r requirements.txt pip install faster-whisper # 推荐 ASR ``` **行空板 M10:** ```bash # unihiker 和 pinpong 已预装 pip install websockets edge-tts sounddevice soundfile numpy pip install faster-whisper # 行空板推荐用 tiny 模型 ``` ### 2. 配置 Gateway 编辑 `config/default.conf`: ```ini [gateway] url = ws://192.168.30.63:18789 token = your_token_here ``` 或通过环境变量: ```bash export OPENCLAW_GATEWAY_URL=ws://192.168.30.63:18789 export OPENCLAW_GATEWAY_TOKEN=your_token_here ``` ### 3. 运行 **文本交互模式 (默认):** ```bash python3 main.py ``` **语音交互模式:** ```bash python3 main.py --voice ``` **行空板全功能模式 (LCD + 语音 + 按键):** ```bash python3 main.py --voice --display unihiker ``` **单次对话:** ```bash python3 main.py "你好，请介绍一下你自己" ``` ## 使用方法 ``` usage: main.py [-h] [--voice] [--text] [-g GATEWAY] [-t TOKEN] [--agent AGENT] [--session SESSION] [-d {console,unihiker,oled}] [--asr {whisper,faster-whisper}] [--asr-model {tiny,base,small,medium,large}] [--tts {edge-tts,pyttsx3}] [--tts-voice TTS_VOICE] [--record-duration RECORD_DURATION] [--silence-detect] [-c CONFIG] [--log-level {DEBUG,INFO,WARNING,ERROR}] [prompt] ``` ### 常用选项 | 选项 | 说明 | |------|------| | `--voice` | 语音交互模式 | | `--display unihiker` | 使用行空板 LCD 显示 | | `--gateway URL` | 指定 Gateway 地址 | | `--token TOKEN` | Gateway 认证令牌 | | `--asr faster-whisper` | 使用 faster-whisper (推荐本地) | | `--asr volcengine` | 使用火山引擎 ASR (推荐云端) | | `--tts volcengine` | 使用火山引擎 TTS (推荐云端) | | `--asr-model tiny` | 行空板推荐用 tiny 模型 | | `--silence-detect` | 自动检测静音停止录音 | | `--config PATH` | 指定配置文件 | ## 配置 配置优先级: **CLI 参数 > 环境变量 > 配置文件 > 默认值** ### 配置文件 `config/default.conf` (INI 格式): ```ini [gateway] url = ws://192.168.30.63:18789 token = 5b4eeb4c3e0721d6cd8e1ee12ea473dbc21cad985881dcfb agent = main session = main [asr] backend = whisper # whisper / faster-whisper / volcengine model_size = base [tts] backend = edge-tts # edge-tts / pyttsx3 / volcengine voice = zh-CN-XiaoxiaoNeural [audio] sample_rate = 16000 record_duration = 5.0 [display] backend = console [volcengine] # 火山引擎 (字节跳动豆包) ASR/TTS 服务凭据 app_key = your_app_key access_key = your_access_key asr_model = bigmodel tts_voice = zh_female_cancan_mars_bigtts tts_encoding = mp3 [logging] level = INFO ``` ### 环境变量 | 变量 | 说明 | |------|------| | `OPENCLAW_GATEWAY_URL` | Gateway 地址 | | `OPENCLAW_GATEWAY_TOKEN` | 认证令牌 | | `ASR_BACKEND` | ASR 后端 (whisper/faster-whisper/volcengine) | | `TTS_BACKEND` | TTS 后端 (edge-tts/pyttsx3/volcengine) | | `TTS_VOICE` | TTS 语音 | | `DISPLAY_BACKEND` | 显示后端 | | `VOLCENGINE_APP_KEY` | 火山引擎 App Key | | `VOLCENGINE_ACCESS_KEY` | 火山引擎 Access Key | | `LOG_LEVEL` | 日志级别 | ## 行空板 M10 硬件 - **CPU:** 四核 1.2GHz - **内存:** 512MB (建议用 tiny/base ASR 模型) - **存储:** 16GB + microSD 扩展 - **屏幕:** 240x320 LCD 彩屏 - **传感器:** 麦克风、光线、加速度、蜂鸣器 - **按键:** 板载按键 (触发对话) - **接口:** WiFi/蓝牙、USB、I2C x2、3-pin x4 - **系统:** Linux + Python 预装 ## 项目结构 ``` kong-claw/ ├── main.py # CLI 主入口 ├── requirements.txt # Python 依赖 ├── README.md # 文档 ├── config/ │ └── default.conf # 配置文件 ├── docs/ │ └── API.md # API 文档 ├── scripts/ │ ├── test_client.py # Gateway 连接测试 │ ├── test_audio.py # 音频测试 │ ├── test_tts.py # TTS 测试 │ ├── test_display.py # 显示测试 │ └── test_volcengine.py # 火山引擎 ASR/TTS 集成测试 ├── tests/ │ └── test_all.py # 全功能单元测试 └── src/ ├── __init__.py # 包信息 (v0.2.0) ├── config.py # 配置加载器 ├── client.py # WebSocket 客户端 (OpenClaw 协议) ├── app.py # 主应用编排 ├── asr.py # 语音识别 ├── tts.py # 语音合成 ├── audio.py # 音频处理 (通用 + 行空板) └── display.py # 显示 (Console / LCD / OLED) ``` ## 测试 ```bash # 全功能单元测试 python3 tests/test_all.py # 测试 Gateway 连接 python3 scripts/test_client.py # 测试音频 python3 scripts/test_audio.py # 测试 TTS python3 scripts/test_tts.py # 测试显示 (控制台) python3 scripts/test_display.py console # 测试显示 (行空板 LCD) python3 scripts/test_display.py unihiker # 测试火山引擎 ASR/TTS (端到端) python3 scripts/test_volcengine.py ``` ## 故障排除 ### 无法连接到 Gateway ```bash # 检查 Gateway 地址和端口是否可达 curl http://192.168.30.63:18789/ # 确认令牌: 在 Gateway 主机运行 openclaw dashboard --no-open ``` ### 行空板 unihiker 库问题 ```bash # 更新 unihiker 库 pip install -U unihiker # 确认版本 >= 0.0.25 python3 -c "import unihiker; print('OK')" ``` ### ASR/Whisper 模型下载失败 ```bash # 使用镜像 export HF_ENDPOINT=https://hf-mirror.com python3 -c "import whisper; whisper.load_model('tiny')" ``` ### 火山引擎 ASR/TTS 连接失败 ```bash # SSL 证书问题 (macOS 常见) - 程序已内置自动处理 # 如仍有问题，安装 certifi: pip install certifi # 测试火山引擎连通性 python3 scripts/test_volcengine.py # ASR 输入需要 WAV 格式，非 WAV 文件会自动用 ffmpeg 转换 # 确保安装了 ffmpeg: brew install ffmpeg # macOS apt install ffmpeg # Linux ``` ### 录音失败 ```bash # 检查音频设备 python3 scripts/test_audio.py # 行空板检查麦克风 python3 -c "from unihiker import Audio; a=Audio(); print(a.sound_level())" ``` ## 许可证 MIT License ## 作者 Feya ## 相关链接 - [OpenClaw 文档](https://docs.openclaw.ai) - [行空板 M10 官方文档](https://www.unihiker.com.cn/wiki/m10) - [行空板 unihiker 库](https://www.unihiker.com.cn/wiki/m10/unihiker_python_lib) - [Whisper](https://github.com/openai/whisper) - [faster-whisper](https://github.com/guillaumekln/faster-whisper) - [edge-tts](https://github.com/rany2/edge-tts) - [火山引擎语音技术](https://www.volcengine.com/docs/6561/1354869)