elevenlabs-stt

Add ElevenLabs Speech-to-Text to OpenClaw's normal inbound audio pipeline (tools.media.audio).

The plugin is intentionally simple to use: install it, add an ElevenLabs provider block, and point an audio model entry at provider: elevenlabs. It also exposes selected ElevenLabs request options through providerOptions.elevenlabs, so you can tune transcript quality and behavior without leaving normal OpenClaw config.

Prerequisites
Quick start
Configuration
Provider options
What this plugin covers
Compatibility
Development
Documentation
License

Prerequisites

OpenClaw >=2026.3.24
Node.js >=22.14.0
An ElevenLabs API key

Quick start

Install with OpenClaw:

openclaw plugins install @mkv21/elevenlabs-stt

Use the scoped package name for OpenClaw installs. On current OpenClaw versions, the unscoped name elevenlabs-stt collides with an existing ClawHub skill during resolver lookup.

Warning Before restarting the OpenClaw Gateway after installation, add the full models.providers.elevenlabs config block shown below. If the plugin is enabled but the provider block is missing or incomplete, OpenClaw can fail validation during startup and the Gateway may no longer start.

Minimal working config:

plugins:
  entries:
    elevenlabs-stt:
      enabled: true

models:
  providers:
    elevenlabs:
      baseUrl: https://api.elevenlabs.io/v1
      apiKey: ${ELEVENLABS_API_KEY}
      models: []

tools:
  media:
    audio:
      enabled: true
      timeoutSeconds: 90
      language: en
      models:
        - provider: elevenlabs
          model: scribe_v2

Important notes:

models.providers.elevenlabs.models: [] is currently required by OpenClaw's shared provider config shape.

If you prefer an explicit env-backed secret ref, you can use:

apiKey:
  source: env
  provider: default
  id: ELEVENLABS_API_KEY

If you want fallback behavior, add additional entries after the ElevenLabs model in tools.media.audio.models.

Configuration

Field	Default	Description
`models.providers.elevenlabs.baseUrl`	`https://api.elevenlabs.io/v1`	Base URL for ElevenLabs API
`models.providers.elevenlabs.apiKey`	—	Required. ElevenLabs API key
`models.providers.elevenlabs.models`	—	Must be `[]` (required by OpenClaw's provider config shape)
`tools.media.audio.models[].provider`	—	Must be `elevenlabs` for this plugin
`tools.media.audio.models[].model`	`scribe_v2`	ElevenLabs STT model ID
`tools.media.audio.language`	—	Global language hint passed as `language_code`
`tools.media.audio.models[].language`	—	Per-entry language override
`tools.media.audio.timeoutSeconds`	—	Global request timeout in seconds
`tools.media.audio.models[].timeoutSeconds`	—	Per-entry request timeout override

Provider options

Tune the upstream ElevenLabs request through providerOptions.elevenlabs, set globally on tools.media.audio.providerOptions.elevenlabs or per model entry on tools.media.audio.models[].providerOptions.elevenlabs.

Option	Type	Default	Description
`tag_audio_events`	boolean	—	Include audio-event cues in transcript text
`no_verbatim`	boolean	—	Cleaner transcript with fillers and false starts reduced (`scribe_v2`)
`diarize`	boolean	—	Enable speaker diarization
`num_speakers`	number	—	Expected number of speakers for diarization
`diarization_threshold`	number	—	Diarization sensitivity threshold
`use_multi_channel`	boolean	—	Treat input as separate speaker channels
`timestamps_granularity`	string	—	Timestamp level: `word` or `character`
`entity_detection`	string	—	Entity detection mode (e.g. `pii`)
`redact`	boolean	—	Enable transcript redaction
`entity_redaction`	string	—	Entity redaction behavior
`temperature`	number	—	Transcription generation temperature
`seed`	number	—	Transcription generation seed
`file_format`	string	—	Override audio format detection

Example:

tools:
  media:
    audio:
      providerOptions:
        elevenlabs:
          no_verbatim: true
          tag_audio_events: true
      models:
        - provider: elevenlabs
          model: scribe_v2

Note: OpenClaw currently consumes only the plain transcript text. Options whose main value is extra metadata (timestamps, speakers, channels, entities) are forwarded to ElevenLabs but not yet surfaced through OpenClaw's current audio result shape. Array-shaped options such as keyterms and additional_formats are not supported because current OpenClaw media providerOptions are scalar-only.

What this plugin covers

Normal inbound audio transcription only
No telephony, realtime/streaming, or async webhook-based transcription flow

Compatibility

Tested locally with OpenClaw 2026.3.24
Requires OpenClaw host version >=2026.3.24

Development

# Run tests
npm test

# Type check
npm run typecheck

Documentation

Configuration Reference and Troubleshooting

AI-Assisted Development Disclaimer

Parts of this project were developed with assistance from generative AI tools. All generated code and text were reviewed and adapted by a human before publication.

License

This project is licensed under the MIT License. See LICENSE for details.

ElevenLabs STT

elevenlabs-stt

Table of contents