Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(setup): keep the gateway-shared OpenClaw turn plugin on --workspace runs

garrytan5d159158e013
diff --git a/docs/mcp/OPENCLAW.md b/docs/mcp/OPENCLAW.md
index 9be826b9dd..cc2da8f5e8 100644
--- a/docs/mcp/OPENCLAW.md
+++ b/docs/mcp/OPENCLAW.md
@@ -107,6 +107,8 @@ OpenClaw requires `allowConversationAccess` before a non-bundled plugin's
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
diff --git a/src/commands/setup.ts b/src/commands/setup.ts
index acbed945e0..5f2d64c386 100644
--- a/src/commands/setup.ts
+++ b/src/commands/setup.ts
@@ -844,7 +844,7 @@ async function runInstructionsOnly(flags: SetupFlags, out: Out): Promise<number>
const turnHook = !off && !placed ? null : harness === 'hermes'
? (off ? removeHermesTurnHook({ hermesHome: dirname(target.path), dryRun: flags.dryRun }) : syncHermesTurnHook({ hermesHome: dirname(target.path), access, dryRun: flags.dryRun }))
: harness === 'openclaw'
- ? (off ? removeOpenclawTurnPlugin({ dryRun: flags.dryRun }) : syncOpenclawTurnPlugin({ access, dryRun: flags.dryRun }))
+ ? (off ? removeOpenclawTurnPlugin({ dryRun: flags.dryRun, workspace: flags.remove ? undefined : flags.workspace }) : syncOpenclawTurnPlugin({ access, dryRun: flags.dryRun, workspace: flags.workspace }))
: isTurnRuleHarness(harness) ? turnRuleHookFor(harness, off, flags, projectDir, rerun.join(' ')) : null;
// Loud failure: an accepted install whose per-turn hook does not load exits non-zero and names the harness's own check.
// A 'print' outcome installed nothing and already names the step that does, so it is reported, not verified.
diff --git a/src/core/setup/openclaw-turn-plugin.ts b/src/core/setup/openclaw-turn-plugin.ts
index 9937a81b10..73f60a0802 100644
--- a/src/core/setup/openclaw-turn-plugin.ts
+++ b/src/core/setup/openclaw-turn-plugin.ts
@@ -32,7 +32,7 @@ const DESCRIPTION = 'Puts the GBrain brain-first rule next to every user turn (m
export function openclawTurnPluginFiles(access: BrainFirstAccess): Record<string, string> {
const rule = renderBrainFirstTurnRule(access, 'openclaw');
return {
- 'package.json': `${JSON.stringify({ name: OPENCLAW_TURN_PLUGIN_ID, version: '1.0.0', private: true, type: 'module', openclaw: { extensions: ['./index.js'] } }, null, 2)}\n`,
+ 'package.json': `${JSON.stringify({ name: OPENCLAW_TURN_PLUGIN_ID, version: '1.0.0', private: true, type: 'module', openclaw: { extensions: ['./index.js'] }, gbrain: { access } }, null, 2)}\n`,
'openclaw.plugin.json': `${JSON.stringify({ id: OPENCLAW_TURN_PLUGIN_ID, name: 'GBrain turn rule', description: DESCRIPTION, configSchema: { type: 'object', additionalProperties: false } }, null, 2)}\n`,
'index.js': [
'// Managed by gbrain setup openclaw; a re-run rewrites this file. Remove: gbrain setup openclaw --remove',
@@ -69,9 +69,24 @@ const installArgv = (bin: string, dir: string): string[][] => [
const shown = (argv: string[]) => argv.map((a) => (/^[\w./:=@-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`)).join(' ');
-/** Write the plugin and install it with OpenClaw's CLI (accepted decision). Never throws. */
-export function syncOpenclawTurnPlugin(opts: { access: BrainFirstAccess; dryRun: boolean; openclawBin?: string | null; run?: Run }): OpenclawTurnPluginOutcome {
+/** The access an installed plugin records in its package.json: undefined with no plugin, null when an older gbrain wrote it without one. */
+function installedAccess(dir: string): BrainFirstAccess | null | undefined {
+ if (!existsSync(join(dir, 'index.js'))) return undefined;
+ try { return (JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { gbrain?: { access?: BrainFirstAccess } }).gbrain?.access ?? null; } catch { return null; }
+}
+
+const named = (a: BrainFirstAccess) => (a.kind === 'mcp' ? `the \`${a.server}\` MCP server` : `\`${a.launcher}\``);
+
+/**
+ * Write the plugin and install it with OpenClaw's CLI (accepted decision). Never throws. Every agent on the gateway gets
+ * the plugin's rule, so a `workspace`-scoped run leaves an installed plugin whose rule would change to another server.
+ */
+export function syncOpenclawTurnPlugin(opts: { access: BrainFirstAccess; dryRun: boolean; workspace?: string; openclawBin?: string | null; run?: Run }): OpenclawTurnPluginOutcome {
const dir = openclawTurnPluginDir();
+ const installed = opts.workspace ? installedAccess(dir) : undefined;
+ if (installed !== undefined && (!installed || renderBrainFirstTurnRule(installed, 'openclaw') !== renderBrainFirstTurnRule(opts.access, 'openclaw'))) {
+ return { action: 'skip', path: dir, detail: `${dir} left as it is: every agent on this OpenClaw gateway gets its rule, which ${installed ? `names ${named(installed)}` : 'an older gbrain wrote without recording its server'}, so a --workspace run does not rewrite it. To change it for every agent: gbrain setup openclaw --remove --workspace ${opts.workspace}, then run this again` };
+ }
const files = openclawTurnPluginFiles(opts.access);
const bin = opts.openclawBin !== undefined ? opts.openclawBin : findOpenclaw();
const commands = installArgv(bin ?? 'openclaw', dir);
@@ -101,9 +116,10 @@ export function syncOpenclawTurnPlugin(opts: { access: BrainFirstAccess; dryRun:
* until the uninstall succeeds: `install --link` put it in plugins.load.paths, and OpenClaw refuses a config
* whose load path is missing.
*/
-export function removeOpenclawTurnPlugin(opts: { dryRun: boolean; openclawBin?: string | null; run?: Run }): OpenclawTurnPluginOutcome {
+export function removeOpenclawTurnPlugin(opts: { dryRun: boolean; workspace?: string; openclawBin?: string | null; run?: Run }): OpenclawTurnPluginOutcome {
const dir = openclawTurnPluginDir();
if (!existsSync(dir)) return { action: 'skip', path: dir, detail: `no per-turn rule plugin at ${dir}` };
+ if (opts.workspace) return { action: 'skip', path: dir, detail: `${dir} left in place: every agent on this OpenClaw gateway gets its rule, so opting out one workspace does not remove it. Remove it for every agent with gbrain setup openclaw --remove --workspace ${opts.workspace}` };
if (opts.dryRun) return { action: 'remove', path: dir, detail: `per-turn rule plugin ${OPENCLAW_TURN_PLUGIN_ID} at ${dir}` };
const bin = opts.openclawBin !== undefined ? opts.openclawBin : findOpenclaw();
const uninstall = [bin ?? 'openclaw', 'plugins', 'uninstall', OPENCLAW_TURN_PLUGIN_ID, '--force'];
diff --git a/test/brain-first-turn-rule.test.ts b/test/brain-first-turn-rule.test.ts
index 921f829865..e93c9ecf42 100644
--- a/test/brain-first-turn-rule.test.ts
+++ b/test/brain-first-turn-rule.test.ts
@@ -314,6 +314,24 @@ describe('per-turn rule: OpenClaw before_prompt_build plugin', () => {
});
});
+ test('a --workspace run leaves the gateway-shared plugin when it names another server, and never removes it', async () => {
+ await withEnv({ OPENCLAW_STATE_DIR: state(), OPENCLAW_PROFILE: undefined }, async () => {
+ syncOpenclawTurnPlugin({ access, dryRun: false, openclawBin: '/bin/openclaw', run: recorder().run });
+ const index = readFileSync(join(openclawTurnPluginDir(), 'index.js'), 'utf8');
+ const rec = recorder();
+ const other = syncOpenclawTurnPlugin({ access: { kind: 'mcp', server: 'gbrain-a' }, workspace: '/ws/a', dryRun: false, openclawBin: '/bin/openclaw', run: rec.run });
+ expect(other.action).toBe('skip');
+ expect(other.detail).toContain('names the `gbrain` MCP server');
+ expect(readFileSync(join(openclawTurnPluginDir(), 'index.js'), 'utf8')).toBe(index);
+ expect(rec.calls).toEqual([]);
+ expect(syncOpenclawTurnPlugin({ access, workspace: '/ws/a', dryRun: false, openclawBin: '/bin/openclaw', run: recorder().run }).action).toBe('keep');
+ const kept = removeOpenclawTurnPlugin({ workspace: '/ws/a', dryRun: false, openclawBin: '/bin/openclaw', run: rec.run });
+ expect(kept.action).toBe('skip');
+ expect(rec.calls).toEqual([]);
+ expect(readFileSync(join(openclawTurnPluginDir(), 'index.js'), 'utf8')).toBe(index);
+ });
+ });
+
test('removal keeps the directory OpenClaw still loads when the uninstall fails or openclaw is not on PATH', async () => {
await withEnv({ OPENCLAW_STATE_DIR: state(), OPENCLAW_PROFILE: undefined }, async () => {
syncOpenclawTurnPlugin({ access, dryRun: false, openclawBin: '/bin/openclaw', run: recorder().run });
diff --git a/test/setup-brain-first.test.ts b/test/setup-brain-first.test.ts
index 8c0a4e71c6..1cbaed019b 100644
--- a/test/setup-brain-first.test.ts
+++ b/test/setup-brain-first.test.ts
@@ -280,6 +280,24 @@ describe('brain-first block: placement rules', () => {
expect(existsSync(join(b.home, '.openclaw', 'gbrain'))).toBe(false);
});
+ test('openclaw --workspace: the gateway-shared plugin is not rewritten for another server name or removed by one workspace opting out', async () => {
+ const b = box();
+ mkdirSync(join(b.home, '.openclaw', 'workspace'), { recursive: true });
+ writeFileSync(join(b.root, 'bin', 'openclaw'), '#!/bin/sh\nexit 0\n');
+ chmodSync(join(b.root, 'bin', 'openclaw'), 0o755);
+ const path = { PATH: `${join(b.root, 'bin')}:${process.env.PATH ?? ''}` };
+ const dir = join(b.home, '.openclaw', 'gbrain', 'gbrain-turn-rule');
+ await setup(b, ['openclaw'], path);
+ const index = read(join(dir, 'index.js'));
+ const ws = join(b.home, 'ws-a');
+ const renamed = await setup(b, ['openclaw', '--workspace', ws, '--name', 'gbrain-a', '--instructions-only'], path);
+ expect(renamed.doc.turn_hook.action).toBe('skip');
+ expect(read(join(dir, 'index.js'))).toBe(index);
+ const declined = await setup(b, ['openclaw', '--workspace', ws, '--no-instructions'], path);
+ expect(declined.doc.turn_hook.action).toBe('skip');
+ expect(read(join(dir, 'index.js'))).toBe(index);
+ });
+
test('a damaged block is preserved and reported, never guessed through', async () => {
const b = box();
const path = join(b.home, '.claude', 'CLAUDE.md');