Connect Instagram to Hermes Agent or OpenClaw with Composio

A content request should begin with account context

Suppose you ask, “Prepare an Instagram post from today's product photo.” Before it writes or publishes anything, the agent needs to know which Instagram identity is connected, whether it is the intended Business or Creator account, and which media already exists. Composio's current Instagram toolkit explicitly excludes Personal accounts and exposes separate actions for reading media, creating media, publishing it, and handling messages. That separation is useful: it gives you a natural review point.

1. Connect the intended professional account

For a managed Hermes Agent or OpenClaw instance, the path is identical. Open Dashboard → Integrations, find Instagram, select Connect, and complete the provider's authorization screen. Read the account and Page choices carefully. Instagram connections go through Facebook Login, and Composio notes that the resulting token stays bound to the account chosen there. To switch identities later, reconnect and select the intended account again in the picker. See the Composio Instagram notes.

Grant only the access needed for the workflow. Do not paste passwords, access tokens, or recovery codes into agent chat. After authorization, the integration card should show that the connection is active.

2. Start with a read-only request

Use my connected Instagram account. Identify the account, list its five most recent media items, and summarize their captions and publish times. Do not post, comment, message, or delete anything.

The agent should check composio connections, then search the current Instagram action schema instead of guessing fields. Useful documented identifiers include INSTAGRAM_GET_USER_INFO, INSTAGRAM_GET_IG_USER_MEDIA, and INSTAGRAM_GET_IG_MEDIA_INSIGHTS. Action definitions are versioned, so names establish intent while composio search instagram supplies the live parameters.

3. Put approval between preparation and publication

1. Ask the agent to draft the caption, accessibility text, and a short description of the selected image or video.
2. Require it to show the target Instagram username and whether the post is a single item or carousel.
3. Review links, claims, tags, location references, and the crop outside the agent.
4. Approve the exact draft. Only then allow the agent to create and publish the media.
5. Have it read the published media back and return the provider's media identifier or URL.

The current publishing pair is INSTAGRAM_POST_IG_USER_MEDIA followed by INSTAGRAM_POST_IG_USER_MEDIA_PUBLISH. Avoid the similarly named deprecated create and post actions. For a carousel, INSTAGRAM_CREATE_CAROUSEL_CONTAINER is also available. Local media must be staged and passed using the file field reported by the current schema; a raw local path is not a portable upload. A public media URL must be directly fetchable by Meta.

Messaging and comment limits are provider rules

INSTAGRAM_LIST_ALL_MESSAGES, INSTAGRAM_SEND_TEXT_MESSAGE, and INSTAGRAM_POST_IG_COMMENT_REPLIES support inbox and community workflows. They should still be review driven. Meta's messaging window can reject a reply even when authentication is healthy; Composio documents that qualifying inbound interactions open the window, while likes, comments, and follows alone do not. Never have the agent claim that a message was sent until it reads the provider result and, where possible, reopens the conversation.

Self-hosted setup for Hermes Agent and OpenClaw

For an installation you run yourself, create a server in your own Composio project, select this app and the tools you need, and connect the intended account. Copy the complete generated MCP URL for that user. The examples below use Composio Platform MCP and a Composio project API key in x-api-key. An app password or provider API key belongs in the app connection flow, not in this header.

Set COMPOSIO_API_KEY in the environment of the agent process and replace the URL placeholder below. Merge the entry into your existing configuration. Keep your project key out of chat and source control. A connection on OpenClaw Launch does not automatically transfer to your own Composio project; Composio connections are scoped to their project and user.

Hermes Agent

Add the server under mcp_servers in ~/.hermes/config.yaml. You can set the environment variable in ~/.hermes/.env.

mcp_servers:
  composio:
    url: "YOUR_GENERATED_PLATFORM_MCP_URL"
    headers:
      x-api-key: "${COMPOSIO_API_KEY}"
    connect_timeout: 60
    timeout: 180

Run hermes mcp test composio to check discovery, then start a new session or use /reload-mcp in the Hermes CLI. See the Hermes MCP configuration reference for reload behavior and tool filters.

OpenClaw

Use a release with the native openclaw mcp commands. Its server definitions belong under mcp.servers in ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "composio": {
        "url": "YOUR_GENERATED_PLATFORM_MCP_URL",
        "transport": "streamable-http",
        "headers": {
          "x-api-key": "${COMPOSIO_API_KEY}"
        }
      }
    }
  }
}

Ensure the Gateway service receives the environment variable, restarting that service after changing its environment. Run openclaw mcp doctor composio --probe and begin a new agent session. If your version lacks these commands, update before using this config. The native registry is separate from mcporter. See OpenClaw's MCP reference and HTTP transport fields.

Discovery confirms the MCP connection. Finish with this guide's first read request to check access to the actual app. The hosted composio shell commands earlier in this guide are supplied by OpenClaw Launch; a standalone MCP setup exposes tools through the agent's MCP client instead.

Does the Instagram Composio integration work with Hermes Agent?

Yes. Managed Hermes Agent and OpenClaw instances use the same Integrations page and Composio commands. The connection belongs to your OpenClaw Launch account, so confirm the intended Instagram identity before using it.

Can I connect a personal Instagram account?

The current Composio Instagram toolkit supports Business and Creator accounts, not Personal accounts. The account selected during Facebook Login is bound to that connection; reconnect to choose a different one.

Can the agent publish an Instagram post immediately?

It can use publishing actions when the account and permissions allow them, but a safer workflow is to draft the caption, confirm the media and target account, request approval, create the media container, publish it, and read the media back.

Why can an Instagram DM reply fail?

Meta limits normal API replies to an active messaging window opened by a qualifying user interaction. A comment, like, or follow does not necessarily open that window, so inspect the conversation before promising a reply.