Forem: Neurl Creators

Understanding OpenClaw’s Hook: The Key to Evaluating Agents Properly

Youdiowei Eteimorde — Wed, 22 Apr 2026 12:41:26 +0000

Working with a tool like OpenClaw can sometimes feel like a black box, with many moving parts that make it hard to understand what is happening under the hood. However, OpenClaw’s Hook functionality changes that by giving you clear visibility into your agent’s behavior.

OpenClaw Hooks let you monitor events as they occur in real time, such as when a message is received or a tool call is made, providing detailed insight into your agent’s execution flow. When combined with an LLM observability tool, they make it easier to debug issues, understand decision-making, and optimize performance.

In this article, we’ll break down how Hooks work and then explore how to integrate them with Arize for monitoring and improving your agent.

Get your agent to set up the code for this article using the Agent’s skill

Hooks in OpenClaw

Within OpenClaw, whenever an action occurs, an event is fired to signal that the action has taken place. For example, when a user sends a message, an event is triggered to indicate this interaction. Similarly, when the agent responds or uses a tool, corresponding events are fired.

OpenClaw Hooks allow you to attach additional logic to these events as they occur. In essence, hooks enable you to tap into OpenClaw’s event-driven system, giving you the ability to customize, and extend the system’s behavior.

OpenClaw hooks can be divided into the following categories:

Agent lifecycle: Hooks triggered during the agent’s execution.
Message flow: Hooks related to messages entering and leaving the system.
Tool execution: Hooks triggered before and after tool execution.
Subagent coordination: Hooks triggered when subagents are invoked.
Gateway lifecycle: Hooks triggered during the OpenClaw gateway’s operation.

With all these hooks at our disposal, we gain visibility into a system that would otherwise be a black box.

The need for Observability in Agents

Observability is essential for understanding how an AI agent or LLM behaves and why it performs tasks in a certain way. Without it, you’re effectively running your agent in isolation, constantly guessing what went wrong.

OpenClaw is no exception. In fact, it requires strong observability for a few key reasons:

Sensitive operations: It often runs directly on a user’s machine and may handle sensitive tasks, making visibility critical.
Autonomous behavior: It can operate proactively through features like heartbeats or cron jobs, executing tasks without direct user input.
System complexity: A single interaction may involve multiple tool calls and internal steps, making it harder to track what’s happening under the hood.

To address these challenges, observability becomes a necessity. Observing a system like OpenClaw requires a dedicated observability tool, and this is where Arize comes in.

Arize is a leading platform for LLM and agent observability, enabling developers to instrument their applications and capture every input and output flowing through the system.

This captured data is then sent to Arize using the OpenTelemetry protocol, where it can be monitored and analyzed in detail.

Instrumentation is relatively straightforward when building applications from scratch, as Arize provides integrations for many LLM and agent frameworks. However, it becomes more challenging when working with an existing system like OpenClaw.

Fortunately, OpenClaw’s hooks provide a solution. By leveraging hooks, we can instrument the agent and gain the visibility needed to properly monitor and evaluate its behavior.

Creating Hooks in OpenClaw

OpenClaw provides two ways to create hooks: directly within the project or through plugins.

The direct method involves creating a hook directory containing two key files:

HOOK.md – defines the hook’s metadata and documentation.
handler.ts – implements the hook’s logic.

The second method is to create a plugin that utilizes hooks. In this article, we will focus on plugin hooks because they offer greater flexibility and are much easier to distribute and reuse.

To learn more about creating hooks directly, refer to the OpenClaw documentation.

Building a Simple Plugin Hook

Let’s create a simple plugin that leverages hooks.

1. Initialize the Project

Start by creating a TypeScript npm project named arize_openclaw_hook. Then install OpenClaw as a dependency:

npm install openclaw

Ensure that OpenClaw is already installed and properly configured on your system or in the environment where it is running.

Below is an example of what your package.json might look like:

{
  "name": "arize_openclaw_hook",
  "version": "1.0.0",
  "description": "",
  "main": "index.ts",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "openclaw": {
    "extensions": [
      "./index.ts"
    ],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2",
      "pluginSdkVersion": "2026.3.24-beta.2"
    }
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "module",
  "dependencies": {
    "openclaw": "^2026.3.28"
  }
}

We’ve also included additional metadata such as the OpenClaw version and Plugin SDK version.

2. Create the Plugin Manifest

All OpenClaw plugins require a manifest file named Openclaw.plugin.json, which contains metadata about the plugin:

{
  "id": "arize_openclaw_hook",
  "name": "Arize OpenClaw Hook",
  "description": "Observability plugin for OpenClaw with Arize.",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
  },
}

Note: The plugin id should match the name of the npm project.

3. Define the Plugin Entry

Next, create an index.ts file to define the plugin:

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
    id: "arize_openclaw_hook",
    name: "Arize OpenClaw Hook",
    description: "Observability plugin for OpenClaw with Arize.",
    register(api) {
        api.registerService(arizeService(api));
    },
});

The definePluginEntry function accepts an object with the plugin’s metadata and a register method. This method is used to register the plugin’s functionality with OpenClaw.

4. Implement the Plugin Service

We will register our plugin as a background service using api.registerService. A service must return an OpenClawPluginService object:

export type OpenClawPluginService = {
    id: string;
    start: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
    stop?: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
};

id: Uniquely identifies the service.
start: Executed when the plugin starts.
stop: Optional method executed during shutdown for cleanup.

Here is a minimal implementation:

function arizeService(api: OpenClawPluginApi): OpenClawPluginService {

    api.logger.info("Initializing Arize OpenClaw Hook service...");

    return {
        id: "arize-openclaw",
        async start(ctx: OpenClawPluginServiceContext) {
            const log = { info: ctx.logger.info.bind(ctx.logger) };

            log.info("Arize OpenClaw Hook service is starting...");
        },
        async stop(ctx: OpenClawPluginServiceContext) {
            const log = { info: ctx.logger.info.bind(ctx.logger) };

            log.info("Arize OpenClaw Hook service is stopping...");
        }
    };
}

This service simply logs messages using the OpenClaw logger. The api.logger is available during registration, while ctx.logger is used within the start and stop lifecycle methods.

5. Adding Hooks to the Service

Next, we attach hooks to listen for specific OpenClaw events:

llm_input – Triggered when the LLM receives a prompt.
llm_output – Triggered when the LLM generates a response.
before_tool_call – Triggered before the agent invokes a tool.

import { definePluginEntry,OpenClawPluginApi,OpenClawPluginService, OpenClawPluginServiceContext} from "openclaw/plugin-sdk/plugin-entry";


function arizeService(api: OpenClawPluginApi): OpenClawPluginService {

    api.logger.info("Initializing Arize OpenClaw Hook service...");

    api.on("llm_input", (event) => {
       api.logger.info(`Prompt: ${event.prompt}`);
       api.logger.info(`Model name: ${event.model}`);
       api.logger.info(`Model provide: ${event.provider}`);
    });

    api.on("llm_output", (event) => {
        api.logger.info(`Assistant Texts: ${event.assistantTexts.toString()}`);
    });

    api.on("before_tool_call", (event) => {
        api.logger.info(`Tool Name: ${event.toolName}`);
        api.logger.info(`Tool Call ID: ${event.toolCallId}`);
    });

    return {
        id: "arize-openclaw",
        async start(ctx: OpenClawPluginServiceContext) {
            const log = { info: ctx.logger.info.bind(ctx.logger) };
            log.info("Arize OpenClaw Hook service is starting...");
        },
        async stop(ctx: OpenClawPluginServiceContext) {
            const log = { info: ctx.logger.info.bind(ctx.logger) };
            log.info("Arize OpenClaw Hook service is stopping...");
        }
    };
}

export default definePluginEntry({
    id: "arize_openclaw_hook",
    name: "Arize OpenClaw Hook",
    description: "Observability plugin for OpenClaw with Arize.",
    register(api) {
        api.registerService(arizeService(api));
    },
});

Event Data Overview

llm_input: Contains the prompt, model name, and provider.
llm_output: Includes the assistant’s generated response.
before_tool_call: Provides details about the tool being invoked, such as its name and call ID.

6. Installing and Testing the Plugin

Once the implementation is complete, install the plugin locally:

openclaw plugins install .

After installation, restart the OpenClaw gateway to activate the plugin:

openclaw gateway restart

Next, we need to open the OpenClaw dashboard to communicate with the agent. We can do this using the following command:

openclaw dashboard

Once the dashboard is open, you can send a message to the agent from the Chat section in the sidebar.

Next, go to Logs in the sidebar and verify that the data was logged.

From the image above, we can see that the data was successfully logged, confirming that our plugin works as expected. Next, we need to add instrumentation so that instead of being logged locally, the data is sent to the Arize server.

Hooks + Observervability = Better Agent

In this section, we’ll extend the plugin from the previous section and add instrumentation so we can observe the agent’s behavior in Arize instead of relying only on local logs.

Installing Instrumentation Dependencies

First, install the required OpenTelemetry and Arize instrumentation packages:

npm install @opentelemetry/api @opentelemetry/exporter-trace-otlp-proto @opentelemetry/resources @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node @opentelemetry/semantic-conventions @arizeai/openinference-semantic-conventions openai

Configuring Arize Credentials

Next, we need to configure the credentials required to send traces to Arize:

ARIZE_API_KEY: Your Arize API key
ARIZE_SPACE_ID: Your Arize space ID
ARIZE_PROJECT_NAME: The name of your project Normally, these would be stored in an environment file. However, since we are working within OpenClaw, the better approach is to expose them as configurable plugin values via the manifest file.

We update Openclaw.plugin.json to include these configuration values:

{
  "id": "arize_openclaw_hook",
  "name": "Arize OpenClaw Hook",
  "description": "Observability plugin for OpenClaw with Arize.",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "spaceID": {
        "type": "string"
      },
      "apiKey": {
        "type": "string"
      },
      "projectName": {
        "type": "string"
      }
    }
  },
  "uiHints": {
    "apiKey": {
      "label": "Arize API Key",
      "placeholder": "your-api-key",
      "sensitive": true
    },
    "spaceID": {
      "label": "Arize Space ID",
      "placeholder": "your-space-id",
      "help": "The ID of the Arize space to use."
    },
    "projectName": {
      "label": "Project Name",
      "placeholder": "openclaw"
    }
  }
}

These values can now be set either in openclaw.json or directly from the dashboard thanks to the UI hints defined above.

Adding Instrumentation

Next, we implement instrumentation to connect OpenClaw to Arize. This involves initializing an OpenTelemetry tracer that sends spans to the Arize server.

function arizeService(api: OpenClawPluginApi): OpenClawPluginService {

    const COLLECTOR_ENDPOINT = "https://otlp.arize.com";
    const SERVICE_NAME = process.env.ARIZE_PROJECT_NAME || "";

    api.logger.info(`Initializing Arize OpenClaw Hook with service name: ${SERVICE_NAME}`);

    const provider = new NodeTracerProvider({
        resource: resourceFromAttributes({
            [ATTR_SERVICE_NAME]: SERVICE_NAME,
            [SEMRESATTRS_PROJECT_NAME]: SERVICE_NAME,
        }),
        spanProcessors: [
            new SimpleSpanProcessor(
                new OTLPTraceExporter({
                    url: `${COLLECTOR_ENDPOINT}/v1/traces`,
                    headers: {
                        'space_id': process.env.ARIZE_SPACE_ID || "",
                        'api_key': process.env.ARIZE_API_KEY || "",
                    },
                })
            ),
        ],
    });

    provider.register();

    const tracer = trace.getTracer(SERVICE_NAME); 

    return {
        id: "arize-openclaw",
        async start(ctx: OpenClawPluginServiceContext) {
            const log = { info: ctx.logger.info.bind(ctx.logger) };

            log.info("Arize OpenClaw Hook service is starting...");
        },
        async stop(ctx: OpenClawPluginServiceContext) {
            const log = { info: ctx.logger.info.bind(ctx.logger) };
            log.info("Arize OpenClaw Hook service is stopping...");
        }
    };
}

At this point, we have instrumentation configured, but no hooks attached yet.

Connecting Hooks to Traces

In the code below, we added our hooks as before, but this time we use the tracer to create spans that instrument all calls and send them to Arize.

function arizeService(api: OpenClawPluginApi): OpenClawPluginService {

    // Remaining code above

    api.on("llm_input", (event) => {
        tracer.startActiveSpan("call-llm", async (span) => {
            span.setAttribute(SemanticConventions.OPENINFERENCE_SPAN_KIND, OpenInferenceSpanKind.CHAIN);
            span.setAttribute(INPUT_VALUE, event.prompt);
            span.setAttribute(LLM_MODEL_NAME, event.model);
            span.setAttribute(LLM_PROVIDER, event.provider);


            api.on("llm_output", (event) => {
                span.setAttribute(OUTPUT_VALUE, event.assistantTexts.toString());
                span.setStatus({ code: SpanStatusCode.OK });
                span.end();
            });
        });
    });

    api.on("before_tool_call", (event) => {
        const span = tracer.startSpan("tool-call");
        span.setAttribute(SemanticConventions.OPENINFERENCE_SPAN_KIND, OpenInferenceSpanKind.TOOL);
        span.setAttribute(TOOL_NAME, event.toolName);
        span.setAttribute(TOOL_CALL_ID, event.toolCallId || "unknown");
        span.setStatus({ code: SpanStatusCode.OK });
        span.end();
    });

    // Remaining code below
}

Here is the full implementation:

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import type { OpenClawPluginApi, OpenClawPluginService , OpenClawPluginServiceContext } from "openclaw/plugin-sdk";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
import { SEMRESATTRS_PROJECT_NAME } from "@arizeai/openinference-semantic-conventions";


import { trace, SpanStatusCode } from "@opentelemetry/api";
import {
    INPUT_VALUE, OUTPUT_VALUE, LLM_MODEL_NAME, LLM_PROVIDER, SemanticConventions, TOOL_NAME, TOOL_PARAMETERS, TOOL_CALL_ID,
    OpenInferenceSpanKind
} from "@arizeai/openinference-semantic-conventions";


function arizeService(api: OpenClawPluginApi): OpenClawPluginService {

    const COLLECTOR_ENDPOINT = "https://otlp.arize.com";
    const SERVICE_NAME = process.env.ARIZE_PROJECT_NAME || "";

    api.logger.info(`Initializing Arize OpenClaw Hook with service name: ${SERVICE_NAME}`);

    const provider = new NodeTracerProvider({
        resource: resourceFromAttributes({
            [ATTR_SERVICE_NAME]: SERVICE_NAME,
            [SEMRESATTRS_PROJECT_NAME]: SERVICE_NAME,
        }),
        spanProcessors: [
            new SimpleSpanProcessor(
                new OTLPTraceExporter({
                    url: `${COLLECTOR_ENDPOINT}/v1/traces`,
                    headers: {
                        'space_id': process.env.ARIZE_SPACE_ID || "",
                        'api_key': process.env.ARIZE_API_KEY || "",
                    },
                })
            ),
        ],
    });

    provider.register();

    const tracer = trace.getTracer(SERVICE_NAME);


    api.on("llm_input", (event) => {
        tracer.startActiveSpan("call-llm", async (span) => {
            span.setAttribute(SemanticConventions.OPENINFERENCE_SPAN_KIND, OpenInferenceSpanKind.CHAIN);
            span.setAttribute(INPUT_VALUE, event.prompt);
            span.setAttribute(LLM_MODEL_NAME, event.model);
            span.setAttribute(LLM_PROVIDER, event.provider);


            api.on("llm_output", (event) => {
                span.setAttribute(OUTPUT_VALUE, event.assistantTexts.toString());
                span.setStatus({ code: SpanStatusCode.OK });
                span.end();
            });
        });
    });

    api.on("before_tool_call", (event) => {
        const span = tracer.startSpan("tool-call");
        span.setAttribute(SemanticConventions.OPENINFERENCE_SPAN_KIND, OpenInferenceSpanKind.TOOL);
        span.setAttribute(TOOL_NAME, event.toolName);
        span.setAttribute(TOOL_CALL_ID, event.toolCallId || "unknown");
        span.setStatus({ code: SpanStatusCode.OK });
        span.end();
    });


    return {
        id: "arize-openclaw",
        async start(ctx: OpenClawPluginServiceContext) {
            const log = { info: ctx.logger.info.bind(ctx.logger) };

            log.info("Arize OpenClaw Hook service is starting...");
        },
        async stop(ctx: OpenClawPluginServiceContext) {
            const log = { info: ctx.logger.info.bind(ctx.logger) };
            log.info("Arize OpenClaw Hook service is stopping...");
        }
    };
}

export default definePluginEntry({
    id: "arize_openclaw_hook",
    name: "Arize OpenClaw Hook",
    description: "Observability plugin for OpenClaw with Arize.",
    register(api) {
        api.registerService(arizeService(api));
    },
});

Testing the Plugin

Now that we have observability in place, let’s test the plugin again.

In the OpenClaw dashboard, I created a new chat session. When a session starts, OpenClaw loads memory and other contextual data using internal tools.

Switching to the Arize dashboard, we can see that all tool calls and the new session events are being sent successfully.

If we inspect the session creation event, we can see:

Input message captured
Output recorded
Additional metadata such as latency and execution details

You can get the full source code implementation here on github.

Conclusion

OpenClaw’s hooks are a powerful feature that let you tap directly into the system’s internal events. By wrapping hooks inside a plugin, you can fully customize your OpenClaw agent and extend its capabilities in meaningful ways.

In this article, we used that flexibility to add observability to our agent using Arize. Observability is critical when working with systems like OpenClaw, where agents are complex, autonomous, and often operate behind multiple layers of abstraction. With the right instrumentation in place, you move from guessing what your agent is doing to clearly understanding its behavior in real time.

Building A Voice AI Agent with OpenClaw and AssemblyAI

Youdiowei Eteimorde — Fri, 17 Apr 2026 05:37:29 +0000

OpenClaw went viral this year because of its simplicity in allowing users to communicate with AI agents running on their own hardware. It wasn’t a new model, a new architecture, or a new agentic protocol. Instead, it demonstrated a new way people could work with AI agents using technology they were already familiar with.

OpenClaw allows users to communicate with their agents through chat apps such as Telegram and WhatsApp. A user can simply pick up their device and send a text message to the AI agent. This ease of use is what attracted many users to OpenClaw.

But can this interaction be simplified even further? Yes, it can. One way to do this is by turning your OpenClaw agent into a voice AI agent. Since OpenClaw already works through chat apps, and most of these apps support voice notes, voice interaction becomes a natural extension of the system.

In this article, we will show you how to set up OpenClaw as a voice AI agent. We will also demonstrate how to bring your own speech-to-text model and integrate it with OpenClaw. The model we will use is Universal-3 Pro, and we will explore how its prompting capabilities can be used to create a more customized voice interaction experience.

OpenClaw in a nutshell

There is a lot of confusion surrounding OpenClaw. Even the name itself creates confusion. So in this section, we will do a quick breakdown of what OpenClaw is and how it works.

What is OpenClaw?

You can think of OpenClaw as a gateway between your chat app and your AI agent.

The chat app can be Telegram, WhatsApp, or Slack. The AI agent can be powered by cloud-based Large Language Models (LLMs) such as those provided by Anthropic or OpenAI, or even by a locally hosted model.

The AI agent also has access to a computer system. This could be your personal computer (though this is not advisable), a Mac Mini, a Raspberry Pi, or a cloud server.

The OpenClaw setup consists of the following:

The chat application serves as the user interface
OpenClaw acts as the orchestrator
The AI agent is the brain
The computer serves as the universal tool.

What makes openclaw different?

Agents are not a new concept. Agents that have access to a computer are not new either, and chatting with AI is certainly not new.

However, two things make OpenClaw stand out.

The first is the medium of communication. Unlike many chatbots that require you to use a separate app or a dedicated website, OpenClaw allows you to communicate with your agent through the chat apps you already use.

The second difference is that the OpenClaw agent is more proactive. It is not just another chat session. The agent can maintain memory, send reminders about tasks it is working on, and interact with the computer it has access to.

Since the agent has access to the system, it can perform actions such as reading files, editing files, and running commands. In many ways, OpenClaw feels like giving a personal computer to an AI assistant.

Setting up openclaw

When it comes to installing openclaw they are several different options you can choose. The easiest option is to install it on your personal computer but this is not advisable since an AI agent will have full control over your computer and a lot security experts have warned several security vulnerabilities on openclaw.

But running on your personal computer is the fastest way to experiment with it. The other option is have a dedicated computer for openclaw such as mac mini or a raspberry pi. Another option is to run openclaw within container using docker that way it is sandboxed.

If you’re on Mac or Linux, you can install OpenClaw with this one-liner:

curl -fsSL https://openclaw.ai/install.sh | bash

Then set it up by running:

openclaw onboard --install-daemon

This will prompt you to configure your model. The --install-daemon flag sets up OpenClaw as a background service, so it runs automatically whenever your device starts.

Once setup is complete, you can confirm everything is running with:

openclaw gateway status

For other installation methods, refer to the official OpenClaw installation guide.

Setting up a channel for communication

When OpenClaw is installed, the next thing you need to do is set up the channel of communication. This is essentially the chat app you wish to use to communicate with OpenClaw from.

All channels support communication via text, but since we are working with a voice agent, we want one that can support other media types, such as audio. Telegram is perfect for this because it offers the easiest setup compared to other channels, and you can send voice notes to the openclaw via Telegram.

Go through the setup guide on Telegram on openclaw documentation.

OpenClaw’s media understanding capabilities

OpenClaw’s media understanding capabilities allow it to process more than just text. When it receives a media file, such as an image or audio, it can use one of its model providers to transform it into a format the agent can understand.

For example, if OpenClaw receives a voice note from a channel like Telegram, it will use a speech-to-text (STT) model to convert the audio into text before passing it to the LLM. Similarly, if it receives an image, it can summarize the content using an image model and send that information to the agent. In this article, we are focusing on the audio understanding aspect of OpenClaw.

By default, OpenClaw supports a limited set of STT providers, including OpenAI, Mixtral Voxtral, and Deepgram. In this guide, we’ll go a step further by integrating a custom STT model, extending OpenClaw beyond its built-in options.

Bring your own Speech To Text model

There are several ways to extend OpenClaw’s capabilities, one of which is via plugins. While writing a plugin to perform media understanding is possible, it is often overkill. OpenClaw already provides a built-in way to extend media understanding using a custom script.

With a custom script, you simply tell OpenClaw that whenever it receives an audio file, it should run the script. The script processes the audio and returns the transcribed text. All the heavy lifting is handled by OpenClaw. You just need to write the script and configure the openclaw.json.

Since we get to write the script, we can choose any STT model provider. In this guide, we will use AssemblyAI.

Step 1: Set Up Your Environment

It is best to create a dedicated Python environment first. Then, install the AssemblyAI SDK:

pip install assemblyai

Next, create an AssemblyAI API key and store it in an environment variable:

export ASSEMBLYAI_API_KEY="your_api_key_here"

For global access, it is recommended to add this line to your .bashrc or .zshrcfile.

Step 2: Create the Transcription Script

Create a Python file called main.py and add the following:

import argparse
import os
import sys
import assemblyai as aai


def main():
    # 1. Set up the argument parser
    parser = argparse.ArgumentParser(
        description="Transcribe an audio file using AssemblyAI."
    )

    # Add positional argument for the audio file path
    parser.add_argument(
        "audio_file", 
        type=str, 
        help="Path to the audio file you want to transcribe (e.g., ./voice_note.ogg)"
    )

    # Add optional argument for the API key
    parser.add_argument(
        "--api-key", 
        type=str, 
        help="Your AssemblyAI API key (can also be set via ASSEMBLYAI_API_KEY env variable)",
        default=None
    )

    args = parser.parse_args()

    # 2. Configure API Key
    api_key = args.api_key or os.environ.get("ASSEMBLYAI_API_KEY")
    if not api_key:
        print("Error: API key is missing.")
        print("Please set the ASSEMBLYAI_API_KEY environment variable or pass it via --api-key.")
        sys.exit(1)

    aai.settings.api_key = api_key

    # 3. Configure and run the transcription
    config = aai.TranscriptionConfig(speech_models=["universal-3-pro"], 
                                     language_detection=True, 
                                     prompt="Transcribe the audio make sure include fillers and stutters in the transcript.")

    print(f"Transcribing '{args.audio_file}'... Please wait.")

    try:
        transcript = aai.Transcriber(config=config).transcribe(args.audio_file)

        if transcript.status == "error":
            raise RuntimeError(f"Transcription failed: {transcript.error}")

        print("\n--- Transcript ---")
        print(transcript.text)
        print("------------------\n")


    except Exception as e:
        print(f"\nAn error occurred: {e}")
        sys.exit(1)

if __name__ == "__main__":
    main()

This script takes the path to an audio file, transcribes it using AssemblyAI, and prints the result.

Step 3: Configure OpenClaw

Next, integrate the script with OpenClaw by editing openclaw.json:

"tools":{
    "media": {
      "audio": {
        "enabled": true,
        "models": [
          {
            "type": "cli",
            "command": "python",
            "args": ["/PATH/TO/SCRIPT/main.py", "{{MediaPath}}"]
          }
        ]
      }
    }
  }

This configuration tells OpenClaw to enable audio understanding, but instead of using a default provider, it will run your custom script.

Tip: If you are using a Python virtual environment, set the command to the full path of your environment’s Python binary. You can find it with:

whereis python

Step 4: Restart OpenClaw

After setup, restart OpenClaw to apply the changes:

openclaw daemon restart

With this setup, you now have full control over OpenClaw’s audio understanding capabilities.

You can find the complete implementation in the GitHub repository.

Why Use Universal-3 Pro with OpenClaw?

A common question when working with OpenClaw’s media capabilities is: why switch to a different STT model? After all, don’t all STT models just convert speech to text?

The answer is no. Different STT models have different strengths and trade-offs, for example:

Speed: Some models prioritize fast transcription, making them suitable for real-time applications.
Accuracy (WER): Others focus on achieving a low Word Error Rate, improving transcription quality.
Domain specialization: Certain models are optimized for specific areas such as medicine, legal, or customer support.
Customization: Some models allow fine-tuning or prompting to handle unique names, jargon, or phrases.
Deployment preference: Developers may prefer local models for privacy, control, or cost reasons.

In this article, we use AssemblyAI’s Universal-3 Pro because of its powerful prompting capabilities. For example, my name is Eteimorde. It is not an English name and rarely appears in standard datasets.

While building my personal voice AI agent with OpenClaw, I noticed that default STT models consistently misheard my name. To solve this, I used Universal-3 Pro’s keyterm prompting feature to explicitly define my name as an important term:

config = aai.TranscriptionConfig(
    speech_models=["universal-3-pro"], 
    language_detection=True, 
    keyterms_prompt=["Eteimorde"]
)

Additional Capabilities of Universal-3 Pro via Prompting

Universal-3 Pro provides advanced features that can be easily leveraged through prompting. You can customize the behavior of the model by updating the prompt in the transcription configuration:

config = aai.TranscriptionConfig(
    speech_models=["universal-3-pro"], 
    language_detection=True, 
    prompt="YOUR_PROMPT_GOES_HERE"
)

Using prompting, the model can perform the following tasks:

Verbatim transcription and disfluencies
Preserve natural speech patterns such as filler words, repetitions, and self-corrections.
Audio event tagging
Mark non-speech sounds like laughter, music, applause, or background noise.
Crosstalk labeling
Identify overlapping speech, interruptions, and multiple speakers talking at once.
Numbers and measurements formatting
Control how numbers, percentages, and measurements are represented.
Context-aware clues
Improve transcription for domain-specific terms, names, and jargon by providing relevant hints in the prompt.
Speaker attribution
Detect and label different speakers in a conversation.
PII redaction
Tag personal identifiable information such as names, addresses, and contact details, useful for limiting what the agent can access.

By using prompting, these capabilities allow your OpenClaw voice agent to become more accurate, context-aware, and personalized, going beyond the default transcription behavior.

Conclusion

OpenClaw makes it easy to run AI agents through chat apps you already use, and adding voice capabilities takes the interaction to a whole new level. By integrating your own speech-to-text models, such as Universal-3 Pro, you unlock features beyond OpenClaw’s built-in media understanding.

Its prompting capabilities allow users to customize how the model transcribes audio, accurately recognize custom keyterms, and leverage features like verbatim transcription to preserve natural speech and audio event tagging to capture non-speech context such as background noise or laughter.

With this setup, your OpenClaw agent behaves more like a true personal assistant. It can remember context, send proactive reminders, and leverage system tools to perform tasks. Voice interaction, combined with Universal-3 Pro’s advanced prompting features, transforms the agent from a simple chat companion into a more robust, seamless, and highly personalized experience.