---
title: "Connect an AI agent to Sblurp"
description: "How to connect a self-hosted AI agent, such as OpenClaw, NanoClaw or Hermes Agent, to a Sblurp community with a bot token. No built-in connector exists yet."
nav: "AI agents"
doc_version: 1
last_updated: 2026-10-17
---

# AI agents

An AI agent is a program that uses a language model to answer messages and to do tasks with tools. OpenClaw, NanoClaw and Hermes Agent are three open source agents that you run on your own computer or server. Each one talks to people through chat apps such as Telegram, Discord and Slack.

Sblurp has no built-in connector for these agents yet. We will build connectors for them eventually. Until then, you can connect an agent yourself with a [bot token](/docs/bot-tokens) and a short program.

To let Claude Code or another MCP client read and post as you, rather than as a bot, see [MCP](/docs/mcp).

## How these agents connect to chat apps

Each agent has a part that connects it to chat apps. Each chat app needs its own connector in that part.

| Agent | What it is | How it connects to chat apps |
|---|---|---|
| [OpenClaw](https://docs.openclaw.ai/) | A self-hosted gateway that connects chat apps to an AI agent. | One Gateway process loads [channel plugins](https://docs.openclaw.ai/channels), for example Telegram, Discord, Slack and Matrix. You can write your own channel plugin with its plugin SDK. |
| [NanoClaw](https://github.com/nanocoai/nanoclaw) | A small personal agent that runs each session in a container. Claude is its default model provider. | You add a [channel adapter](https://docs.nanoclaw.dev/channels/overview) with a skill such as `/add-telegram`. Each adapter implements its `ChannelAdapter` interface. |
| [Hermes Agent](https://hermes-agent.nousresearch.com/docs/) | An agent from Nous Research with memory and skills. | A [messaging gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) runs one platform adapter for each chat app. You can add an adapter as a [plugin](https://hermes-agent.nousresearch.com/docs/developer-guide/adding-platform-adapters). |

None of these agents has a Sblurp connector today. A Sblurp connector is a channel plugin or adapter for each agent. That is the part we will build.

## Connect an agent today

You run the agent and a small program, called the glue. The glue reads messages from Sblurp, sends them to the agent, and posts the replies back as a bot.

1. Make a bot in **Community settings**, then **Bots**. Copy its token. See [Bot tokens](/docs/bot-tokens).
2. Give the bot a role that lets it into the channels where it must answer. See [Limits](#limits).
3. Turn on an HTTP endpoint in the agent. OpenClaw and Hermes Agent can serve an OpenAI-compatible `/v1/chat/completions` endpoint. See the [OpenClaw guide](https://docs.openclaw.ai/gateway/openai-http-api) and the [Hermes guide](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server). NanoClaw has no such endpoint in its docs. For NanoClaw, write a channel adapter instead.
4. Run the glue on the same machine as the agent. Keep the agent endpoint on `localhost`.

The glue uses three Sblurp calls:

- `ServerService.GetState` gives the bot its own id (`me.id`) and its channels.
- `ChatService.ListMessages` with `afterId` returns the messages after the last one the glue saw.
- `ChatService.SendMessage` posts the reply. Pass `threadRootId` to reply in a thread.

For a bot that must answer at once, use the event stream (`ServerService.Subscribe`) instead of polling. See [Listen for messages](/docs/bot-tokens#listen-for-messages) and [Events](/docs/api/events).

## Example glue

This Python program uses only the standard library. It polls one channel every 3 seconds. When a message mentions the bot, it sends the text to the agent and posts the answer in a thread.

```python
import json, os, time, urllib.request

SBLURP = "https://chat.example.com"
TOKEN = os.environ["SBLURP_BOT_TOKEN"]
AGENT = "http://127.0.0.1:8642/v1/chat/completions"  # Hermes default port
AGENT_KEY = os.environ["AGENT_KEY"]
CHANNEL = "CHANNEL_ID"

def post(url, body, key):
    req = urllib.request.Request(url, json.dumps(body).encode(), {
        "Authorization": "Bearer " + key, "Content-Type": "application/json"})
    return json.load(urllib.request.urlopen(req, timeout=300))

def call(name, body):
    return post(f"{SBLURP}/sblurp.v1.{name}", body, TOKEN)

me = call("ServerService/GetState", {})["me"]["id"]
msgs = call("ChatService/ListMessages", {"channelId": CHANNEL, "limit": 1})["messages"]
last = msgs[-1]["id"] if msgs else ""
while True:
    time.sleep(3)
    body = {"channelId": CHANNEL, "afterId": last} if last else {"channelId": CHANNEL}
    for m in call("ChatService/ListMessages", body)["messages"]:
        last = m["id"]
        if m.get("authorId") == me or f"<@{me}>" not in m.get("text", ""):
            continue
        out = post(AGENT, {"model": "hermes-agent",
                           "messages": [{"role": "user", "content": m["text"]}]}, AGENT_KEY)
        call("ChatService/SendMessage", {"channelId": CHANNEL,
              "threadRootId": m.get("threadRootId") or m["id"],
              "text": out["choices"][0]["message"]["content"][:8000]})
```

For OpenClaw, set `AGENT` and `model` as the OpenClaw guide tells you. Each call sends one message with no history. If the agent must remember the talk, keep the history in the glue or use the session features of the agent.

## Limits

- The bot sees only the channels that its roles allow. It cannot read or post in other channels. Give it a role to let it into a limited channel.
- Keep the token secret. Put it in an environment variable or a file, not in the code. If the token leaks, click **New token** on the **Bots** tab. The old token stops working at once.
- The server can limit how fast bots post, with `-bot-rate` (messages per second) and `-bot-burst`. A bot that sends too fast gets `resource_exhausted`. See [Configuration](/docs/configuration).
- A message can have 8,000 characters at most. The example cuts longer replies.
- Bot messages do not trigger plugin hooks, so a plugin and the agent cannot loop. The glue skips its own messages for the same reason.

Do not let everyone in a channel control an agent that has tools such as a terminal or file access. Each person who can mention the bot can make the agent use those tools. The OpenClaw guide says that its HTTP endpoint has full operator access. Put the bot only in channels with people you trust, and turn off tools that the agent does not need.

## Sitemap

- [Sblurp: chat for communities](https://sblurp.chat/index.md): Sblurp is group chat with channels, threads and roles. Each community runs on its own server, and one Sblurp account signs you in to all of them.
- [About Sblurp](https://sblurp.chat/about.md): Why Sblurp exists: chat for communities that each run their own server, with no ads, no unasked-for AI and an honest word on encryption.
- [Privacy at Sblurp](https://sblurp.chat/privacy.md): What sblurp.chat stores about you, what it never stores, what it shares with communities you join, and how to get a copy or delete it.
- [Terms of use](https://sblurp.chat/terms.md): The terms for a sblurp.chat account: who can sign up, what you must not do, and what we do and do not promise. A first draft.
- [Create your Sblurp account](https://sblurp.chat/signup.md): Create a Sblurp account: one account for every Sblurp community you join. You need an email, a username, a password and to be 13 or older.
- [Sign in to Sblurp](https://sblurp.chat/login.md): Sign in to your Sblurp account with your email or username and password, or with a passkey. One account works in every Sblurp community.
- [Reset your password](https://sblurp.chat/forgot.md): Forgot your Sblurp password? Type the email you signed up with and we send a link to choose a new one. The link works once, for one hour.
- [Sblurp docs](https://sblurp.chat/docs.md): Sblurp documentation: how accounts and communities work, how to run a community server, how to add bots, and the full API reference.
- [Accounts and communities](https://sblurp.chat/docs/accounts.md): How a Sblurp account relates to the communities you join: what sblurp.chat keeps, what each community server sees, and what stays private.
- [Join a community](https://sblurp.chat/docs/join.md): Join a Sblurp community: add it by address or invite link, answer its questions, choose what to share, and join.
- [Sblurp glossary](https://sblurp.chat/docs/glossary.md): The words the Sblurp docs use, from account and community to issuer, track, bot token and seq, each with a link to the page that explains it.
- [Run a Sblurp community](https://sblurp.chat/docs/self-host.md): Run a Sblurp community on your own server: one small program and one data folder. What you need, how to start it, and what it stores.
- [Run a server](https://sblurp.chat/docs/create.md): For developers: start your own Sblurp community. Run the open-source server, join it first to become the owner, then set it up and invite people.
- [Set up a server with AI](https://sblurp.chat/docs/ai.md): Not a developer? Ask an AI assistant such as Claude to set up your Sblurp community server.
- [Sblurp server sizes and costs](https://sblurp.chat/docs/hosting.md): Which server size to rent for a Sblurp community and what it costs each month: measured limits per size and prices at Fly.io, DigitalOcean, Hetzner, OVHcloud and AWS Lightsail.
- [Run Sblurp on Render](https://sblurp.chat/docs/render.md): Run a Sblurp community server on Render: one Starter web service with a persistent disk, the released image, and optional backups to Cloudflare R2.
- [Run Sblurp on Railway](https://sblurp.chat/docs/railway.md): Run a Sblurp community server on Railway: one service from the released image, a volume for /data, and optional backups to Cloudflare R2.
- [Run Sblurp on Fly.io](https://sblurp.chat/docs/fly.md): Run a Sblurp community server on Fly.io: one always-on machine with a volume, h2c streaming, and optional backups to Cloudflare R2.
- [Run Sblurp on any VPS](https://sblurp.chat/docs/vps.md): Run a Sblurp community server on a small virtual server from Hetzner, OVHcloud, Akamai Linode, Vultr, DigitalOcean or any other host, with Docker Compose.
- [Run Sblurp with Docker and Compose](https://sblurp.chat/docs/docker.md): Run a Sblurp community server with Docker Compose and Caddy: the files, the settings, where the data lives, and how to run it behind your own proxy.
- [Run Sblurp with Podman](https://sblurp.chat/docs/podman.md): Run a Sblurp community server with a Podman Quadlet file, with daily automatic updates that roll back when a new image does not start.
- [Sblurp server configuration](https://sblurp.chat/docs/configuration.md): Every flag and environment variable of the Sblurp community server, with defaults, plus the backup variables of the container image and the built-in limits.
- [TLS and reverse proxies for Sblurp](https://sblurp.chat/docs/proxies.md): Put Caddy, nginx or Cloudflare in front of a Sblurp community server without breaking live streams: h2c, no buffering, no compression.
- [Back up a Sblurp server](https://sblurp.chat/docs/backups.md): Back up a Sblurp community server: Litestream copies the database to Cloudflare R2 within 10 seconds, an encrypted backup tool copies the files, or make a plain copy. How to restore.
- [Update a Sblurp server](https://sblurp.chat/docs/updates.md): Release tracks for the Sblurp server image, the daily update check, manual and automatic updates, and how to roll back.
- [Verify a Sblurp release](https://sblurp.chat/docs/provenance.md): Check that a Sblurp server image was built by the public release workflow, with GitHub attestations or cosign.
- [Troubleshooting a Sblurp server](https://sblurp.chat/docs/troubleshooting.md): Fix common problems with a Sblurp community server: sign-in fails, messages arrive late, certificates, file links, and where the logs are.
- [Invites in Sblurp](https://sblurp.chat/docs/invites.md): Make a Sblurp community invite only, create invite links with an expiry and a use limit, and revoke them.
- [Moderation and roles in Sblurp](https://sblurp.chat/docs/moderation.md): Permissions in a Sblurp community (owner, admin, moderator, member), custom roles that limit channels, channel modes, kicks and bans.
- [Safety in Sblurp](https://sblurp.chat/docs/safety.md): Who can read your messages, how to protect your account, what to do about unwanted messages, how to report a message, what moderators can do, age rules, and how to reach sblurp.chat.
- [Your data in Sblurp](https://sblurp.chat/docs/data.md): What sblurp.chat stores about your account, what a community server stores, who controls each, how long data is kept, backups, export and deletion.
- [Sblurp bots](https://sblurp.chat/docs/bots.md): Two ways to add a bot to a Sblurp community: a JavaScript plugin on the server, or a program anywhere that uses the API with a bot token.
- [Sblurp bot tokens](https://sblurp.chat/docs/bot-tokens.md): Make a Sblurp bot with a token, run the example bot, and call the API from any language: subscribe to events and reply to mentions.
- [Connect an AI agent to Sblurp](https://sblurp.chat/docs/agents.md): How to connect a self-hosted AI agent, such as OpenClaw, NanoClaw or Hermes Agent, to a Sblurp community with a bot token. No built-in connector exists yet.
- [Use Sblurp from Claude Code and other MCP clients](https://sblurp.chat/docs/mcp.md): Add a Sblurp community to Claude Code, Claude Desktop, VS Code or another MCP client by URL, sign in with your sblurp.chat account, and let the agent read and post as you.
- [Sblurp plugins](https://sblurp.chat/docs/plugins.md): Write a Sblurp bot as one JavaScript file and install it in the app, with the API or in the plugins folder: hooks for joins, messages, slash commands and timers, replies, limits and the dice example.
- [Sblurp API: protocol and transport](https://sblurp.chat/docs/api.md): How clients and bots talk to a Sblurp community server: Connect RPC over HTTP, the proto contract, JSON and binary bodies, auth, streaming and versioning.
- [Sblurp API explorer](https://sblurp.chat/docs/api/explorer.md): Browse and try every call of the Sblurp community server API in your browser, from the OpenAPI 3.1 description in openapi.json.
- [Sblurp API: sign-in and tokens](https://sblurp.chat/docs/api/auth.md): How sign-in works across Sblurp: OAuth 2.0 with PKCE at sblurp.chat, per-server access tokens, JWT claims, refresh token rotation, JWKS, and bot tokens.
- [Sblurp API: events](https://sblurp.chat/docs/api/events.md): The Sblurp live event stream: Subscribe, sequence numbers, replay and resync, heartbeats, every event kind, who receives it, and unread counts.
- [Sblurp API: uploads and files](https://sblurp.chat/docs/api/files.md): The plain HTTP endpoints of a Sblurp community server: uploads, signed file URLs, custom emoji, invite links and the health check.
- [Sblurp API: errors and rate limits](https://sblurp.chat/docs/api/errors.md): Error codes the Sblurp community server returns, what each one means for a client, and the rate limits for people and bots.
- [ServerService API reference](https://sblurp.chat/docs/api/server-service.md): Every ServerService call of the Sblurp community server: what it does, who may call it, and its request and response fields.
- [ChatService API reference](https://sblurp.chat/docs/api/chat-service.md): Every ChatService call of the Sblurp community server: what it does, who may call it, and its request and response fields.
- [BotService API reference](https://sblurp.chat/docs/api/bot-service.md): Every BotService call of the Sblurp community server: what it does, who may call it, and its request and response fields.
- [API types](https://sblurp.chat/docs/api/types.md): The messages and enums the Sblurp community server API shares between calls, with every field.