docs: OpenClaw customer install runbook + generated README section - #5933
Merged
Conversation
The OpenClaw observability package shipped without install instructions: the generated ZIP README covered Claude Code, Cursor, Codex and OpenCode but not OpenClaw, and there was no runbook for the two things that silently break an install. - generated README: OpenClaw install section covering the directory install, --force, the required allowConversationAccess block, the Gateway restart, and the harness-split coverage caveat - docs/runbooks/openclaw-install.md: laptop and server/CI install paths, verification, enforcement semantics, version-pin policy and the operational gotchas from the DNO-950 spike - docs/plugins/overview.md: list OpenClaw alongside the other observability packages and the downloadObservabilityPlugin enum Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TiJy9DrFpsmnD2vEkDHKNv
Contributor
🦋 Changeset detectedLatest commit: 024520e The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
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 |
This was referenced Sep 1, 2026
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
All reported issues were addressed across 4 files
Reply with feedback, questions, or to request a fix.
Fix all with cubic | Re-trigger cubic
Review found several statements that were wrong rather than merely thin: - The coverage table implied claude-cli-routed sessions are always picked up by Claude Code hooks. They are not, unless those hooks are also deployed on the machine; a runbook-only install leaves them unobserved. - Step 2 pointed at a directory that does not exist until the downloaded archive is extracted. - `llm_input` and `before_agent_finalize` were listed as hooks that start firing once allowConversationAccess is on. The shipped shim subscribes neither, so they are never reported. - The 60s figure is the agenthooks serve timeout, not the handler deadline. Blocking gates fail closed at GATE_TIMEOUT_MS (10s), which is what an operator watching a stalled gate actually experiences. All three budgets are now spelled out. - The server/CI path was not executable from a clean image: it never said how to obtain the package or that the bootstrap fetches speakeasy-hooks over the network on first use. Also gates the generated README's OpenClaw section on a hooks key. With no key nothing OpenClaw-shaped is generated, so the section described files that were not in the repo, and covers both states with tests. The version-pin note is now a numbered qualification procedure, the manual fallback the issue allows in place of a canary. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TiJy9DrFpsmnD2vEkDHKNv
Contributor
There was a problem hiding this comment.
All reported issues were addressed across 3 files (changes from recent commits).
Reply with feedback, questions, or to request a fix.
Fix all with cubic | Re-trigger cubic
The runbook told operators to allowlist github.com for the hooks binary download. That is the wrong host and would leave an egress-isolated container broken in exactly the scenario the section addresses: the generated bootstrap fetches from the org's own Gram server (hooksServedTargets over cfg.ServerURL), which the hooks_bootstrap.go comment says is deliberate, since customer sandboxes often cannot reach GitHub while the Gram domain is already allowlisted for ingest. The GitHub URL is only where the server fetches upstream artifacts. The overview also claimed six observability platforms while publishing.md still said two and package-format.md documented three, so a reader could not tell what a publish actually produces. Adds the OpenClaw package format (layout, manifest, the conversation-access opt-in and the shim's deadlines) and replaces the stale count with the full slug table, verified against the slug generators. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TiJy9DrFpsmnD2vEkDHKNv
This comment has been minimized.
This comment has been minimized.
simplesagar
approved these changes
Sep 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes DNO-960. Split from #5929 so nothing here shares a rollback fate with the schema change.
Why
We ship an OpenClaw observability package but never told anyone how to install it. The generated ZIP README had sections for Claude Code, Cursor, Codex and OpenCode, and nothing for OpenClaw.
There was also no runbook for the two things that silently break an OpenClaw install — both of which produce a partly working state rather than an obvious failure, which is the worst kind.
What changed
--forcewhen replacing, the requiredallowConversationAccessblock, the Gateway restart, and the coverage caveatdocs/runbooks/openclaw-install.md: laptop and server/CI install paths, verification, enforcement semantics, version-pin policy, and the operational gotchas from the DNO-950 spikedocs/plugins/overview.md: OpenClaw listed alongside the other observability packages and in thedownloadObservabilityPluginenumThe two traps the runbook exists for
allowConversationAccess. Without it the conversation hooks silently never fire — no prompts, no assistant responses, no usage — while tool hooks keep working. A half-configured install looks partly fine.agentRuntime: claude-cli, whichopenclaw models auth loginwrites by default when a claude-cli profile exists), OpenClaw delegates the model and tool loop out-of-process and its tool/LLM hooks never fire. Those sessions are still covered — by our Claude Code hooks — so this is complementary coverage rather than a hole, but a customer in that mode will otherwise think the integration is broken.Notes
generate.gois a server implementation file, but the change is purely the customer-facing install text, so it belongs with the runbook rather than the feature PR.hooksGeneratorVersionbump needed: the README is not part of the rendered hook-plugin subtree thatcheck-generator-versionsdiffs. Confirmed by renderingexport-hook-plugin -publishedand checking the file list.latest: it would page on OpenClaw's release cadence and registry flakes without telling us what we actually support — the same reasoning that keeps the LiteLLM real-proxy suite onworkflow_dispatch.Related PRs
Independent — all three branch from
main, no stacking:feat:source alias and turn correlationmig:the materialized-view change🤖 Generated with Claude Code
https://claude.ai/code/session_01TiJy9DrFpsmnD2vEkDHKNv
Summary by cubic
Adds OpenClaw install docs for the observability plugin — the generated ZIP README now has an OpenClaw section, and a new runbook covers laptop and server/CI installs. Two configuration states silently break coverage without any error, and both are now documented.
allowConversationAccessdrops prompt and usage capture while tool hooks keep working, and the Claude CLI harness routes sessions through Claude Code hooks, which capture them only if those hooks are also deployed on the machine.docs/plugins/package-format.md, and lists OpenClaw indocs/plugins/overview.md, thedownloadObservabilityPluginenum, and the observability slug table indocs/plugins/publishing.md.Written for commit 024520e. Summary will update on new commits.