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

OpenAI 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 OpenAI 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.

Separate two credentials before changing anything. The key Hermes uses to reach its model provider lives in Hermes's own config and has nothing to do with this error; search results for "Hermes API key" mostly answer about that one. The credential in play here is the OpenAI platform key you pasted at setup, held server-side. If that key was regenerated, deleted, or disabled in the OpenAI dashboard after you pasted it, every OpenAI tool fails from that moment, and re-pasting the current key from the ClawLink dashboard is the fix. If the key is untouched but calls still fail, check it is a project key scoped to a project your account can actually use, since a key belongs to one project and returns exactly this error outside it. When a reconnect is needed, start a fresh chat afterwards: the agent's tool catalog reloads on session start.

Ask the agent to diagnose it:

Call openai_get_chat_completion with a minimal one-token request and quote the exact error string. Then tell me which OpenAI project your key was created under. Do not retry the failing tool yet.

The usual cause with hosted keys is a restricted key: OpenAI lets you create keys limited to certain endpoints, and a read-only or endpoint-scoped key 403s on the tools outside its scope no matter what the account behind it can do. The second cause is project access: a key created in project A cannot act in project B, and the 403 names the resource, not the fix. The third cause is the placeholder trap that shows up in hosted toolkits: the agent called a tool with an id it invented (a file id, an upload id, a run id) instead of one it was given by an earlier call. Have it list what it can see and reuse ids from those responses exactly.

Ask the agent to diagnose it:

Tell me which OpenAI tool returned 403 and quote the error. Then list the ids that call would have needed, and which earlier tool call should have produced each one. Do not call OpenAI again until I reply.

OpenAI rate limits by usage tier and by project, and an agent fanning out a batch of model calls is exactly the traffic shape that meets the limit: many parallel calls, each counting against the same allowance. The response is not to hammer retries but to change the shape of the work: have the agent run the calls sequentially, or move the work to openai_create_batch, which is the async route designed for large volumes. The 429 response tells the agent how long to wait, so ask it to report the backoff rather than guessing. A project with its own rate tier, separate from your main account traffic, is the structural fix if this recurs.

Ask the agent to diagnose it:

Tell me how many OpenAI calls you made in the last minute and which tool returned 429. Quote the backoff value from the error. Do not call OpenAI again until I reply.

Two different failures. If Hermes shows no OpenAI tools at all, the connection or the pairing is incomplete: confirm the plugin was installed with --enable, that both hermes clawlink begin and hermes clawlink finish ran, and that OpenAI shows as connected in the dashboard. If most tools work and a single name fails, that name is wrong rather than missing, and the error lists the closest real ones. There is also a first-call timing case unique to this setup: schemas load on demand, so the opening OpenAI call in a fresh session can arrive before the catalog and needs one retry. What does not apply is the usual advice for this symptom, which assumes a local MCP server declared in a client config file.

Ask the agent to diagnose it:

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

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

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

An OpenAI platform API key, generated at platform.openai.com under API keys, pasted once on the hosted setup page. It is distinct from the key Hermes itself uses to talk to its model provider: that one lives in Hermes's own config and is not involved here. The key you paste here carries your OpenAI account's access, so the agent can call models, embeddings, batches, and audio tools as you. It is stored server-side, never written to a .env on your machine, and disconnecting from the ClawLink dashboard ends the agent's use of it immediately.

Not through this integration. This page is the hosted-management route: one key, pasted once, kept server-side, so you stop dealing with environment files and rotation across machines. If your goal is to avoid OpenAI billing entirely, that is a different problem, covered by hosted-OAuth routes for providers that offer them; the /learn/oauth-for-ai-agents page explains the difference. Do not assume "no key management" means "no key".

The full platform surface: chat completions and the newer Responses API, completions, embeddings, audio transcription, translation and speech, moderation, batches for async work, file and upload handling, and eval runs. The writes to be deliberate about are the ones that spend money, since model calls are billed per token on your account, and batches are real work that runs on your account's quota. Asking the agent to state its intended calls before it makes them is the cheap guard against surprise spend.

Because "OpenAI as a tool" is not "OpenAI as the brain". Hermes can run on any model provider while your agent still needs one-off OpenAI calls: an embedding for a search index, a moderation pass, a batch classification, a transcription of an audio file, or a specific model that is not what Hermes is currently running on. This connection gives the agent a defined, visible way to make those calls, with the argument names in the tool schemas, rather than having it improvise HTTP calls from documentation.

The parts worth comparing are where the secret lives and who can revoke it. Here the key lives server-side rather than in a local environment file or a CLI config, so a compromised machine does not leak it, and disconnecting in the dashboard revokes the agent's access at once. The remaining risk is the normal one for any API key: the account behind it can spend. A restricted project-scoped key, or a key on a project with its own billing limits, is the standard way to bound that, and nothing about this setup requires an unrestricted key.

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.