feat: set up OpenClaw MCP and hooks from the agent install command by speakeasyforgebot · Pull Request #8108 · speakeasy-api/gram

speakeasyforgebot · 2026-10-26T17:10:38Z

Fixes DNO-1419

Why

Connecting an agent to OpenClaw took manual steps. The Plugins page plugin carries an org hooks key, and a cached sign-in could outrank any key, so sessions were not recorded under the agent.

What changed

Before: the agent install command configured other MCP clients only. OpenClaw needed the gateway added by hand and the plugin downloaded separately.

After: on a machine with openclaw, the same curl … | sh:

adds the agent gateway as the speakeasy MCP server, keeping the key out of process arguments;
installs the observability plugin with the agent's own key (agent_key: true, mode 600), using --force and --accept-capabilities when the CLI lists them;
sets allowConversationAccess, sends one test hook, prints PASS or FAIL, and says to restart the Gateway.

The Manual tab gains an OpenClaw command. The hooks binary now prefers a key marked as an agent's to a cached personal sign-in. An agent with no project gets the gateway only. Hooks from a dashboard-issued key also need #8015, which grants org:hooks_ingest.

Gutternote review steps

Sidebar → Identity → Agents → New (/<org>/projects/<project>/identities/agents/new). Pick a server, then Create agent.
The install step shows the command, a trusted-shell note, and a separate OpenClaw follow-up message with no code or key.
Deny clipboard access. Copy shows Copy failed.
Open Manual. The OpenClaw block runs openclaw mcp add speakeasy with the key from $SPEAKEASY_AGENT_KEY.

Recording

Local stack, OpenClaw 2026.10.6 in Docker: install, chat through the gateway, read the session.

agent-install-openclaw-e2e.mp4

🚀 Preview Environment (PR #8108)

Preview URL: https://pr-8108.dev.getgram.ai

Component	Status	Details	Updated (UTC)
✅ Database	Ready	Existing database reused	2026-10-28 21:03:01.
✅ Images	Available	Container images ready	2026-10-28 21:07:01.

_{Gram Preview Bot}

main reached 52 in #8085, so the manifest change needs its own bump to republish. Co-authored-by: Forge Bot <speakeasyforgebot@users.noreply.github.com>

It carries the hooks API key, and extraction honors the archive's Unix mode. Co-authored-by: Forge Bot <speakeasyforgebot@users.noreply.github.com>

- Make the installed speakeasy.json 0600 whatever mode the installer gives it. - Unpack the archive with python3 when unzip is missing. - Print a Gateway restart step instead of restarting from inside the turn. - Say a deleted project, not only a missing one, leaves the agent without hooks. - Correct the SecretRef note on the MCP header. - Run the script tests on a stub-only PATH and name the block-reason test for what it checks. Co-authored-by: Forge Bot <speakeasyforgebot@users.noreply.github.com>

…tall panel Co-authored-by: Forge Bot <speakeasyforgebot@users.noreply.github.com>

…rom the OpenClaw install Co-authored-by: Forge Bot <speakeasyforgebot@users.noreply.github.com>

changeset-bot · 2026-10-26T17:10:43Z

🦋 Changeset detected

Latest commit: 2bec0c0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
server	Minor
dashboard	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

linear-code · 2026-10-26T17:10:47Z

DNO-1419

A plugin's speakeasy.json can now mark its hooks_api_key as an agent's own key (agent_key). The hooks relay and the spool drain then use that key ahead of a cached speakeasy-hooks login, so an agent installed on a machine where a person signed in keeps its events under the agent. SPEAKEASY_AI_HOOKS_API_KEY still wins, and an org key from SPEAKEASY_AI_HOOKS_ORG_KEY is never treated as an agent's. The generator gains GenerateConfig.HooksKeyIsAgent to write the flag; published plugin output is unchanged. Co-authored-by: Forge Bot <speakeasyforgebot@users.noreply.github.com>

cubic-dev-ai

All reported issues were addressed across 13 files

_{Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic}

cubic-dev-ai

All reported issues were addressed across 10 files (changes from recent commits).

_{Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic}

cubic-dev-ai

All reported issues were addressed across 16 files

_{Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic}

…openclaw-review-5c3c

github-actions · 2026-10-28T16:55:02Z

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

github-actions · 2026-10-28T16:56:26Z

atlas migrate lint on server/migrations

Status	Step	Result
	No migration files detected
	ERD and visual diff generated	View Visualization
	No issues found	View Report
Read the full linting report on Atlas Cloud

github-actions · 2026-10-28T16:56:36Z

atlas migrate lint on clickhouse/migrations

Status	Step	Result
	No migration files detected
	ERD and visual diff generated	View Visualization
	No issues found	View Report
Read the full linting report on Atlas Cloud

blacksmith-sh · 2026-10-28T17:18:47Z

Found 1 test failure on Blacksmith runners:

Failure

Test	View Logs
`tests/` `wake-stack.spec.ts:123:1 › a paused worktree serves the resume page and comes back from` `it › the page reloads into the dashboard`	View Logs

^{Need help on this PR? Tag @codesmith-bot with what you need.}

gram-bot

Auto-approved: review:bypass label applied by @mfbx9da4. Required status checks still gate this merge.

cubic-dev-ai

1 issue found and verified against the latest diff

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/runbooks/hooks-environment-overrides.md">

<violation number="1" location="docs/runbooks/hooks-environment-overrides.md:72">
P2: This overstates the override for replay: `SPEAKEASY_AI_HOOKS_ORG_KEY` only replaces the baked key and clears `agent_key` on drain when the spooled deployment matches. Scope the sentence to match the code.</violation>
</file>

_{Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic}

cubic-dev-ai

All reported issues were addressed

_{Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic}

cubic-dev-ai

All reported issues were addressed across 28 files

_{Requires human review: Auto-approval blocked because this review re-detected 5 unresolved issues already reported by Cubic.

View guided diff | Turn on auto-fix | Re-trigger cubic}

Apply SPEAKEASY_AI_HOOKS_ORG_KEY on replay only when the environment names the entry's server, skip the Claude sign-in nudge for agent plugins, let an explicit login see an existing cached sign-in, and let WritePlugin mark an agent key. Tests clear the org key and deployment env vars.

Write the gateway entry through a private batch file and openclaw config set --batch-file, as the one-line setup does, then make the saved config owner-only.

cubic-dev-ai

All reported issues were addressed across 15 files (changes from recent commits).

_{Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic}

mfbx9da4 and others added 6 commits October 26, 2026 16:34

feat: set up OpenClaw MCP and hooks from the agent install command

68569ee

fix: bump hooksGeneratorVersion for the OpenClaw hook capability

2cf5adf

main reached 52 in #8085, so the manifest change needs its own bump to republish. Co-authored-by: Forge Bot <speakeasyforgebot@users.noreply.github.com>

fix: mark speakeasy.json owner-only in plugin ZIPs

f4d82ab

It carries the hooks API key, and extraction honors the archive's Unix mode. Co-authored-by: Forge Bot <speakeasyforgebot@users.noreply.github.com>

fix: surface clipboard failures and OpenClaw caveats on the agent ins…

6d0a8df

…tall panel Co-authored-by: Forge Bot <speakeasyforgebot@users.noreply.github.com>

docs: say where the agent key lands and what projectless agents get f…

1ba2cc0

…rom the OpenClaw install Co-authored-by: Forge Bot <speakeasyforgebot@users.noreply.github.com>

speakeasyforgebot requested review from a team as code owners October 26, 2026 17:10

github-actions Bot added the preview Spawn a preview environment label Oct 26, 2026

cubic-dev-ai Bot reviewed Oct 26, 2026

View reviewed changes

mfbx9da4 added 5 commits October 26, 2026 21:54

chore: merge main into agent hooks credential fixes

58a77b0

fix: preserve agent credential precedence during replay and publish

2ec5b37

chore: merge main into OpenClaw installer

8b725f2

fix: target the workspace package in credential release note

62edc82

fix: protect installer credentials and preserve working gateways

42c63fb

mfbx9da4 mentioned this pull request Oct 26, 2026

feat: set up OpenClaw MCP and hooks from the agent install command #8088

Closed

cubic-dev-ai Bot reviewed Oct 26, 2026

View reviewed changes

mfbx9da4 added 3 commits October 26, 2026 22:29

fix: preserve gateway config and clarify install checks

af7faf9

chore: stack agent installer on hooks credential precedence

e439516

fix: select agent credentials for generated hooks

db38b23

mfbx9da4 changed the base branch from main to cursor/agent-key-outranks-hooks-cache-da9f October 26, 2026 22:37

cubic-dev-ai Bot reviewed Oct 26, 2026

View reviewed changes

Comment thread docs/runbooks/openclaw-install.md Outdated

Comment thread server/internal/mcp/agentinstall/script.go

Comment thread server/internal/mcp/agentinstall/script_test.go

Merge remote-tracking branch 'origin/main' into cursor/agent-install-…

1dc6f50

…openclaw-review-5c3c

fix: refuse install codes for plain-HTTP origins

2867be0

mfbx9da4 changed the base branch from cursor/agent-key-outranks-hooks-cache-da9f to main October 28, 2026 17:00

mfbx9da4 mentioned this pull request Oct 28, 2026

fix: let an agent's baked hooks key outrank a cached sign-in #8109

Closed

mfbx9da4 reviewed Oct 28, 2026

View reviewed changes

Comment thread .changeset/agent-hook-credential-order.md Outdated

feat: show how to add the agent gateway to OpenClaw by hand

9d05150

mfbx9da4 added the review:bypass Merge without human review approval. Required status checks still apply. label Oct 28, 2026

mfbx9da4 enabled auto-merge October 28, 2026 17:38

chore: fold the agent install changesets into one

fac1953

gram-bot Bot approved these changes Oct 28, 2026

View reviewed changes

fix: stub only the clipboard in the OpenClaw install test

ab26596

cubic-dev-ai Bot reviewed Oct 28, 2026

View reviewed changes

Comment thread server/internal/plugins/generate.go

Comment thread server/internal/plugins/impl.go

Comment thread hooks/relay/drain_test.go

Comment thread hooks/relay/config.go

cubic-dev-ai Bot reviewed Oct 28, 2026

View reviewed changes

Comment thread hooks/relay/auth.go

Comment thread hooks/relay/provision.go Outdated

mfbx9da4 added 3 commits October 28, 2026 20:48

fix: keep the key-bearing install.sh owner-only in plugin ZIPs

f08cea1

fix: keep the agent key out of argv in the manual OpenClaw step

5d6d841

Write the gateway entry through a private batch file and openclaw config set --batch-file, as the one-line setup does, then make the saved config owner-only.

cubic-dev-ai Bot reviewed Oct 28, 2026

View reviewed changes

Comment thread hooks/relay/relay_test.go

Comment thread client/dashboard/src/pages/agents/credentials/StepInstall.tsx Outdated

Comment thread hooks/relay/relay_test.go

mfbx9da4 added 2 commits October 28, 2026 21:02

fix: write the hooks plugin config owner-only

d486aab

fix: fail the manual OpenClaw step when the config update fails

2bec0c0

mfbx9da4 added this pull request to the merge queue Oct 28, 2026

Merged via the queue into main with commit 9701990 Oct 28, 2026
59 of 60 checks passed

mfbx9da4 deleted the cursor/agent-install-openclaw-review-5c3c branch October 28, 2026 21:29

github-actions Bot locked and limited conversation to collaborators Oct 28, 2026

Conversation

speakeasyforgebot commented Oct 26, 2026 • edited by speakeasybot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What changed

Gutternote review steps

Recording

🚀 Preview Environment (PR #8108)

Uh oh!

changeset-bot Bot commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

linear-code Bot commented Oct 26, 2026

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 28, 2026

Uh oh!

github-actions Bot commented Oct 28, 2026

Uh oh!

Uh oh!

blacksmith-sh Bot commented Oct 28, 2026

Failure

Uh oh!

gram-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

speakeasyforgebot commented Oct 26, 2026 •

edited by speakeasybot

Loading

changeset-bot Bot commented Oct 26, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

github-actions Bot commented Oct 28, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading