# How to connect OpenAI to Hermes Agent (paste one key, 126 tools)

> Connect OpenAI to Hermes with ClawLink: paste your OpenAI key once and 126 tools work from chat. No MCP server to run, nothing stored on your machine.

Web version: https://claw-link.dev/hermes/openai

Most guides for giving Hermes Agent OpenAI access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical OpenAI setup: pair once in the browser and your always-on Hermes agent can act on OpenAI for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.

**Start here — paste this into Hermes to set up ClawLink:**

> Set up ClawLink for Hermes and tell me when it's ready.
> 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable`
> 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 3. I'll approve it in my browser, then reply "approved".
> 4. When I say approved, finish setup: `hermes clawlink finish`
> 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.

## Setup

It takes three steps to connect Hermes to OpenAI.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect OpenAI** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect openai  # connect OpenAI (browser OAuth)
npx -y @useclawlink/cli actions openai  # list available actions
npx -y @useclawlink/cli run openai <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:

```bash
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin    # prints an approval link — open it and approve
hermes clawlink finish   # after approving in the browser
hermes clawlink test
```

Then connect OpenAI in the [ClawLink dashboard](https://claw-link.dev/dashboard) — paste your OpenAI API key once.

Verify the connection by asking Hermes:

> Call openai_create_chat_completion with model gpt-4o-mini and a system message telling it to answer in two sentences, then show me the response.

### Using a different agent?

The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once OpenAI is connected in the dashboard, that agent calls the same 126 OpenAI tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## OpenAI MCP for Hermes

Looking for a OpenAI MCP server for Hermes Agent? ClawLink connects OpenAI to Hermes Agent and exposes 126 OpenAI tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw OpenAI integration](https://claw-link.dev/openclaw/openai) works the same way.

Two different products answer to "Hermes", and only one is this page. Nous Research's Hermes Agent is a self-hosted agent you configure with a wizard, choosing "OpenAI Codex or API" as its provider and putting keys in `~/.hermes/.env`. ClawLink's Hermes Agent integration is not that: this connects the agent you already run to OpenAI so its tools can call the OpenAI API on your behalf. Here you paste an OpenAI platform key once into a hosted setup page, Hermes pairs with `hermes clawlink begin` and `hermes clawlink finish`, and 126 OpenAI tools become callable from chat. Nothing runs on your machine, no config file is edited, and the key is held server-side, so rotating it means changing one thing in the dashboard rather than editing a file on every machine.

## What the Hermes Agent OpenAI integration can do

126 OpenAI tools are ready for Hermes Agent once the account is connected. The 30 below are the ones people reach for most; your agent can call all 126.

### 30 of 126 OpenAI tools for Hermes

| Tool | What it does |
|---|---|
| **Add upload part** `openai_add_upload_part` | Tool to add a part (chunk of bytes) to an Upload object. Use when uploading large files in chunks, with each part up to 64 MB. |
| **Cancel batch** `openai_cancel_batch` | Tool to cancel an in-progress batch. Use when you need to stop a batch that is currently processing. |
| **Cancel eval run** `openai_cancel_eval_run` | Tool to cancel an ongoing evaluation run. Use when you need to stop an evaluation run that is currently in progress. |
| **Cancel response** `openai_cancel_response` | Tool to cancel a background model response by its ID. Use when you need to stop a response that was created with the 'background' parameter set to true. |
| **Cancel run** `openai_cancel_run` | Tool to cancel a run that is currently in progress. Use when you need to stop an assistant run that is taking too long or is no longer needed. |
| **Cancel upload** `openai_cancel_upload` | Tool to cancel an upload. Use when you need to stop an upload that is in progress. No parts may be added after cancellation. |
| **Compact response** `openai_compact_response` | Tool to compact a conversation or response to reduce token usage. Use when you need to reduce the size of long conversations while preserving important context. |
| **Create audio transcription** `openai_create_audio_transcription` | Tool to transcribe audio files to text via OpenAI Audio Transcriptions API. Use when you need to convert speech in audio files to written text, optionally with timestamps or speaker diarization. |
| **Create audio translation** `openai_create_audio_translation` | Tool to translate audio files to English text via OpenAI Audio Translations API. Use when you need to convert speech in audio files (any language) to English text. |
| **Create batch** `openai_create_batch` | Tool to create and execute a batch from an uploaded file of requests. Use after uploading a JSONL file with purpose 'batch' to process multiple API requests in a single batch operation. |
| **Create chat completion** `openai_create_chat_completion` | Tool to create a chat completion response from OpenAI models. Use for conversational AI, text generation, function calling, multimodal tasks with vision/audio, and structured JSON outputs. |
| **Create completion** `openai_create_completion` | Tool to generate text completions using OpenAI's legacy Completions API. Use for single-turn text generation with models like gpt-3.5-turbo-instruct. |
| **Create embeddings** `openai_create_embeddings` | Generate text embeddings via the OpenAI embeddings endpoint |
| **Create moderation** `openai_create_moderation` | Classify text and/or image inputs for potentially harmful content via the OpenAI Moderation API |
| **Create speech** `openai_create_speech` | Generate text-to-speech audio using OpenAI's Audio API |
| **Download file** `openai_download_file` | Download the contents of a specified file by its ID |
| **Download video** `openai_download_video` | Download video content (MP4) or preview assets from OpenAI Videos API |
| **Get chat completion** `openai_get_chat_completion` | Retrieve a stored chat completion |
| **Get chat completion messages** `openai_get_chat_completion_messages` | Retrieve messages from a stored chat completion |
| **Get chatkit thread** `openai_get_chatkit_thread` | Retrieve a ChatKit thread by its ID |
| **Get conversation item** `openai_get_conversation_item` | Retrieve a single item from a conversation |
| **Get eval** `openai_get_eval` | Retrieve an evaluation by ID |
| **Get eval run** `openai_get_eval_run` | Retrieve an evaluation run by ID to check status and results |
| **Get eval run output item** `openai_get_eval_run_output_item` | Retrieve a specific output item from an evaluation run by its ID |
| **Get eval run output items** `openai_get_eval_run_output_items` | Get a list of output items for an evaluation run |
| **Get eval runs** `openai_get_eval_runs` | Get a paginated list of runs for an evaluation |
| **Get input token counts** `openai_get_input_token_counts` | Calculate input token counts for OpenAI API requests |
| **Get message** `openai_get_message` | Retrieve a specific message from a thread by its ID |
| **Get response** `openai_get_response` | Retrieve a model response by ID |
| **Get run step** `openai_get_run_step` | Retrieve a specific run step from an Assistants API run to inspect detailed execution progress |

## Example prompts

**Get an answer from a specific model**

> Call openai_create_chat_completion with model gpt-4o-mini and a system message telling it to answer in two sentences, then show me the response.

**Embed a set of texts**

> Use openai_create_embeddings on the three customer feedback snippets I pasted, and return the dimension count and a quick cosine similarity between the first and second vectors.

**Transcribe an audio file**

> Take the audio file at \<url>, call openai_create_audio_transcription on it, and give me a plain-text summary of what was said.

**Batch a classification job**

> Create a batch with openai_create_batch for the 200 support tickets in \<file id>, asking the model to classify each as billing, technical, or other, then tell me when it is done.

## How the OpenAI tools behave

Details that decide whether an OpenAI prompt is a quick answer or a 429-shaped crawl.

- **Two model-call families exist side by side.** Chat Completions tools (`openai_create_chat_completion`, `openai_get_chat_completion`) and Responses tools (`openai_get_response`, `openai_compact_response`, `openai_cancel_response`) both make model calls but take different arguments. Pick one family per task and say which.
- **Every call spends your account's money.** Tokens, audio minutes, and batch compute bill against the key's project. A prompt that asks the agent to "try a few models" is a prompt to spend on several.
- **Batches are the volume escape hatch.** `openai_create_batch` runs async work that does not count against the interactive rate limit the same way, and `openai_cancel_batch` stops it. Large enumerations belong here, not in a fan-out of chat calls.
- **Ids come from prior calls.** File ids, upload ids, and run ids are returned by earlier tools; an id typed from the dashboard or documentation fails like a typo. Have the agent list before it addresses.
- **Evals exist as a first-class surface.** `openai_get_eval_run`, `openai_get_eval_run_output_items`, and friends let an agent audit a model's performance on your account rather than just calling it.
- **Audio is a real surface.** Transcription, translation, and speech generation each have their own tool, and `openai_download_file` retrieves results. A file first needs to exist as an OpenAI file, so the agent should confirm the upload step before the heavy call.

## ClawLink vs. building it yourself

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.

| | Manual | ClawLink |
|---|---|---|
| **Credential handling** | Collect, validate, store, and rotate the OpenAI API key yourself, then make sure every tool call uses the right account. | Users complete the hosted ClawLink setup once and the connected OpenAI account becomes available to the agent without you building credential management. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for OpenAI. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right OpenAI actions to the runtime in a format your agent can reliably use. | 126 tools for OpenAI are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes OpenAI to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect OpenAI in the browser, and the 126 tools above work from chat. There is no SDK and no config file, and the OpenAI key you paste at setup is stored server-side rather than kept in your environment. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### Hermes paired but still can't use OpenAI
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`.

### Connection succeeds but no tools appear
Reconnect OpenAI from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling OpenAI tools
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.

### OpenAI returns 403 or "permission denied" on one action while others work
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.

### OpenAI says "invalid API key" although the account shows as connected
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:

```text
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.
```

### OpenAI returns 403 "insufficient permissions" on some tools
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:

```text
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 starts returning 429 or rate-limit errors mid-task
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:

```text
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.
```

### OpenAI tools are missing, or one tool name is not found
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:

```text
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.
```

### API key setup works but results look incomplete
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.

### Is there a Hermes Agent OpenAI integration?
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.

### How do I connect OpenAI to Hermes with ClawLink?
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.

### How long does it take to connect OpenAI to Hermes Agent?
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.

### Why use ClawLink instead of wiring OpenAI up myself?
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.

### Which key does this need?
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.

### Can I use OpenAI through Hermes without any API key of my own?
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".

### What can the agent do with the OpenAI tools?
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.

### Why would an agent need OpenAI tools when Hermes already uses a model?
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.

### Is it safe to connect OpenAI to an agent through ClawLink?
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.

### Hermes paired but still can't use OpenAI
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`.

## Related

- [DataRobot](https://claw-link.dev/hermes/datarobot) — DataRobot is a machine learning platform that automates model building, deployment, and monitoring, enabling organizations to derive predictive insights from large datasets.
- [Hermes Chatbotkit integration](https://claw-link.dev/hermes/chatbotkit) — ChatBotKit is a platform that enables developers to build and manage AI-powered chatbots, offering comprehensive APIs and SDKs for seamless integration into applications.
- [Griptape tools](https://claw-link.dev/hermes/griptape) — Griptape is a comprehensive platform offering tools and frameworks for building, deploying, and scaling generative AI applications.