Garry's Opinionated OpenClaw/Hermes Agent Brain
Connect GBrain to OpenClaw
This page is the MCP-registration reference card. For the full brain install — CLI, engine, skills, dream cycle — follow INSTALL_FOR_AGENTS.md; the README covers the bootstrap and connect paths.
Connect with Option 2 (stdio) when the brain runs on the gateway's machine, or with OpenClaw's own MCP client when it runs elsewhere. Option 1's ClawHub bundle is not available yet. A bot that several people DM connects over HTTP as well: see One bot for several people, in DMs.
Option 1: ClawHub bundle plugin (not available yet)
This project publishes no ClawHub package yet. The package named gbrain on
ClawHub is an unofficial upload of an old 0.10.1 build whose manifest has no
id, so openclaw plugins install clawhub:gbrain stops with
plugin manifest requires id. Don't install it; use Option 2.
GBrain ships openclaw.plugin.json at the repo
root. Installing the bundle plugin registers the MCP server for you — the
manifest carries an mcpServers.gbrain entry that runs the bundled
.agents/gbrain-launcher serve (the same launcher the Codex and Claude Code
plugins use; it resolves your installed gbrain via GBRAIN_BIN, then
~/.bun/bin/gbrain, then PATH, so it works under launchd's bare PATH and
never needs a build step) plus the bundled skills — and declares the
gbrain-context-engine context engine. To route OpenClaw's context-engine slot
through gbrain, two steps, in this order:
Install and enable the plugin by its own id,
gbrain-context-engine(theidinopenclaw.plugin.json).Set the slot to the engine id the plugin registers:
plugins.slots.contextEngine = gbrain-context-engine
The current host requires the canonical plugin ID in the slot. The installed
plugin ID is unchanged and gbrain-context remains a registry alias for older
integrations, but it is not a slot alias on current hosts: migrate an old
plugins.slots.contextEngine = gbrain-context setting to
gbrain-context-engine. Setting the slot alone does not install/enable the
plugin. For a legacy host that cannot provide a per-session workspace, set
plugins.entries.gbrain-context-engine.config.workspaceDir to an absolute
workspace path; on multi-agent hosts prefer the host-supplied workspace. An
unbound or ambiguous workspace warns and reads no source rather than selecting
an arbitrary agent's memory.
The factory also accepts zero arguments from current hosts. Its assemble
keeps the current prompt separate from fenced stored transcript history; an
identical trailing legacy user message is already the current turn. The
admitted-turn acknowledgement is stateless and writes nothing. Reflex-only
pointer synthesis leaves returned messages unchanged; the turn acknowledgement
does not automatically capture conversation content (compaction has its own
explicit checkpoint path). Loading the plugin alone is not evidence of model
recall: verify saved-page retrieval after a restarted turn and source isolation
with the intended host. The loopback native test uses a deterministic provider,
so it does not certify paid-model recall or provenance.
Option 2: openclaw mcp add
OpenClaw keeps MCP servers under mcp.servers in ~/.openclaw/openclaw.json
(openclaw config schema shows the key path). Register gbrain with the CLI:
openclaw mcp add gbrain --command "$(command -v gbrain)" --arg serve --arg --surface --arg starter --arg --advertise --arg verbs --env GBRAIN_HOME=$HOME
Use an absolute --command path: the launchd-started gateway's PATH does
not include ~/.bun/bin, so a bare gbrain fails to spawn. --env is
optional: a PGLite brain needs no DATABASE_URL
(--env DATABASE_URL=postgresql://... for Postgres), and GBRAIN_HOME only
matters when the brain home isn't ~/.gbrain. --surface starter --advertise verbs
lists the seven-verb memory protocol (MEMORY_VERBS v1)
plus request_tools, which reaches every other tool; drop the
--advertise verbs values to list the starter set (full for the whole catalog) (check
openclaw mcp add --help for your version's --arg spelling).
Leave GBRAIN_SOURCE unset in the MCP env unless you deliberately want
single-source retrieval: a pin scopes every tool (search, get_brain_identity
counts, …) to that one source, and nothing warns on reads.
Remote brain: OpenClaw's MCP client over HTTPS
When the brain runs on another machine, OpenClaw connects to its MCP endpoint itself, over streamable HTTP with OAuth. That grant is scoped and revocable on the brain host, while the stdio route above gives the gateway full local database access.
openclaw gateway stop
openclaw mcp add gbrain --url https://<brain-host>/mcp --transport streamable-http --auth oauth
openclaw mcp login gbrain
openclaw mcp doctor gbrain --probe
openclaw gateway start
mcp add, login and doctor --probe refuse while the local gateway runs, so
stop it first and start it again after. openclaw mcp login runs the browser sign-in (on a headless host it prints a
--code command to finish with). OpenClaw registers its client through dynamic
client registration, so the brain owner turns that on and approves the consent
(native OAuth path,
self-service registration). Until
the login succeeds, OpenClaw leaves the server out of agent turns. Publish the
endpoint with gbrain mcp expose (remote MCP).
Or: a thin client's stdio bridge
When OpenClaw should keep a stdio entry, install gbrain on the OpenClaw
machine as a thin client of the brain host and register its gbrain serve,
which relays every call to the host with that client's grant (it opens no
local database). On the brain host, gbrain agent register with
--harness openclaw prints these lines with your client filled in; run them
on the OpenClaw machine:
gbrain init --mcp-only --issuer-url https://<brain-host> --mcp-url https://<brain-host>/mcp \
--oauth-client-id <client_id> --oauth-client-secret <client_secret>
openclaw mcp add gbrain --command "$(command -v gbrain)" --arg serve --arg --surface --arg starter --arg --advertise --arg verbs
If gbrain's bundle plugin is installed there, it already registers gbrain:
run only the init line. To keep this client apart from another gbrain on
that machine, put GBRAIN_HOME=<dir> before the init line and add
--env GBRAIN_HOME=<dir> to the mcp add line. What the bridge relays and
how it reports failures: stdio bridge.
One bot for several people, in DMs
When one OpenClaw bot answers several people, each in their own DM, each DM can
read only the pages that person may read. The bot speaks to the brain as a
shared agent:
every call carries an X-Gbrain-On-Behalf-Of header naming the person, and the
brain answers with that person's view, within the bot's own source grant. On
OpenClaw a small plugin sets the header from the DM's sender through the
requester-scoped MCP connection resolver
(api.registerMcpServerConnectionResolver). OpenClaw supplies the sender, not
the model, and the header rides on the transport; an audience put in tool
arguments is refused (on_behalf_of_in_arguments).
Say to your agent: "Set up my OpenClaw bot so each DM reads only what that
person may read", then "Show what alice-example's DMs can read" (it runs
gbrain access check --token openclaw-dm-bot --as alice-example on the brain host).
DMs only. The resolver learns who sent the turn (requesterSenderId, with
messageChannel and agentAccountId), not whether the turn came from a group
or who else is in it. On a group turn the sender's view would be shown to the
whole group. Use this recipe only on a gateway where every conversation has one
person in it: set groupPolicy: "disabled"
on each channel and turn dm.groupEnabled off on Discord and Slack. Group
audiences are tracked in #8534.
Before you share a personal brain through the bot
Each DM reads as one member, so anything that relaxes privacy for a single member relaxes it for every person the bot serves:
- No private-pages grant on the bot. Never give its token
--private-pages granted-sources. With it, every mapped person reads everyvisibility: privatepage in the bot's sources, which on a personal brain are your own private pages. - No private-facts grant on the bot. Leave its token at
--private-facts none. A DM call that names a person never uses that grant (an asserted audience reads world-only facts), so it adds nothing for the people the bot serves, and any call that reaches the brain without the header would read every fact saved private in the bot's sources. - Host hatches off.
GBRAIN_REMOTE_PRIVATE_PAGESandsearch.remote_private_pagesapply to every remote caller on the host, this bot included. Leave both unset while the bot runs. - A dedicated token bound to no member. Make a new token for the bot. Don't reuse your own agent's token or bind the bot's token to your member: your DMs through the bot then read like anyone else's, and your own agent keeps your full view.
- Pages only you should read name you as their reader. Today
access: privateandvisibility: privatehide a page from this bot. Clearing those labels, by hand or in bulk withgbrain repair private-labels, makes the pages readable in every DM and byguest. Before you clear them, give the pages you want to keep to yourselfreadable_by: [<your member>]or a folder rule (gbrain access rule add --prefix <folder>/ --readers <your member>).
gbrain access check --token openclaw-dm-bot --as <member> must show
Private pages: none for the bot.
Keep the gateway's people apart too
The header separates the brain's answers. The rest of the gateway has to keep people apart as well (OpenClaw's trust model treats one gateway as one trust boundary, so people who must not trust each other need separate gateways):
session.dmScope: "per-channel-peer"(per-account-channel-peerwith several accounts on one channel). The default,main, puts every DM in one session, so one person's brain results land in the next person's context.tools.sessions.visibility: "self", so session tools can't read another person's DM transcript.- No shell or file tools for this agent on the gateway host: commands there
inherit the gateway's environment, which holds the bot's token, and a local
gbrainor database URL reads every page. - Leave the
gbrain-context-engineslot unset for this bot. It reads through the host's own brain connection, not the bot's token.
On the brain host
Run gbrain serve --http (deploy guide). Add each person as a
member, make a read-only token for the bot, and list whom it may act for: each
person's member id, plus guest for senders who have none. Never *.
gbrain access member add alice-example
gbrain access member add bob-example
gbrain auth create openclaw-dm-bot --scopes read # prints the token once
gbrain auth rescope --token openclaw-dm-bot --sources <source-id> --may-act-for alice-example,bob-example,guest
gbrain access check --token openclaw-dm-bot --as alice-example
Keep the token read-only. An audience limits which existing pages a write
can reach, not where a new page lands. A write-capable token keeps its own
write grant whatever the header says, so a page made in one DM outside a ruled
folder (a new top-level page, a capture into inbox/) is read by everyone
the source admits, guest included, unless the write names readable_by,
which is the model's choice and not a fence. If the bot has to write for people
who must not affect each other's data, register one client per person with
--bound-slug-prefixes <their folder>/
(Model B);
the resolver can return each sender's own credential.
On the OpenClaw host
Put the token in the gateway's environment as GBRAIN_DM_BOT_TOKEN, never in
openclaw.json. Declare the server by URL alone. This replaces Option 2's stdio
entry, and an mcp.servers entry also takes the place of the bundle plugin's
server of the same name:
openclaw mcp set gbrain '{"url":"https://brain.example.com/mcp","transport":"streamable-http"}'
Then write the plugin, a directory gbrain-dm-audience with three files.
package.json:
{ "name": "gbrain-dm-audience", "version": "1.0.0", "private": true, "type": "module", "openclaw": { "extensions": ["./index.js"] } }
openclaw.plugin.json:
{
"id": "gbrain-dm-audience",
"name": "GBrain DM audience",
"description": "Names each DM's sender to gbrain as X-Gbrain-On-Behalf-Of",
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"url": { "type": "string" },
"members": { "type": "object", "additionalProperties": { "type": "string" } }
}
}
}
index.js:
export default {
id: 'gbrain-dm-audience',
name: 'GBrain DM audience',
description: "Names each DM's sender to gbrain as X-Gbrain-On-Behalf-Of",
register(api) {
const { url, members = {} } = api.pluginConfig ?? {};
api.registerMcpServerConnectionResolver({
serverName: 'gbrain',
resolve(ctx) {
const token = process.env.GBRAIN_DM_BOT_TOKEN;
if (!url || !token || !ctx.requesterSenderId) return null;
const sender = `${ctx.messageChannel ?? ''}:${ctx.requesterSenderId}`;
const audience = Object.hasOwn(members, sender) ? members[sender] : 'guest';
return { url, headers: { Authorization: `Bearer ${token}`, 'X-Gbrain-On-Behalf-Of': audience } };
},
});
},
};
Install and enable it, map each sender to a member, and restart the gateway.
A sender key is <messageChannel>:<requesterSenderId> as OpenClaw passes them.
Map only ids the channel authenticates, such as numeric user ids, never display
names or nicknames.
openclaw plugins install --link ./gbrain-dm-audience --force --accept-capabilities
openclaw plugins enable gbrain-dm-audience
openclaw config set plugins.entries.gbrain-dm-audience.config '{"url":"https://brain.example.com/mcp","members":{"telegram:<sender id>":"alice-example"}}' --strict-json
What each DM gets
- A mapped sender reads as their member: the pages every member may read, plus
pages whose
readable_byor folder rule lists them, within the bot's sources. - An unmapped sender reads as
guest: no restricted page and no private page. To give unmapped senders no brain at all, returnnullfromresolvewhenmembershas no entry for the sender. - A mapped member outside
--may-act-foris refused (on_behalf_of_not_permitted), and one that names no enabled member is refused (on_behalf_of_unknown_member); nothing is read either way (shared-agent refusals). - Runs without a trusted sender (cron, heartbeat, subagents) get no gbrain server from the resolver. Scheduled jobs that use the wrapper below read as the brain owner, so never send their output to someone's DM.
To stop the bot reading for someone, take them out of --may-act-for. gbrain
reads that list on every call; OpenClaw may keep a resolved connection for a
few minutes. To check from a DM, ask the bot to call whoami: its
access.applied names the audience the call read as, and relaxation must
read none.
Brain-first instructions
Registering the server only makes the tools available. Agents seldom call a brain nobody told them about, so finish either option with the primary route, the per-turn rule:
gbrain setup openclaw # --dry-run previews; --workspace <dir> picks the agent
It writes one short marked block into the workspace AGENTS.md (from
OPENCLAW_CONFIG_PATH or ~/.openclaw/openclaw.json: a sole agent's
workspace, else agents.defaults.workspace, else ~/.openclaw/workspace; with
several agents, pass --workspace). Text outside the markers is never touched,
a re-run upgrades the block in place, --no-instructions opts out and is
remembered, and --remove takes it out. A thin-client install puts the same
block at the top of GBRAIN-INSTRUCTIONS.md.
A rule in AGENTS.md reaches the system prompt only, so setup also puts it next
to every user turn with a hook-only OpenClaw plugin, gbrain-turn-rule: its
before_prompt_build handler returns the rule as prependContext (without its
closing "answer" sentence on heartbeat, cron and exec-completion turns). The plugin is
self-contained (the rule text is in its code; it reads and calls nothing) and
lives in <OpenClaw state dir>/gbrain/gbrain-turn-rule. Setup installs it with
OpenClaw's own CLI:
openclaw plugins install --link <state dir>/gbrain/gbrain-turn-rule --force --accept-capabilities
openclaw plugins enable gbrain-turn-rule
openclaw config set plugins.entries.gbrain-turn-rule.hooks.allowConversationAccess true
OpenClaw requires allowConversationAccess before a non-bundled plugin's
before_prompt_build runs. With no openclaw on PATH, setup writes the plugin
and prints those commands to run on the OpenClaw host; restart a running gateway
afterwards. --no-instructions and --remove uninstall the plugin and delete
its directory. A re-run after an upgrade rewrites the plugin with the new text.
Every agent on the gateway gets the plugin's rule, so a --workspace run leaves
it when it would name another server and --no-instructions there keeps it.
OpenClaw lists no gbrain tool after openclaw mcp set: the model reaches them
only through tool_search, whose results it frames as external data. With an
MCP connection the rule therefore names the tools (recall, entity, search,
query) and says to find them with tool_search and run them with tool_call.
With openclaw on PATH, setup runs
openclaw plugins inspect gbrain-turn-rule --runtime --json and exits non-zero
with turn_hook_not_loaded unless the plugin shows as loaded with
before_prompt_build (repair).
Skills (fallback)
gbrain skillpack scaffold --harness openclaw adds gbrain's skills to the
workspace. OpenClaw lists them in its prompt, but in harness-evals a listed
skill was followed on 1-3% of turns against 97-100% for the per-turn rule, so
install skills beside the rule, never instead of it. OpenClaw serves a skill
only whole: a SKILL.md larger than one read (64,000 characters on a model with
200k+ context, 32,000 at 100k-200k, 16,000 below, a 32,768-byte page when the
context window is unknown) gets "cannot be partially served" and nothing else.
Every SKILL.md gbrain installs for OpenClaw is at most 32,000 bytes
(test/openclaw-route.test.ts), so it loads on any model with 100k+ context
and when the window is unknown; on smaller models the 16,000-character cap
applies and the larger skills do not load.
Scheduled jobs and workspace scripts
OpenClaw cron jobs, workspace scripts and hooks run with another HOME and
environment than the gateway's MCP server. Route every one of them through a
single wrapper that sets GBRAIN_HOME, loads the brain's env file and runs the
installed gbrain by absolute path; log its stderr and check its exit code
(the wrapper and its rules).
On a managed brain, scripts commit the files they write with
gbrain git commit-push -- <paths> (never plain git commit); a scheduled
gbrain sources refresh <id>
keeps it current
(scripts and the managed checkout).
Have gbrain report back to this chat
When the brain owner has turned on reporting back
(gbrain wakeshift enable on the brain host), gbrain can wake an OpenClaw
session when a job, a pending write or a cron run it watches finishes. OpenClaw
needs Wakeshift's own plugin for that. Where the gateway runs (in its container,
if it's in one):
gbrain setup openclaw --wakeshift
It asks for consent, then runs OpenClaw's installer for the pinned
@wakeshift/[email protected] (openclaw plugins install npm:@wakeshift/[email protected] --force --accept-capabilities,
then openclaw plugins enable wakeshift --accept-capabilities) and checks that
the plugin loads. The plugin turns on OpenClaw's hooks endpoint with its own
token. On a gateway that listens beyond this computer, setup prints
Wakeshift's question about that endpoint; agreeing is yours to do
(openclaw config set plugins.entries.wakeshift.config.allowNetworkHooks true --strict-json),
and gbrain never sets it. The session shows a note starting Wakeshift: connected
after its first watch. gbrain doctor warns when the installed plugin is not
the pinned version. Remove it with
openclaw wakeshift reset && openclaw plugins uninstall wakeshift --force.
Verify
openclaw mcp list should show gbrain. Then start an agent turn and ask it
to use the brain:
Call get_brain_identity, then search my brain for [topic].
If the tools respond, the wiring works. list_skills shows everything the
brain can do (gated by mcp.publish_skills on the host).
Remove
Delete mcp.servers.gbrain from ~/.openclaw/openclaw.json (or run
openclaw mcp remove gbrain if your version has it), or uninstall the bundle
plugin.