How to connect Meta Ads 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 Meta Ads from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

Meta Ads 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 Meta Ads 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.

Error 100 is Meta's catch-all for an id the token cannot resolve, and it has two very different causes that look identical in chat. The first is a placeholder: an agent that has not listed anything yet will invent an id such as act_123456789 or YOUR_AD_ACCOUNT_ID, and because the shape is valid, the call reaches Meta and comes back as a missing object rather than a bad argument. List first, then act. metaads_get_ad_accounts returns the real act_-prefixed ids, metaads_list_ads and metaads_read_adsets go a level down. The second cause is asset access: the object exists, but the identity behind your token was never assigned to it, so from Meta's point of view it does not exist. That distinction is the whole game, and Meta's error text will not make it for you.

Ask the agent to diagnose it:

Run metaads_get_ad_accounts and list every account id and name you can see. Then run metaads_get_user and tell me which identity the token belongs to. Do not retry the failed call until both have returned.

The token is valid and the identity is real; the permission set on the token is short. Read calls such as metaads_get_insights need ads_read, and anything that creates or edits needs ads_management. A token minted quickly from the Graph API Explorer often carries only the default permissions, which is why the same connection can list ad accounts and then fail to create a campaign. Regenerate the token with both permissions, reconnect from the dashboard, and retry. Note this is a different failure from asset access: with the wrong permissions you get a permissions error, and with the wrong asset assignment you get an empty result or an error 100.

Ask the agent to diagnose it:

Run metaads_get_ad_accounts to confirm the connection works for reads. Then tell me the exact error body from the failed write call, including the code and subcode fields.

Meta access tokens expire, and short-lived ones expire fast. A token from the Graph API Explorer typically lasts around an hour unless it is exchanged for a long-lived one, and even a long-lived user token has a finite life. That is the practical argument for a Business Manager system user: its tokens do not expire on the same schedule and are not tied to your personal login session. When you see this error, nothing is wrong with the integration; the credential aged out. Generate a fresh token and reconnect Meta Ads from the dashboard.

Ask the agent to diagnose it:

Run metaads_get_user and report the exact error body if it fails, including the code and error_subcode fields. Do not retry the other Meta Ads calls.

Double-check that the API key for Meta Ads 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 Meta Ads: link your Meta Ads account once in the browser and Hermes Agent can call the Meta Ads API through 50 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 Meta Ads in the dashboard and Hermes can use it from the next message — no config files, and the Meta Ads key you paste is stored server-side instead of in your environment.

About two minutes. Sign in, click Connect next to Meta Ads 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 Meta Ads working from chat.

A Meta access token with ads_read and ads_management permissions, for an identity that has access to the ad account you want the agent to work on. Most people generate one from Meta's Graph API Explorer for a first test, then move to a longer-lived token or a Business Manager system user token for anything ongoing. The identity matters more than the token type: a token belonging to a user or system user with no access to the ad account will connect successfully and then return an empty list from metaads_get_ad_accounts, which reads like a broken integration and is actually a permissions gap.

You do not need to create an app. You may still want a system user, and the distinction is worth understanding. A personal user token is tied to you and to your session, so it expires and takes the agent's access with it. A Business Manager system user is a non-human identity that belongs to the business, is assigned to specific ad accounts, and issues tokens that do not die when you change your password. For an agent that runs unattended, that is the more stable choice. Either way you are pasting one string into the connect screen rather than wiring an app.

Decide it on mechanics rather than on vibes, and there are four that matter here. First, reach: the token you paste defines the ceiling, so a token scoped to one ad account cannot touch the others, and a read-only token cannot spend money no matter what the agent decides to do. Second, revocation: you invalidate the connection from Meta's side by removing the token or the system user's asset access, and from ClawLink's side by deleting the connection, and neither depends on the other. Third, enumerability: the agent's ability is the tool list on this page, not an open API session; the write tools are named individually, including metaads_create_campaign, metaads_create_ad_set, metaads_create_ad, and metaads_update_campaign. Fourth, sequencing: campaign creation in this toolset takes several deliberate calls rather than one, so there is no single prompt that quietly launches spend. The conservative setup is a token that can read insights but not manage, until you have watched what the agent proposes.

Because the identity behind the token has no ad accounts assigned to it. This is the most common first-run failure and it is not a ClawLink error. In Business Manager, assets are assigned to people and system users explicitly, and a brand-new system user starts with nothing. Assign it to the ad account, give it the right role, then retry. If the same token returns accounts in Meta's Graph API Explorer but not here, check that you copied the whole string.

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.