How to connect HeyGen to Hermes Agent

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.

Reconnect HeyGen from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

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.

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.

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:

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.

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:

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 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:

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.