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

Cloudflare 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 Cloudflare 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 search results teach for this error are the manual route's: a wrong Authorization header format, confusing a Global Key with an API token, propagation delay after creating a token, or a token with wrong permissions. On a hosted connection the request formatting is handled, so the remaining causes are two. First, the stored key was regenerated or deleted in Cloudflare after setup, in which case every Cloudflare call fails from that moment and re-pasting the current key from the dashboard is the fix. Second, the key's permissions changed in Cloudflare, which shows up as permission errors rather than token errors. What is not the cause is anything in ~/.hermes or the plugin's pairing: the plugin token and the Cloudflare key are different credentials, and search answers that conflate them will send you down the wrong path.

Ask the agent to diagnose it:

Call cloudflare_list_accounts to check which Cloudflare account the connection acts as, then quote the exact error from the failed call. If it is an invalid-token error I will re-paste the key; do not retry before then.

Two usual causes, and both are about the key and the request rather than the connection. First, Cloudflare API keys carry per-key permissions, so a key created with only zone-read access fails on writes like cloudflare_create_dns_record, and the error names the missing permission: a com.cloudflare.api.* permission error means the key itself is too limited, and the fix is a key with the right permissions in Cloudflare, not a reconnect. Second, the agent may have sent a placeholder or guessed id (like "YOUR_ID" or a zone name from documentation) instead of a real one: ask it to run cloudflare_list_zones first and retry with the real zone id. The backend even adds a hint pointing to the Cloudflare dashboard on these permission errors, so read the full error before touching anything.

Ask the agent to diagnose it:

Run cloudflare_list_accounts and cloudflare_list_zones and show me the real ids. Quote the exact 403 text, including any hint about the dashboard, then retry with a real id from that list.

Cloudflare rate-limits its API per account, and an agent walking every zone, then every record, firewall rule, pool, and tunnel, one call at a time, is exactly the traffic shape that meets the limit. The response is not to retry immediately, which lands in the same window, but to change the shape of the work: one zone at a time, and have the agent tell you what it intends to enumerate before it starts. If a full audit is genuinely needed, running it in stages across turns is more reliable than one sweep.

Ask the agent to diagnose it:

Tell me how many Cloudflare calls you have made in the last minute and what you were enumerating. Quote any rate-limit text from the last response. Do not call Cloudflare again until I reply.

Two different failures. If Hermes shows no Cloudflare tools at all, the connection or pairing is incomplete: confirm the plugin was installed with --enable, that both hermes clawlink begin and hermes clawlink finish ran, that Cloudflare shows as connected in the dashboard, and start a fresh chat. If most tools work and a single name fails, that name is wrong rather than missing: the error lists the closest real tools, and the real catalog is one clawlink_list_tools --integration cloudflare away. There is also a first-call timing case unique to this setup: schemas load on demand, so the opening Cloudflare call in a fresh session can arrive before the catalog and needs one retry. What does not apply is the advice for this symptom that blames a client's MCP server registering only a couple of tools, which is Cloudflare's own Code Mode server, not this connection.

Ask the agent to diagnose it:

List the Cloudflare tools you actually have access to. If there are none, run clawlink_list_integrations and confirm the plugin pair, then tell me what you see. If there are, tell me which one lists zones and use that exact name.

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

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

You paste one Cloudflare API key at setup, generated in your Cloudflare account settings, and it is stored server-side. The distinction the search results teach, Global Key versus API token, and the 401 causes that follow from it (wrong header format, propagation delay after creating a token), matter only on the manual route where you are building requests by hand. On a hosted connection you see none of that plumbing: the key is entered once, the agent calls the tools, and regenerating the key in Cloudflare means updating a single place in the dashboard. Cloudflare keys carry per-key permissions, so a key with limited access is a 403 you will see in chat, not a setup error.

The 20 tools cover the account and zone surface: zones and their DNS records, accounts and members, lists for WAF rules, firewall rules, load-balancer monitors and pools, tunnels, and bot management settings. The writes to be deliberate about are creating or updating DNS records and zones, because those change live DNS for real domains, and updating tunnel configuration, which changes routing. Reads, starting with cloudflare_list_accounts and cloudflare_list_zones, are the safe first steps.

The AI Overview answers this query "yes, generally safe" and its cited mitigations are AI Gateway, least privilege, and scoped tokens. The hosted connection implements the scoped-token half by construction: the key you paste is stored server-side, the agent never sees it, and revoking the connection from the dashboard ends its use immediately. The behavioral half is yours: DNS and zone changes are live internet changes, so require a confirmation step before writes, and treat any fetched content as untrusted input, since a zone's records are just data until an agent is told to act on them.

The underlying Cloudflare API is the same, so the capability difference is small; the setup and upkeep difference is not. The Composio route involves their Connect CLI, an MCP server block hand-edited into ~/.hermes/config.yaml with a consumer key, and infrastructure you then own. Here the plugin install and one pairing handshake are the entire client-side story, the key is entered once in the dashboard, and Cloudflare sits alongside your other connected accounts with one place to revoke. Choose on how much you want to run, not on features.

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.