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

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

This is the most common error on this integration in production, and it is architecture, not a bug: Microsoft's Graph Search API serves enterprise mailboxes only, so outlook_search_messages rejects personal accounts with this exact message. Reconnecting will not change it, because the mailbox type does not change. On a personal account, use outlook_list_messages for a folder or outlook_query_emails for server-side filters; both run on personal mailboxes. On a work or school account, search works as documented, with KQL syntax such as from:user@example.com and received: ranges.

Ask the agent to diagnose it:

Run outlook_get_profile and tell me whether the account is a personal or work or school mailbox. Then recommend the correct tool for what I asked and do not retry search if the account is personal.

This is Microsoft Graph throttling, returned as a 429, and the literal message is all it gives you. The response may also carry a Retry-After interval. It happens when the agent fires a burst of calls in one prompt, and the fix is to wait and then spread the work, not to reconnect. Batch operations help here: a move or update across several messages is one call when it fits under the 20-item batch limit, where separate per-message calls are many. If throttling repeats on every attempt, the shape of the prompt is the problem, and a narrower request with filters will succeed where a broad sweep does not.

Ask the agent to diagnose it:

Report the exact status and any Retry-After value from the failed call. If the task involved many per-message calls, tell me which batch tools could replace them.

Two production error codes cover this family. {"error":{"code":"TargetIdShouldNotBeMeOrWhitespace","message":"Id is malformed."}} appears when a move or copy target is empty or whitespace, which happens when the agent invents a destination folder instead of listing one. {"error":{"code":"ErrorItemNotFound","message":"The specified object was not found in the store."}} appears when the message id is a placeholder, or the message was moved or deleted after the id was captured. Both are solved by listing first: outlook_list_mail_folders returns real folder ids for moves, and outlook_list_messages returns real message ids for reads. Microsoft's ErrorInvalidIdMalformed variant of "Id is malformed." is the same shape from a different endpoint.

Ask the agent to diagnose it:

List the mail folders or messages available to the connection, then retry the failing call with the real id from that response. Show me the id you are about to use before calling.

Graph batch operations on this integration cap at 20 items, and the validation error names the count that broke it. The agent is asking to update or move more messages in one call than the API accepts. The fix is to split the batch into chunks of 20 or fewer, which means the tool runs twice, or to narrow the selection so a smaller batch does the job. This is an argument-shape error, not a connection fault.

Ask the agent to diagnose it:

Split the batch into groups of 20 or fewer and run them in sequence. Report how many messages each batch covered.

The production string is {"error":{"code":"ErrorAccessDenied","message":"Access is denied. Check credentials and try again."}}, and AADSTS65001 is the code the engines teach for the same family. Three causes. Account mismatch: the tool is pointed at a mailbox the connected identity does not own; run outlook_get_profile and compare. Tenant policy: a work or school tenant that restricts third-party app consent blocks the grant, and the consent screen or a 65001 error reports that an administrator must approve it, which is an action for your tenant admin, not a reconnect. Stale grant: consent was revoked or the connection expired, and reconnecting from the dashboard with the owning account restores it. One thing the guides say that does not apply here: switching the app from delegated to application permissions. That advice is for applications you register and run yourself; this connection is delegated by design, running as you, which is the whole point of the hosted flow.

Ask the agent to diagnose it:

Run outlook_get_profile and tell me the mailbox the connection holds. If it is not the mailbox I meant, reconnect and re-run. Otherwise report the exact error code from the failing call.

Try reconnecting Outlook and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

Yes. ClawLink is the fastest way to connect Hermes to Outlook: link your Outlook account once in the browser and Hermes Agent can call the Outlook API through 270 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 Outlook in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

About two minutes. Sign in, click Connect next to Outlook in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

The alternative to ClawLink is usually manual OAuth app 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 Outlook working from chat.

An app password plugs a mailbox into Hermes Agent's email gateway, a chat channel where the agent replies to incoming mail, so it belongs on a dedicated inbox. ClawLink connects Outlook as tools through OAuth: the agent searches, reads, and drafts in your own account only when you ask. Use ClawLink if you want the agent working on your mail; use the gateway if you want to message your agent by email.

Not for this connection. The walkthrough the engines teach is real work: create an application in Microsoft Entra ID, configure redirect URIs, request Graph scopes like Mail.Send, and consent to them as an admin. ClawLink connects through an app that is already registered and requests a fixed scope set on the consent screen, which for a personal account you approve on the spot. The one case where approval is not instant is a work or school mailbox whose tenant requires administrator approval for third-party apps: the consent screen then reports that an admin must grant access, and the connection cannot complete until someone with that role approves it. That is Microsoft's tenant policy, not a setup step you can do around.

No, and the error is explicit about it: "Search does not work with @hotmail.com or @outlook.com personal accounts. Please use a work or school (Microsoft 365/Enterprise) account." Microsoft's Search API only serves enterprise mailboxes, so outlook_search_messages is a work-or-school tool. Personal accounts still get everything else: outlook_list_messages, outlook_query_emails, read, draft, reply, and send all work on personal mailboxes. If you are on a personal account and want search-like behavior, outlook_query_emails with server-side filters is the closest tool, and it searches one folder at a time.

The risk list for this question names prompt injection and over-permissioning, and both deserve a direct answer. Prompt injection: an agent that reads mail can be steered by the content of that mail, so links and instructions inside emails should be treated as untrusted input, which is worth writing into the prompt. Over-permissioning: this connection requests Mail.Read, Mail.ReadWrite, Mail.Send, Calendars, Contacts, and MailboxSettings, all listed on the consent screen, and the destructive tools that delete and move messages carry a confirmation step before they run. The grant is revocable from Microsoft's account settings without involving us, and nothing about the connection stores your password. Those are the mechanics; whether a mail-reading agent is right for your inbox is a judgment call the page cannot make for you.

The usual cause is account mismatch: the connection shows as healthy while the tool is pointed at a mailbox the connected identity does not own. A work or school connection cannot read a personal mailbox or a colleague's shared folder unless the shared grant exists, and the error comes back as an access-denied code rather than a clear account message. The second cause is tenant policy: some organizations restrict third-party app consent, which surfaces as an admin-approval requirement. The third is a stale grant: if consent was revoked or the connection expired, reads keep working from cache while writes fail. The fix in each case is to reconnect from the dashboard with the account that owns the mailbox and complete the consent screen, and to have the agent run outlook_get_profile first to confirm which identity the connection holds.

The 270 tools cover three surfaces. Mail: search, query, read, draft, reply, forward, send, move, copy, and delete, with delete and move gated by a confirmation step. Calendar: create and update events, find meeting times, free and busy schedules, and calendar permissions. Contacts: create, read, and update contacts and contact folders. The write tools are individually named in the tool list, and the ones that remove or relocate messages ask before they run.

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.