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

PostHog 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 PostHog 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 AI Overviews give four causes for this, in order of likelihood: a personal API key missing the scope the endpoint needs (write scopes like customer_analytics:write are not implied by an analytics-read key), an endpoint that rejects personal-key auth entirely and wants a different credential model, a host-region mismatch (calling us.posthog.com surfaces against an eu.posthog.com project, or mixing the us and eu hosts), and a user-role restriction in your PostHog org. The hosted-toolkit causes still apply on top: the connection acts as a specific account and project, so a key created by one user in one org cannot see another user's projects, and the placeholder trap, where the agent used a project or insight id it invented instead of one from posthog_list_organization_projects. The diagnostic move is to have the agent quote the error, name the tool, and list the projects the connection can actually see before reconnecting, because a reconnect will not fix a region or role boundary.

Ask the agent to diagnose it:

Call posthog_list_organization_projects and tell me which project ids this connection can see. Quote the exact 403 from the failing tool and which host region your PostHog project uses. Do not retry it yet.

The engines' answer to this symptom is PostHog's own MCP setup: npx @posthog/wizard@latest mcp add, verify the client config, restart. That advice presumes a PostHog MCP server, which this flow does not run, so the distinction matters: there is no local MCP server here to configure or restart. The real causes are the hosted two: the connection or pairing is incomplete (confirm the plugin installed with --enable, both pairing commands ran, and PostHog shows as connected), or schemas load on demand, so the first PostHog call in a fresh session can arrive before the catalog and needs one retry. If most tools work and one name fails, that name is wrong rather than missing.

Ask the agent to diagnose it:

List the PostHog tools you actually have access to. If there are none, say so plainly. If there are, tell me which one creates a query in a project and use that exact name.

This is the wrong-account or wrong-project shape, and it is the dimension the engines' p3 answers add: a key scoped to project A returns empty results for project B, and a connection made while logged into one PostHog account stays that account even if you later switch. The symptom is usually clean: queries succeed but return zero events, or lists show a different project set than you expect. The fix is to confirm which account and project the key belongs to, then reconnect with the right one from the dashboard and start a fresh chat. Role changes after a connection (a teammate's role was downgraded, a re-invite went stale) produce the same symptom and the same fix.

Ask the agent to diagnose it:

List the projects visible to this connection with posthog_list_organization_projects and the projects you expected. Tell me which differ, and which PostHog account created the key. Do not reconnect yet.

The Query API surfaces PostHog's own errors, and they are usually honest: a bad property name, a wrong date range, or HogQL that references an event the project has never captured. The engines teach the Query API as the agent-facing surface precisely because the error messages are actionable, so the response is to let the agent iterate: have it quote the error, check the property against posthog_get_event_definitions and posthog_get_group_property_definitions, and retry with corrected names rather than reconnecting or guessing. A query that returns empty rows is different from an error, and an empty result usually means the date range or event name is simply not present in the data.

Ask the agent to diagnose it:

Quote the exact HogQL error, then call posthog_get_event_definitions and tell me which property names actually exist. Do not retry the query until you have done both.

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

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

Yours, the one you already use for PostHog's API. The AI Overviews and ChatGPT all answer the without-a-key question with "you cannot", which is true only if the searcher expects to avoid PostHog credentials entirely. This page is the other reading: you keep using your PostHog personal API key, but ClawLink hosts it, so the agent never touches a .env, never configures a client, and you never paste the key into a second place. Creating the key still happens in PostHog, because the key is proof of your account. What disappears is every step after that.

The platform surface: event definitions and property definitions, funnels and retention insights, trends per project, feature flags and experiments, dashboards, session recordings, surveys, and the Query API, which the engines name as the agent-facing surface for HogQL (posthog_create_query_in_project_by_id). It is a read-and-analyze surface first: the agent can answer "what did users do last week" from your actual events instead of from a dashboard someone already built. The deliberate writes are the governance ones: creating insights and feature flag changes land in your project for the whole team.

Because the 502 tools are the API with its argument shapes already resolved: project ids, insight types, date ranges, and filter structures are typed in the schemas, and the tool names match the surfaces the docs describe, so the agent is far less likely to improvise a malformed call. The Query API tool in particular is what the engines teach searchers to reach for, and here it is one named tool instead of a hand-built request against /api/projects/\{project_id\}/query.

The engines' safety answers lean on scoped keys, redaction, prompt-injection awareness, and privacy modes, and all four are available to you here. The key is held server-side and never written to a local file, and revoking in the dashboard ends the agent's access immediately. Scoped keys matter more than usual with PostHog because the same key can reach different projects: use a key limited to the project the agent should analyze. The prompt-injection caution is real for any analytics agent that reads event content, since event payloads are untrusted input the agent should never execute. If your data includes identifiable people, keep the agent's summaries to aggregates and let the privacy modes in your PostHog project do the redaction work.

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.