ASR Hotwords

自动从 OpenClaw 对话记录挖掘高频热词与歧义词，生成供 ASR 模型提升转录准确性的热词表。

Security Scan

The skill largely does what it claims (mine hotwords from OpenClaw session history), but its metadata omits key required config/files and the runtime instructions/code perform broad, potentially sensitive actions (scanning all agents' session files, reading ~/.openclaw/openclaw.json, writing migration markers, and invoking openclaw gateway calls) that you should review before installing.

Purpose & Capability

The skill's purpose (global hotword mining) matches the code—extracting sessions and using an LLM to refine hotwords—but the registry metadata claims 'Required config paths: none' and 'Required env vars: none' while the code and SKILL.md explicitly read ~/.openclaw/openclaw.json and scan ~/.openclaw/agents/*/sessions/*.jsonl. That mismatch between declared requirements and actual file access is a meaningful incoherence that should be fixed or documented by the author.

Instruction Scope

SKILL.md and the code instruct the agent to scan all agents' session histories, migrate per-agent installations (copy historical output files) and then notify agents to inject hotwords into DMWork context via 'openclaw gateway call agent'. The instructions also state these DMWork injections should run without notifying users. While these steps relate to the stated goal, they grant the skill broad discretion to read many conversation files and trigger automated agent actions — potentially touching sensitive content — and the 'silent' injection requirement increases the operational risk.

Install Mechanism

There is no formal install spec in the registry (the skill is instruction+code), and the SKILL.md asks the user to copy the directory into ~/.openclaw/skills/asr-hotwords/ and run pip install -r requirements.txt. The dependency list (jieba, pypinyin, openai, anthropic, pyyaml) is reasonable for the task. Because installation is manual and dependencies come from PyPI, risk is moderate but expected; however the absence of a declared install step in metadata is an inconsistency.

Credentials

No environment variables or config paths are declared in the registry metadata, yet the code explicitly reads ~/.openclaw/openclaw.json to obtain API keys/base URLs and it scans ~/.openclaw/agents for session files and may write MIGRATED.md into old per-agent skill directories. Access to LLM credentials and every agent's session history is required by the functionality but was not declared up front — this is a proportionality/documentation problem and increases privacy risk if you didn't expect global access.

Persistence & Privilege

The skill does not set always: true. It creates local marker files (.installed, .cron_configured) and migrate.py will write MIGRATED.md into old per-agent directories and copy historical vocab files into the new skill output directory. It also issues 'openclaw gateway call agent' commands to request agents update DMWork voice-context automatically. Those actions modify other workspace directories and can trigger remote agent behavior — legitimate for migration/integration but worth explicit user consent.

What to consider before installing

This skill appears to implement the advertised hotword-mining pipeline, but before installing you should: - Confirm you are comfortable giving the skill READ access to ~/.openclaw/agents/*/sessions (it will scan all agents' conversations) and READ access to ~/.openclaw/openclaw.json (it reads your configured LLM apiKey/baseUrl). - Review the included Python files (especially migrate.py, extract_sessions.py, run.py, and build_words.py) yourself — they will copy old vocab files into the new skill directory and write MIGRATED.md into old per-agent skill directories. - Note the skill will attempt to call the OpenClaw CLI (openclaw gateway call agent) to notify agents to inject hotwords into DMWork contexts; ensure you understand and approve what that command does in your environment. - If you accept the functionality: back up ~/.openclaw/agents and ~/.openclaw/openclaw.json beforehand, and consider running the pipeline on a limited agent subset (edit config.yaml 'extract.agents') before allowing full "all agents" runs. - Ask the skill author/maintainer to correct the registry metadata to declare the required config paths (~/.openclaw/openclaw.json, ~/.openclaw/agents) and to explicitly document migration and automated injection behaviors so users can give informed consent. If you are not willing to expose full session histories or to permit automatic DMWork injections, do not install or run this skill.

ASR Hotwords — OpenClaw Skill

功能

从 OpenClaw 所有 agent 的对话记录中自动挖掘热词/歧义词表，供 ASR 模型提升语音转录准确性。

Pipeline: 提取所有 session 对话 → 本地热词挖掘（jieba 分词 + LLM 精炼） → 输出歧义词表 → 自动导出 hotwords.md

触发条件

用户说以下类似的话时触发此 skill：

• "挖掘对话中的热词"
• "提取对话歧义词"
• "跑一下热词挖掘"
• "更新热词表"

安装流程

当用户要求安装/启用此 skill 时，按以下步骤执行：

注意：以下所有路径中的 SKILL_DIR 指此 SKILL.md 所在目录（即 skill 的根目录）。执行时用 read 工具获取本文件路径，取其父目录即可。

Step 1: 安装 Skill

将 skill 安装到 ~/.openclaw/skills/asr-hotwords/。

# 如果是从其他位置安装
cp -r <source> ~/.openclaw/skills/asr-hotwords/

Step 2: 旧版迁移（自动）

运行迁移脚本，自动检测旧版 per-agent 安装并合并数据：

cd SKILL_DIR && python3 migrate.py

迁移脚本会：

• 扫描所有 agent workspace 下的旧版 asr-hotwords 或 asr-personal-hotwords 目录
• 合并 output/vocab_*.json 历史挖掘结果到新位置（不覆盖）
• 迁移 .installed / .cron_configured 标记文件
• 迁移 hotwords.md
• 在旧目录写入 MIGRATED.md 标记

如果没有旧版安装，脚本会提示"无需迁移"并跳过。

Step 3: 安装依赖

pip3 install -r SKILL_DIR/requirements.txt --quiet

Step 4: 验证 OpenClaw LLM 配置

检查 ~/.openclaw/openclaw.json 中是否存在有效的 provider 配置（apiKey + baseUrl）。

Step 5: 测试运行

用前一天的数据跑一次完整 pipeline，确认端到端流程正常：

cd SKILL_DIR && nohup bash run.sh > run.log 2>&1 &

运行完成后会自动导出 hotwords.md。可通过 tail -f SKILL_DIR/run.log 查看进度。

Step 6: 设置安装标记

touch SKILL_DIR/.installed

安装完成，通知用户 skill 已就绪。

首次使用引导

当用户首次触发此 skill 时（通过触发条件中的关键词），检查 SKILL_DIR 下是否存在 .cron_configured 文件：

如果 .cron_configured 不存在（首次使用）：

在执行挖掘之前，先向用户提问：

"这是首次使用热词挖掘 skill。是否需要设置每日定时执行？（推荐：每天凌晨自动挖掘前一天的对话热词并更新 hotwords.md）"

• 用户同意：询问执行时间（默认 02:00），创建 OpenClaw cron 定时任务（sub-agent 方式），然后创建 .cron_configured 文件
• 用户拒绝：直接创建 .cron_configured 文件（标记为已询问，不再重复提问）

touch SKILL_DIR/.cron_configured

如果 .cron_configured 已存在： 跳过引导，直接执行。

手动执行

默认：挖掘前一天

cd SKILL_DIR && nohup bash run.sh > run.log 2>&1 &

指定日期

cd SKILL_DIR && nohup bash run.sh --date 2026-04-26 > run.log 2>&1 &

指定日期范围

cd SKILL_DIR && nohup bash run.sh --start 2026-04-20 --end 2026-04-26 > run.log 2>&1 &

仅导出热词表（不重新挖掘）

cd SKILL_DIR && bash run.sh --export-only
cd SKILL_DIR && bash run.sh --export-only -f json -o hotwords.json
cd SKILL_DIR && bash run.sh --export-only -f csv -o hotwords.csv
cd SKILL_DIR && bash run.sh --export-only -f txt

执行完成后，向用户汇报：

• 提取了多少条消息
• 挖掘出多少条热词
• 展示 top 10 热词

输出文件

文件	说明
output/vocab_{date}.json	原始挖掘结果（按日期存档）
hotwords.md	热词表（每次运行自动导出，prompt 格式，供 ASR 模型直接使用）

DMWork 语音纠错上下文注入

挖掘完成后，run.py 会自动通过 openclaw gateway call agent 发送结构化消息给 agent。

agent 收到消息后必须执行：

1. 读取 SKILL_DIR/hotwords.md
2. 调用 dmwork_management(action="voice-context-update", content=文件内容)
3. 调用 dmwork_management(action="voice-context-read") 验证注入成功

如果是手动执行挖掘，agent 在汇报结果后也应主动执行上述注入步骤。

配置

编辑 config.yaml：

• extract.agents：要提取的 agent 列表（["*"] 为全部，或指定如 ["main", "claude"]）
• extract.max_content_len：单条消息最大字符数
• extract.min_freq：最低词频阈值

LLM API key 和模型信息自动从 ~/.openclaw/openclaw.json 读取，无需手动配置。

锚点词表机制

• 首次运行：anchors 为空
• 后续运行：自动加载 output/ 目录下所有历史 vocab 结果作为 anchors（合并去重）
• 词表只增不减，持续积累