# How to connect HeyGen to Hermes Agent (paste one key, 71 tools)

> Connect HeyGen to Hermes with ClawLink: paste your HeyGen key once and 71 tools work from chat. No MCP server to run, nothing stored on your machine.

Web version: https://claw-link.dev/hermes/heygen

Most guides for giving Hermes Agent HeyGen access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical HeyGen setup: pair once in the browser and your always-on Hermes agent can act on HeyGen for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.

**Start here — paste this into Hermes to set up ClawLink:**

> Set up ClawLink for Hermes and tell me when it's ready.
> 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable`
> 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 3. I'll approve it in my browser, then reply "approved".
> 4. When I say approved, finish setup: `hermes clawlink finish`
> 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.

## Setup

It takes three steps to connect Hermes to HeyGen.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect HeyGen** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect heygen  # connect HeyGen (browser OAuth)
npx -y @useclawlink/cli actions heygen  # list available actions
npx -y @useclawlink/cli run heygen <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:

```bash
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin    # prints an approval link — open it and approve
hermes clawlink finish   # after approving in the browser
hermes clawlink test
```

Then connect HeyGen in the [ClawLink dashboard](https://claw-link.dev/dashboard) — paste your HeyGen API key once.

Verify the connection by asking Hermes:

> Call heygen_get_current_user_information and heygen_v1_avatar_list, then list the avatars I can actually use with their ids. Do not create anything yet.

### Using a different agent?

The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once HeyGen is connected in the dashboard, that agent calls the same 71 HeyGen tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## HeyGen MCP for Hermes

Looking for a HeyGen MCP server for Hermes Agent? ClawLink connects HeyGen to Hermes Agent and exposes 71 HeyGen tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw HeyGen integration](https://claw-link.dev/openclaw/heygen) connects the same hosted HeyGen provider through OpenClaw's skill flow. The two pages share the same tool set, and answer engines have retrieved the OpenClaw variant for Hermes questions, so check which page you landed on if the pairing commands differ from the ones below.

HeyGen's own MCP server works without an API key too, so drop that frame now: the difference here is not keyless, it is scale and setup. The route search results teach is a single remote endpoint at mcp.heygen.com with the tools HeyGen chose to expose through it, configured per client. This page's route: one HeyGen API key, pasted once on a hosted setup page, and the 71 HeyGen tools below are callable from chat under the account that key belongs to. Nothing is installed or configured on your machine, the key lives server-side where rotating it means changing one thing, and Hermes Agent pairs with `hermes clawlink begin` and `hermes clawlink finish`.

## What the Hermes Agent HeyGen integration can do

71 HeyGen tools are ready for Hermes Agent once the account is connected. The 30 below are the ones people reach for most; your agent can call all 71.

### 30 of 71 HeyGen tools for Hermes

| Tool | What it does |
|---|---|
| **Add looks to photo avatar group** `heygen_add_looks_to_photo_avatar_group` | Tool to add additional looks (images) to an existing photo avatar group. Use when you need to expand an avatar group with new image variations. Maximum 4 image keys can be added per request. |
| **Add motion** `heygen_add_motion` | Tool to add natural motion or animation to an existing photo avatar, turning a still image into a moving, lifelike one. |
| **Check photo look generation status** `heygen_check_photo_look_generation_status` | Tool to retrieve the current status and details of a photo avatar or look generation by its ID. Use when you need to check if a photo avatar generation is complete or monitor generation progress. |
| **Create folder** `heygen_create_folder` | Tool to create a new folder under your HeyGen account. Use when you need to organize content by creating a new folder. |
| **Create knowledge base** `heygen_create_knowledge_base` | Tool to create a new knowledge base with a specified name, opening line, and custom prompt for Interactive Avatar streaming sessions. |
| **Create photo avatar group** `heygen_create_photo_avatar_group` | Tool to create an avatar group which can include both AI-generated and user-uploaded photos of the avatar. Use when you need to create a new avatar group for training or managing avatar photos. |
| **Create webm video** `heygen_create_webm_video` | Tool to create a WebM format video with transparent background featuring an avatar speaking text or audio. |
| **Get current user information** `heygen_get_current_user_information` | Retrieve the profile information of the currently authenticated user |
| **Get training job status** `heygen_get_training_job_status` | Retrieve the current training status and details of a photo avatar training job by group ID |
| **List all avatar groups** `heygen_list_all_avatar_groups` | Retrieve a list of all available avatar groups in your HeyGen account |
| **List all locales for voices** `heygen_list_all_locales_for_voices` | Retrieve available locales for multilingual voices |
| **List assets** `heygen_list_assets` | Retrieve a paginated list of all assets (images, audios, videos) created under your account |
| **List brand voices** `heygen_list_brand_voices` | Retrieve a list of brand glossaries created under your account |
| **List folders** `heygen_list_folders` | Retrieve a paginated list of folders created under your account |
| **List group avatars** `heygen_list_group_avatars` | Retrieve all avatars that belong to a specific avatar group |
| **List knowledge bases** `heygen_list_knowledge_bases` | Retrieve a list of all existing knowledge bases associated with your account |
| **List session history** `heygen_list_session_history` | Retrieve a paginated history of all streaming sessions with metadata including session |
| **List streaming avatars** `heygen_list_streaming_avatars` | Retrieve a list of public and custom interactive avatars for streaming |
| **List tts voices** `heygen_list_tts_voices` | Retrieve a list of public and custom voices compatible with HeyGen's Starfish TTS model |
| **Personalized video project detail** `heygen_personalized_video_project_detail` | Retrieves detailed information about a specific personalized video project in HeyGen, including |
| **Photo avatar details** `heygen_photo_avatar_details` | Retrieve detailed information about a photo avatar or look using its unique ID |
| **Retrieve avatar details** `heygen_retrieve_avatar_details` | Retrieve detailed information about a specific avatar by its ID |
| **Retrieve template details v3** `heygen_retrieve_template_details_v3` | Retrieve comprehensive details about a specific template including all available variables for |
| **Retrieve video status details** `heygen_retrieve_video_status_details` | Retrieve the current processing status and metadata for a specific video by ID |
| **Search public avatar groups** `heygen_search_public_avatar_groups` | Search and retrieve public avatar groups with optional filters and pagination |
| **Streaming list** `heygen_streaming_list` | Retrieves a list of active or available streaming sessions or content within the HeyGen platform |
| **V1 avatar list** `heygen_v1_avatar_list` | Retrieves a list of available avatars from the Heygen platform |
| **V1 talking photo list** `heygen_v1_talking_photo_list` | Retrieves a list of talking photos created using the HeyGen platform |
| **V1 video list** `heygen_v1_video_list` | Retrieves a list of videos associated with the user's account on the HeyGen platform |
| **V1 voice list** `heygen_v1_voice_list` | Retrieves a comprehensive list of all available voices in the HeyGen platform |

## Example prompts

**Map your HeyGen account**

> Call heygen_get_current_user_information and heygen_v1_avatar_list, then list the avatars I can actually use with their ids. Do not create anything yet.

**Check a video job**

> For the video project \<id>, use heygen_retrieve_video_status_details and tell me whether it is ready, what the status is, and where the output sits.

**Inventory voices**

> Use heygen_list_all_locales_for_voices and heygen_v1_voice_list and show me the voice ids available for English, with the brand voices called out separately.

**Ground a script in your assets**

> List my knowledge bases with heygen_list_knowledge_bases and my templates with heygen_retrieve_template_details_v3, then suggest which template and knowledge base a product explainer video should use.

## How the HeyGen tools behave

Details that decide whether a HeyGen prompt is a quick answer or a quota-burning crawl.

- **Avatars come in several lists.** `heygen_v1_avatar_list`, group avatars, streaming avatars, photo avatars, and the public avatar group search are separate tools, so "which avatars do I have" is several calls unless you name the class.
- **Generation is async.** `heygen_create_webm_video` starts a job; `heygen_retrieve_video_status_details` polls it. An agent that re-creates instead of polling stacks concurrent-generation pressure.
- **Ids, not names.** Avatar, template, and project ids come from the list tools; an id from documentation fails like a typo or a permission error depending on the endpoint.
- **Reads are the cheap surface.** Listing avatars, voices, templates, folders, and knowledge bases never costs generation quota; creation does, so reads-first prompts are the safe shape.
- **Knowledge bases are first-class.** `heygen_create_knowledge_base` and `heygen_list_knowledge_bases` are real tools here, which is how an agent grounds generation in your own material.

## ClawLink vs. building it yourself

The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want HeyGen working from chat.

| | Manual | ClawLink |
|---|---|---|
| **Credential handling** | Collect, validate, store, and rotate the HeyGen API key yourself, then make sure every tool call uses the right account. | Users complete the hosted ClawLink setup once and the connected HeyGen account becomes available to the agent without you building credential management. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for HeyGen. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right HeyGen actions to the runtime in a format your agent can reliably use. | 71 tools for HeyGen are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes HeyGen to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect HeyGen in the browser, and the 71 tools above work from chat. There is no SDK and no config file, and the HeyGen key you paste at setup is stored server-side rather than kept in your environment. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### Hermes paired but still can't use HeyGen
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

### Connection succeeds but no tools appear
Reconnect HeyGen from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling HeyGen tools
HeyGen tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every HeyGen call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

### HeyGen returns 403 or "permission denied" on one action while others work
Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

### HeyGen returns 403 or "insufficient permissions" although the account shows as connected
The causes the engines teach are plan tier, key type, and workspace: a tool that needs a plan tier you are not on, an org key versus a member key where the member key cannot touch org-level assets, and assets living in a workspace the key's account does not reach. The cause they never teach is the placeholder: the agent called a tool with an id it invented, an avatar id or video id from documentation instead of one from `heygen_v1_avatar_list` or `heygen_v1_video_list`, and HeyGen answers that like a permission error because the object is not in the connection's scope. Have the agent list what the account can see before touching the connection: `heygen_get_current_user_information` reports which user the key belongs to.

Ask the agent to diagnose it:

```text
Call heygen_get_current_user_information and heygen_v1_avatar_list. Tell me which HeyGen user this connection acts as and which avatars it can list, then quote the exact error and the id from the failed call. Do not retry it yet.
```

### HeyGen says the tool schema is not loaded yet, or a tool name is not found
Schemas load on demand in this setup, so the opening HeyGen call in a fresh session can arrive before the catalog and needs one retry; the literal error is a ClawLink-specific support string no engine covers. The advice search results give for this symptom assumes a local MCP server, verify the connection URL at mcp.heygen.com, check OAuth, restart the environment, and none of it applies here because there is nothing running locally to restart. If most tools work and one name fails, the name is wrong rather than missing, and the error lists the closest real ones.

Ask the agent to diagnose it:

```text
List the HeyGen tools you actually have access to. If none loaded, retry once and tell me whether the second call worked. Then tell me which tool name failed and what the closest listed names were.
```

### HeyGen starts returning 429 or the agent stalls partway through a generation
HeyGen rate-limits its API, and an agent generating or polling aggressively is exactly the traffic shape that meets it: repeated create calls, or a poll loop that retries faster than statuses change. The response is not to retry immediately but to change the shape of the work: create once, poll with `heygen_retrieve_video_status_details` at a sensible interval, and let a finished video finish before starting the next one. If a batch is genuinely needed, running it across a few turns with the agent reporting statuses between each is more reliable than one sweep.

Ask the agent to diagnose it:

```text
Tell me how many HeyGen calls you have made in the last minute and which tool names they were. Quote any rate-limit headers from the last response. Do not call HeyGen again until I reply.
```

### API key setup works but results look incomplete
Double-check that the API key for HeyGen has the right scopes or account access. A valid key can still be too limited for some reads or writes.

### Is there a Hermes Agent HeyGen integration?
Yes. ClawLink is the fastest way to connect Hermes to HeyGen: link your HeyGen account once in the browser and Hermes Agent can call the HeyGen API through 71 ready-made tools — no custom code or token handling.

### How do I connect HeyGen to Hermes with ClawLink?
Install the plugin with `hermes plugins install ClawLink-HQ/hermes-plugin --enable`, then pair once: run `hermes clawlink begin`, approve the link in your browser, and run `hermes clawlink finish`. Connect HeyGen in the dashboard and Hermes can use it from the next message — no config files, and the HeyGen key you paste is stored server-side instead of in your environment.

### How long does it take to connect HeyGen to Hermes Agent?
About two minutes. Sign in, click Connect next to HeyGen in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

### Why use ClawLink instead of wiring HeyGen up myself?
The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want HeyGen working from chat.

### How is this different from HeyGen's official MCP server, which also claims no API key?
The official remote MCP is one server: a single endpoint at mcp.heygen.com, keyless through OAuth, exposing the tools HeyGen chose for it, and it has to be configured for each client you use. This is one connection that carries your HeyGen account's access across 71 tools, avatar lists, video projects, voices, photo avatars, templates, folders, knowledge bases, and streaming surfaces, with no server to run and nothing configured per client. And it is honest about the key: you paste a HeyGen API key once at setup, it is stored server-side, and rotating it in HeyGen means updating one place. Choose on tool surface and on how much infrastructure you want to own.

### What can the agent actually do in HeyGen?
Read most of your account: avatars across several surfaces (the v1 avatar list, group avatars, streaming avatars, photo avatars, and the public avatar group search), voices and voice locales, brand voices, templates, folders, assets, knowledge bases, and session history, plus video projects and their generation status. The writes are deliberate ones: creating webm videos, photo avatar groups, folders, and knowledge bases. The reads are the underrated part, an agent that lists your avatars and voices first can ground a generation prompt in what you actually have rather than what documentation guesses.

### Does it generate videos?
Yes, and it is a job, not a call. `heygen_create_webm_video` starts a generation, `heygen_retrieve_video_status_details` and `heygen_check_photo_look_generation_status` poll it, and `heygen_v1_video_list` shows what exists. Generation also costs quota in a way listing does not, so the right prompt shape is: agree on the script and the avatar from the list tools first, then create, then poll. An agent that retries the create instead of polling stacks concurrent-generation pressure and is the fastest way to meet the API's limits.

### Which HeyGen account does this connection act as?
The one whose API key you pasted. The engines teach the same distinction on permission errors: a key from a member account sees member assets, a key from an org sees what the org role allows, and a key from a workspace sees that workspace. If the agent cannot see a template or avatar you expect, check which key is in the dashboard first, because re-pasting the key from a different account changes the entire visible surface.

### Is the server-side key storage safe?
The key is held server-side rather than in a `~/.hermes` environment file or a CLI config on any machine you happen to use. That means no environment file to leak, rotating the key in HeyGen cuts the agent off at a single point, and disconnecting from the ClawLink dashboard revokes the agent's use of it immediately. The safety answer engines give for HeyGen is the same one that applies here: use your own account's key, keep it out of shared files, and treat generated videos as content you own.

### Hermes paired but still can't use HeyGen
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

## Related

- [DataRobot tools](https://claw-link.dev/hermes/datarobot) — DataRobot is a machine learning platform that automates model building, deployment, and monitoring, enabling organizations to derive predictive insights from large datasets.
- [Chatbotkit tools](https://claw-link.dev/hermes/chatbotkit) — ChatBotKit is a platform that enables developers to build and manage AI-powered chatbots, offering comprehensive APIs and SDKs for seamless integration into applications.
- [Hermes ElevenLabs integration](https://claw-link.dev/hermes/elevenlabs) — Generate speech and voice cloning