Agent Skills › malpern/VoxClaw › voxclaw

voxclaw

GitHub

提供智能体语音播报能力，通过 CLI、URL Scheme 或 HTTP API 将文本转换为语音输出。支持 macOS 环境下的 VoxClaw 工具集成，用于实现非视觉交互场景。

plugins/voxclaw/skills/voxclaw/SKILL.md malpern/VoxClaw

Trigger Scenarios

需要语音播报生成音频反馈

Install

npx skills add malpern/VoxClaw --skill voxclaw -g -y

More Options

Non-standard path

npx skills add https://github.com/malpern/VoxClaw/tree/main/plugins/voxclaw/skills/voxclaw -g -y

Use without installing

npx skills use malpern/VoxClaw@voxclaw

指定 Agent (Claude Code)

npx skills add malpern/VoxClaw --skill voxclaw -a claude-code -g -y

安装 repo 全部 skill

npx skills add malpern/VoxClaw --all -g -y

预览 repo 内 skill

npx skills add malpern/VoxClaw --list

SKILL.md

Frontmatter

{
    "name": "voxclaw",
    "homepage": "https:\/\/github.com\/malpern\/VoxClaw",
    "metadata": {
        "requires": {
            "bins": [
                "curl"
            ]
        }
    },
    "description": "Give your agent a voice. Send text to a Mac running VoxClaw and hear it spoken aloud with OpenAI neural voices or Apple TTS."
}

VoxClaw

Use this skill when the user wants audible output from an agent.

VoxClaw runs on macOS as a menu bar app and can speak text through:

the local voxclaw CLI
the voxclaw://read?text=... URL scheme
the HTTP listener, usually on port 4140

Preferred flow

If the human provides a VoxClaw setup pointer, use the provided health_url and speak_url directly.

Connection order:

Use plugins/voxclaw/scripts/voxclaw-say --health when working in this repo.
If a pointer is available, pass its speak_url or health_url to the helper.
Otherwise let the helper probe http://localhost:4140/status.
The helper falls back to the local voxclaw CLI when needed.

Never guess a .local hostname if the user already supplied a numeric LAN IP.

Preferred command

Default to the helper script instead of open-coded curl:

plugins/voxclaw/scripts/voxclaw-say "Hello from the agent"
plugins/voxclaw/scripts/voxclaw-say --health
plugins/voxclaw/scripts/voxclaw-say --url http://192.168.1.50:4140/read "Deployment complete"
plugins/voxclaw/scripts/voxclaw-say --voice nova --rate 1.2 "Build failed"
plugins/voxclaw/scripts/voxclaw-say --instructions "Read warmly" "Welcome back"
plugins/voxclaw/scripts/voxclaw-say --project-id /Users/me/myproject "Update from my project"

HTTP API

Health check:

curl -sS http://localhost:4140/status

Speak text:

curl -X POST http://localhost:4140/read \
  -H 'Content-Type: application/json' \
  -d '{"text":"Hello","project_id":"/Users/me/myproject","agent_id":"my-agent"}'

Optional fields: voice, rate, instructions, project_id, agent_id.

Acknowledge (user has read the response, skip speaking it):

curl -X POST http://localhost:4140/ack \
  -H 'Content-Type: application/json' \
  -d '{"project_id":"/Users/me/myproject"}'

CLI fallback

voxclaw "Hello"
voxclaw --clipboard
voxclaw --voice nova "Build passed"
voxclaw --send "Hello"   # send to an already running listener
voxclaw --status