On this page
On this page
Plugin guides
GBrain
The gbrain plugin connects OpenClaw to GBrain.
After you install it, OpenClaw has a gbrain MCP server that every agent run can use:
chat turns, cron jobs, heartbeats and subagents. You do not edit config by hand.
GBrain runs as its own service, which GBrain installs and supervises. OpenClaw never starts or restarts it: it runs GBrain's own commands once for first-time setup, then only connects and reports.
Before you install
On macOS and Linux, GBrain needs Bun 1.4.4 or newer. OpenClaw does
not install Bun. If neither gbrain nor bun is installed, the plugin shows this
command in the Control UI; run it once and setup finishes within a minute:
On Linux, Bun's installer also needs unzip (for example sudo apt install unzip).
In Docker, the GBrain container image already includes Bun; see Docker.
What install does
On the first Gateway start after install, the plugin:
- Uses the
gbraincommand when it is installed. When it is missing and Bun is installed, it runs GBrain's installer:bun install -g github:garrytan/gbrain#stable. - Starts GBrain's service with
gbrain mcp expose --no-tailscale --yes. GBrain installs a launchd agent (com.gbrain.serve) on macOS or a systemd user unit (gbrain-serve.service) on Linux, on127.0.0.1:3131. When no brain exists yet, the plugin first runsgbrain init --pglite --no-embedding(a local brain with keyword search; see GBrain's docs to add embeddings). - Creates an OpenClaw key through the running server's owner API (read and write).
- Writes
mcp.servers.gbrain(streamable HTTP with that key). The Gateway applies it without a restart.
An existing GBrain service on the same machine is reused as it is. An
mcp.servers.gbrain entry that points somewhere else, or that uses an
environment template such as ${GBRAIN_MCP_TOKEN}, is left as you configured it.
When the plugin replaces its key or follows a port change, it updates only the URL,
transport and Authorization header; your other settings on the entry stay.
Agents find GBrain's tools through tool search when a turn needs them. To make agents
check GBrain on every turn, run GBrain's own gbrain setup openclaw; it adds a
per-turn rule plugin. It is optional, and it adds a brain search to every turn.
Docker
The OpenClaw image has no Bun and no service manager, so GBrain runs in its own container next to the Gateway. Add the overlay when you start Compose:
Compose builds a small image on first start (Bun plus git, which gbrain upgrade
uses). The gbrain service installs GBrain's stable release into a volume, creates the
brain, runs gbrain mcp expose --no-tailscale --yes for its owner credential, and
then runs gbrain serve --http as the container's main process. Compose restarts it.
In a container the plugin looks for GBrain at 127.0.0.1 and then at the gbrain
Compose service on the project network, so Gateway and GBrain restarts do not affect
each other. Nothing is published on the host. The Gateway mounts GBrain's data
read-only to create its key; it never opens the brain.
Status and recovery
The plugin rechecks every minute and reports problems as plugin health in the Control
UI and in openclaw plugins inspect gbrain --runtime --json.
| You see | Cause | What to do |
|---|---|---|
| GBrain needs Bun 1.4.4 or newer | gbrain and bun are both missing |
Install Bun (curl -fsSL https://bun.sh/install | bash; on Linux it also needs unzip). Setup finishes within a minute. |
| GBrain is not running next to this container | Docker without the overlay | Start Compose with deploy/gbrain/compose.yaml. |
| GBrain's service is not answering | The service stopped or crashed | gbrain mcp expose --status; GBrain's supervisor restarts it. |
| Another program answers on 127.0.0.1:3131 | Port taken | Free the port, or gbrain mcp expose --no-tailscale --yes --port <port>; the plugin follows GBrain's receipt. |
| The gbrain memory server is running but cannot open its brain | Another gbrain serve (for example a stdio entry in another app) holds the PGLite brain |
Stop that process. GBrain rechecks every 5 seconds. |
A revoked or rotated OpenClaw key is replaced automatically within a minute.
gbrain upgrade needs no OpenClaw change.
Uninstall
openclaw plugins uninstall gbrain removes the plugin. It does not stop GBrain's
service or touch the brain. The mcp.servers.gbrain entry stays, so agents keep the
brain; remove it with openclaw mcp unset gbrain. Remove GBrain's service with
gbrain mcp expose --remove.
GBrain and Knowledge
Knowledge is a memory provider: it owns plugins.slots.memory.
The GBrain plugin owns no slot. It adds an MCP server, so you can use both: Knowledge
for OpenClaw's own memory prompt and recall, GBrain as a tool the agent calls.