Grok Bot
Connect Grok Bot to Roam HQ chat. People message it in Roam, and it replies there.
Set it up in the Grok Bot app. After that, you talk to it in Roam.
What you need
- The Grok Bot app
- A Roam HQ workspace
Personal or organization
Choose one before you connect.
| Personal | Organization | |
|---|---|---|
| Appears in Roam as | Your personal bot (name and icon on the token) | A named bot you configure (display name and avatar) |
| Who can message it | Only you | Anyone in the workspace who can reach it |
| What it can see | The direct message with that bot — not your DMs with other people, and not groups | Direct messages to the bot, plus groups you add it to |
| Credential | Personal Access Token (rmp-…) | API key (rmk-…) |
| Use when | A private assistant in Roam | A shared teammate others can @-mention |
Every bot on a Grok Bot account shares one computer (files, browser, logins). If an organization key must stay isolated, use a dedicated Grok / Cursor account for that bot.
Connect
In Grok Bot, send:
Install this Roam plugin https://github.com/WonderInventions/grokbot-roam then connect Roam
Confirm the plugin. Grok Bot will ask for:
- A Roam credential — create one below, then paste it when Grok Bot prompts you. Do not paste it into the chat.
- A routine URL and sender key — Grok Bot creates a routine (an automation Roam triggers on each new message). If it cannot read those values, copy them from the routine's details panel. Treat the sender key as a secret.
Grok Bot also adds Roam as an MCP server with that same credential (not a second login). That is how it searches meetings and adds emoji reactions.
When that finishes, test in Roam, not only in the Grok Bot app.
Personal
- In Roam: User Settings → Developer → Create Personal Access Token
- Name it (for example
grok-bot) - Grant Chat Send, Chat Read, and Meetings Read (Chat Send includes images, files, and reactions)
- Copy the token (
rmp-…). Admins can require approval (the default) or disable personal tokens. If approval is required, an admin approves it under Administration → Developer → Personal Access Tokens. See Access Models.
Give that token to Grok Bot when it asks.
Then in Roam, open a direct message with the personal bot and send:
ping — reply with pong
You should see the reply in that Roam DM.
A personal bot cannot be added to groups. If you later want it to answer @-mentions in groups you are in, ask Grok Bot after it is connected — that is off by default.
Organization
You need workspace-admin access in Roam.
- Roam Administration → Developer → Add ApiClient
- Choose API Key
- Set the display name and avatar — that is what people see in Roam
- Scopes, at minimum:
chat:send_message,chat:read,chat:history,group:read,webhook:write,item:write(images and files),meetings:read - Copy the key (
rmk-…)
Give that key to Grok Bot when it asks.
Then add the bot to each group it should read: Group Settings → add the bot. @-mentioning it does not join the group. It can post to some public groups without joining; it cannot read history there until it is a member.
In Roam, @-mention it in a group it belongs to, or send it a direct message:
What is this channel for?
If something goes wrong
| What you see | What to try |
|---|---|
| Nothing happens in Roam | In Grok Bot, reconnect Roam and paste both the routine URL and the sender key from the routine panel. |
| Connect rejects the URL | Use the URL from Grok Bot’s routine panel (it contains /automations/webhook/). |
| Org bot silent in a channel | Add it under that group’s Group Settings. |
| Personal bot answering other people | You likely used an API key. Recreate with a Personal Access Token. |
| It replies to every message in a busy group | Ask Grok Bot to listen only when @-mentioned. |
| It replies to itself in a loop | Ask Grok Bot to reconnect Roam so it reloads who it is. |
| It can see your DMs with other people | Reconnect. Personal setup should only attach the DM with the bot. |
| Images or files do not send or open | Personal: Chat Send. Org: the key needs item:write. Then reconnect. |
| Meeting or transcript questions fail | Personal: Meetings Read. Org: meetings:read. Reconnect and let Grok Bot add Roam MCP with the same token. |
| Cannot add an emoji reaction | Personal: Chat Send. Org: chat:send_message. Ask Grok Bot to use the roam MCP server — not a chat message. |
Optional: call Roam tools from Grok
Connecting Roam chat already adds the roam MCP server on this Grok Bot. You can also add it where you talk to Grok outside Roam — on grok.com or in Grok Build.
| Where you talk to Grok | How to add Roam |
|---|---|
| Grok Bot | Add a custom MCP server called roam at https://api.ro.am/mcp (say custom server) |
| grok.com | Connectors → New Connector → Custom |
| Grok Build | grok mcp add --transport http roam https://api.ro.am/mcp |
Personal access uses the OAuth prompt (or a PAT in the Authorization header). Organization access uses an API key in that header. See MCP (AI Assistants).
Grok as the model on Hermes or OpenClaw
To run Grok as the model inside Hermes or OpenClaw instead of Grok Bot, follow those guides after pointing the agent at xAI.
See also
- Access Models — personal vs organization tokens
- MCP (AI Assistants) — tools Grok can call on Roam