The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Document OpenClaw Gateway as a fully collected runtime
Claude1c8505280ecc
diff --git a/CLAUDE.md b/CLAUDE.mdindex 5a56c47a..5ee48b46 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -12,7 +12,7 @@ Beacon Endpoint Agent is a local-only endpoint telemetry agent for AI runtimes.- `packages/asymptote-sdk-js`: TypeScript SDK for cloud agent telemetry that exports Beacon-compatible OpenTelemetry spans.- `browser-extension`: optional Chrome MV3 collector that relays Claude.ai and ChatGPT chat telemetry into the local pipeline as OTLP.- `pkg/asymptoteobserve`: shared Go library — event schema, harness-name normalization, provenance markers, token usage, and the threat-rules engine. Imported by the CLI, the hook adapter, and the collector exporter, so a change here reaches all three.-- `plugins`: TypeScript sources for the managed runtime plugins/extensions (`opencode-beacon`, `cline-beacon`, `pi-beacon`, `omp-beacon`), each mirrored into an embedded copy under `cli/beacon/internal/endpoint/hooks/assets/`.+- `plugins`: TypeScript sources for the managed runtime plugins/extensions (`opencode-beacon`, `cline-beacon`, `pi-beacon`, `omp-beacon`, `openclaw-beacon`), each mirrored into an embedded copy under `cli/beacon/internal/endpoint/hooks/assets/`.- `rules` and `spec/threat-rules`: the open rule corpus and the Threat Rules format it conforms to.- `beacon-sandbox`: harness that runs a real Claude Code session in a disposable sandbox and checks what Beacon captured. See `beacon-sandbox/AGENTS.md`.- `packaging`: macOS, Linux, and Windows packaging and deployment assets.@@ -47,7 +47,8 @@ Supported runtime surfaces today:- goose (Block) telemetry over two paths that are collected together because neither is sufficient alone. The hook path is a Beacon-owned plugin: goose discovers plugins as the immediate subdirectories of `.agents/plugins` (user scope honours `GOOSE_PATH_ROOT`; project scope is always `<project>/.agents/plugins`) and loads `<plugin-root>/hooks/hooks.json` from each, so Beacon owns the directory `beacon-endpoint` rather than a file. Seven of goose's twelve events are subscribed to -- `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `SessionEnd` -- covering session lifecycle, prompts, tool lifecycle, command lines, file creates and edits with diffs, and MCP tool calls. The OTLP path configures `otel_exporter_otlp_endpoint` in goose's own `config.yaml` and carries what no hook does: token usage including cache reads and writes, model and provider, response ids, finish reasons and agent reasoning, on OTel GenAI semconv `chat` and `execute_tool` spans the collector exporter already reads. The harness is `goose`; GooseAI spellings are deliberately unmapped in `NormalizeHarnessName` and unaccepted as targets, because that is a different company's inference service rather than this runtime. Four contract details are load-bearing. goose classifies a *blocking* hook's stdout, so `PreToolUse` and `Stop` must answer `{"decision":"allow"}` -- the `{}` every other runtime reads as no opinion is classified a failed hook, and on a rule configured `on_failure: block` it denies the tool call; the policy seam's deny is correspondingly `{"decision":"block"}`, because goose does not recognise "deny" and would read it as no verdict and allow. `developer` is registered with `unprefixed_tools`, so its tools arrive as bare `shell`, `write`, `edit`, `tree`, `read_image`, and MCP tools are identified only by their `<extension>__<tool>` prefix not naming a built-in extension -- there is no `mcp` in the name, no `mcp_*` argument and no result to inspect. `PostToolUseFailure` carries a payload identical to `PostToolUse`, so the `event` field is the only thing separating a write that landed from one that did not, and it is what the diff guard turns on. And goose exports OTLP over HTTP only, so it takes the collector's HTTP port where Claude Code, Codex and Gemini take gRPC; pointing it at 4317 fails silently. `BeforeShellExecution`, `AfterShellExecution`, `BeforeReadFile` and `AfterFileEdit` are deliberately not subscribed to -- each duplicates `PreToolUse`/`PostToolUse` for the same call and carries no `tool_call_id` -- and `PreToolUseResult` is deferred because it fires once per call to report an outcome that is almost always "allow". Not collected, because goose exposes none of it on a hook: tool output of any kind (so no command exit codes, no command output, no file-read contents), reported cost, and approval decisions -- goose does ask the operator through `ToolApprovalOperation`, exposes none of it, and its `PreToolUse` chain is a separate plugin-policy layer that runs after the operator's decision, so an approval derived from it would claim a decision precisely where Beacon cannot see one. `.agents/plugins` is the shared Open Plugins directory rather than goose's own namespace, so another host implementing that specification would also run these hooks and Beacon could not tell from the payload; that is a stated limitation with no fix on Beacon's side. **Only the adapter half of this is implemented.** `cli/beacon-hooks/cmd/goose.go` maps the payloads and `NormalizeHarnessName` pins the name, so a `hooks.json` that invokes `beacon-hooks --platform goose` is collected correctly today. There is no installer: `goose` is not an accepted `beacon endpoint hooks install --harness` target, there is no `cli/beacon/internal/endpoint/hooks/goose.go`, and no `harness.DiscoverGoose` configures `otel_exporter_otlp_endpoint` in goose's `config.yaml`. Both files must be written by hand. `docs/runtimes/goose.mdx` and the README runtime table both describe the install commands as if they shipped; they have not. Close that gap before treating goose as a supported install target.- fx (vercel-labs/fx) telemetry read from the session store fx commits under `~/.fx/sessions/`, covering session start, prompts, tool calls, commands with exit codes and output, file reads/creates/edits with diffs, MCP tool calls, agent messages, history compaction, and per-turn token usage plus reported cost. fx exposes no third-party hook, plugin, or OTLP surface -- its lifecycle hooks are compiled into the binary -- so collection is a read of fx's own records, run by `beacon endpoint fx sync`. Every event carries `harness.collection_method=poll`; approvals are not synthesized (fx persists permission feedback text, not a per-call decision, matching the Cline and Pi posture) and no session-end event is invented, since fx sessions are resumable. Implementation lives in `cli/beacon/internal/fxsession` and `cli/beacon/cmd/endpoint_fx.go`.- Claude Cowork admin-configured OpenTelemetry setup guidance and local validation.-- Runtimes that ride the shared hook and OTLP paths without a contract worth writing down here: Antigravity CLI, Devin CLI, Devin Desktop, Factory Droid, Gemini CLI, GitHub Copilot CLI, Grok Build, Hermes Agent, OpenCode (a Beacon-managed plugin, `plugins/opencode-beacon`), Qwen Code, and VS Code. OpenClaw Gateway is OTLP setup guidance and status checking under `cli/beacon/internal/endpoint/integrations/openclaw`, the same shape as Cowork, rather than a harness. The bullets above are the runtimes with a reverse-engineered or otherwise surprising contract, not the full supported set — `harness.DiscoverAll` in `cli/beacon/internal/endpoint/harness` and the install switch in `cli/beacon/cmd/endpoint_hooks.go` are the authoritative lists. Prime Agent has a reserved harness name and a `plugin` collection method but no collection path yet.+- OpenClaw Gateway telemetry over two paths, collected together because neither is sufficient alone. The plugin path is a Beacon-managed plugin: OpenClaw discovers a plugin as the *directory* `beacon-endpoint` under an extensions root (user scope honours `OPENCLAW_STATE_DIR`; project scope is always `<workspace>/.openclaw/extensions`), holding three files -- a plain-JavaScript entry plus the `package.json` and `openclaw.plugin.json` that declare it, with the entry named under both `openclaw.extensions` and `openclaw.runtimeExtensions` so either host build reaches it. Ten of OpenClaw's forty-one typed hooks are registered, covering session lifecycle and resume, prompts, tool lifecycle, commands with exit code and output, file reads/creates/edits with diffs, `apply_patch` as one `file.modified` per changed path, MCP tool calls, compaction, subagent lifecycle, and token usage including cache reads and writes. The OTLP path is OpenClaw's own `diagnostics-otel` plugin, configured *inside OpenClaw* and only printed by `beacon endpoint integrations openclaw` (`cli/beacon/internal/endpoint/integrations/openclaw`); it carries gateway traces and metrics, and by OpenClaw's default carries no content at all. Both paths report the harness `openclaw_gateway`. Five contract details are load-bearing. OpenClaw registers `before_tool_call` **fail-closed**, so a handler that throws or exceeds its timeout blocks the tool call -- that handler therefore dispatches and returns synchronously with no promise to await, which costs event ordering and nothing else, since `gen_ai.tool.call.id` is the join. Conversation hooks, `llm_output` among them, are withheld from every non-bundled plugin until `plugins.entries.beacon-endpoint.hooks.allowConversationAccess` is set, so an otherwise perfect install collects everything except tokens and agent messages. Beacon reads OpenClaw's config and never writes it -- it is JSON *or JSON5*, and a Go round trip would strip an operator's comments out of the file configuring every chat channel they run -- so the installer prints advice instead, and only mentions `plugins.allow` when that key already exists, because introducing an allowlist would deny every other plugin. MCP tools are named `<server>__<tool>` with no `mcp` anywhere, so the separator is the only signal, as on goose. And `derivedPaths` arrives only on `before_tool_call`, so the plugin carries it forward by `toolCallId` -- without it an `apply_patch` is an opaque blob with no file rows. The prompt is `message_received`, the inbound chat message, not `llm_input`'s assembled prompt. Approval decisions are not exposed by OpenClaw's plugin hooks and are not synthesized, matching the Cline, Pi, goose, OpenHands and Kiro decision; the trap is that an `exec` result's `details.approvalReviewOutcome` reads like one and is a *model-backed* review, so it stays in `raw`. Not collected: reported cost (OpenClaw computes it from an operator-configured table rather than a provider report), and gateway lifecycle. Deliberately not registered: the prompt-injection, claim, gate and evaluate hooks, which would give Beacon power over the agent; `llm_input` and `agent_end`, which carry the whole conversation per call; and the two synchronous persistence hooks, which ignore promises. Implementation lives in `plugins/openclaw-beacon`, `cli/beacon-hooks/cmd/openclaw_event.go` and `cli/beacon/internal/endpoint/hooks/openclaw.go`.+- Runtimes that ride the shared hook and OTLP paths without a contract worth writing down here: Antigravity CLI, Devin CLI, Devin Desktop, Factory Droid, Gemini CLI, GitHub Copilot CLI, Grok Build, Hermes Agent, OpenCode (a Beacon-managed plugin, `plugins/opencode-beacon`), Qwen Code, and VS Code. The bullets above are the runtimes with a reverse-engineered or otherwise surprising contract, not the full supported set — `harness.DiscoverAll` in `cli/beacon/internal/endpoint/harness` and the install switch in `cli/beacon/cmd/endpoint_hooks.go` are the authoritative lists. Prime Agent has a reserved harness name and a `plugin` collection method but no collection path yet.- Browser chat telemetry through an optional Chrome MV3 extension (`browser-extension/`) covering claude.ai and chatgpt.com. A main-world interceptor tees the streamed response, a per-site adapter parses it into a normalized turn, and the service worker POSTs OTLP GenAI logs to the local collector on `127.0.0.1:4318`; the extension never writes files and never contacts a remote endpoint. `harness.name` resolves to `claude_web` or `chatgpt_web` (already handled by `NormalizeHarnessName` in `pkg/asymptoteobserve/harness.go`, where the browser cases must stay above the generic `claude` rule) and `harness.collection_method` is `otlp`. Scope is deliberately narrow: only those origins' chat streams, never other tabs or general browsing. Retention defaults to `full`, so prompt and response text is retained by default; this is documented rather than defaulted down, because browser chat telemetry without content has no investigative value. Treat the adapters as experimental, since both sites' stream formats are private and undocumented.- `beaconjson` OpenTelemetry Collector exporter that converts OTLP logs, traces, metrics, and resource attributes into Beacon endpoint JSONL.- Endpoint inventory (`inventory.heartbeat` / `inventory.snapshot` in `inventory_state.jsonl`) is written by a scheduled job, `com.beacon.endpoint.inventory` (`service.InventoryManager`, user LaunchAgent or system LaunchDaemon, `beacon-inventory.timer` on systemd), every six hours and once at load, on by default and reconciled by `lifecycle.ReconcileInventoryJob` on every install, repair and package upgrade (`beacon endpoint inventory install-daemon`). Agent hooks do not trigger inventory any more; the hook binary's `--cli` flag and `inventory-heartbeat` subcommand survive only as no-ops for hook commands written by older versions, and `beacon endpoint inventory heartbeat --trigger hook` is likewise retired. A system-mode run inventories the active console user's home and still writes the liveness heartbeat when nobody is logged in; the scheduled scan has no working directory, so project-scoped config is only in `beacon endpoint inventory`.diff --git a/README.md b/README.mdindex 3dc5d504..ae192a78 100644--- a/README.md+++ b/README.md@@ -174,7 +174,7 @@ for the full breakdown by surface.| <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/kiro.png" alt="" width="16"> | [Kiro](https://docs.asymptotelabs.ai/runtimes/kiro) | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | – | ✅ | – || <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/muse-code.png" alt="" width="16"> | [Muse Code](https://docs.asymptotelabs.ai/runtimes/muse-code) | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | – | – || <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/omp.png" alt="" width="16"> | [Oh My Pi](https://docs.asymptotelabs.ai/runtimes/oh-my-pi) | Extension | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |-| <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/openclaw.png" alt="" width="16"> | [OpenClaw Gateway](https://docs.asymptotelabs.ai/cli/supported-runtimes-openclaw-gateway) | OTLP | ~ | ~ | ~ | ~ | ~ | ~ | ~ | ~ |+| <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/openclaw.png" alt="" width="16"> | [OpenClaw Gateway](https://docs.asymptotelabs.ai/runtimes/openclaw-gateway) | Plugin + OTLP | ✅ | ✅ | ✅ | ✅ | ✅ | – | ✅ | ~ || <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/opencode.png" alt="" width="16"> | [OpenCode](https://docs.asymptotelabs.ai/cli/supported-runtimes-opencode) | Plugin | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ || <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/openhands.png" alt="" width="16"> | [OpenHands](https://docs.asymptotelabs.ai/runtimes/openhands) | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | – | ✅ | – || <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/pi-agent.png" alt="" width="16"> | [Pi](https://docs.asymptotelabs.ai/runtimes/pi) | Extension | ✅ | ✅ | ✅ | ✅ | ✅ | – | – | ✅ |diff --git a/docs/cli/endpoint-discover.mdx b/docs/cli/endpoint-discover.mdxindex aa83f438..e145be76 100644--- a/docs/cli/endpoint-discover.mdx+++ b/docs/cli/endpoint-discover.mdx@@ -11,9 +11,9 @@ description: "Discover supported local agent harnesses and their Beacon telemetrbeacon endpoint discover```-Beacon discovers local runtime surfaces and reports their telemetry configuration state, including whether supported configuration appears Beacon-managed or customer-managed. By default, discover prints detected targets. Add `--all` to include every supported runtime target, including runtimes that are not detected on the host. OpenClaw Gateway is validated through the `beacon endpoint integrations openclaw` commands after Gateway diagnostics export is configured.+Beacon discovers local runtime surfaces and reports their telemetry configuration state, including whether supported configuration appears Beacon-managed or customer-managed. By default, discover prints detected targets. Add `--all` to include every supported runtime target, including runtimes that are not detected on the host. OpenClaw Gateway is discovered through its managed plugin, and its separate gateway OTLP export is validated through the `beacon endpoint integrations openclaw` commands after Gateway diagnostics export is configured.-Gemini CLI discovery looks for the `gemini` executable and `~/.gemini/settings.json`, then checks whether local OTLP telemetry is enabled for Beacon. VS Code discovery checks Copilot Chat OpenTelemetry configuration and reports Beacon-managed state when the OTLP endpoint points at Beacon's local receiver. GitHub Copilot CLI discovery looks for the `copilot` executable or `~/.copilot/config.json`, then validates that `COPILOT_OTEL_ENABLED=true` and the effective OTLP endpoint points at Beacon's local HTTP receiver, usually `http://127.0.0.1:4318`. Claude Code discovery looks for the `claude` executable and Claude settings paths; optional Claude hook status is available through `beacon endpoint hooks status --harness claude`. Antigravity CLI discovery looks for the `antigravity` or `antigravity-cli` executable, `~/.gemini/config`, or `./.agents`, then checks whether Beacon endpoint hooks are installed in `~/.gemini/config/hooks.json` or `./.agents/hooks.json`. Grok Build discovery checks whether Beacon's managed hook file is installed at `~/.grok/hooks/beacon-endpoint.json` or `./.grok/hooks/beacon-endpoint.json`. Hermes Agent discovery looks for the `hermes` executable or `~/.hermes`, then checks `~/.hermes/config.yaml` for Beacon-managed hooks, identified by the endpoint settings flags (`--log`, `--config`, `--cli`) or a legacy `BEACON_ENDPOINT_MODE=1` prefix, together with `--platform hermes`. OpenCode discovery looks for the `opencode` executable or `~/.config/opencode`, then checks whether Beacon's managed plugin is installed at `~/.config/opencode/plugins/beacon.ts`. Cline discovery looks for `~/.cline` and treats a `cline` executable as an additional signal rather than the deciding one, because Cline's VS Code and JetBrains hosts ship no executable; it then checks whether Beacon's managed plugin is installed at `~/.cline/plugins/beacon.ts`. Pi discovery looks for the `pi` executable and treats `~/.pi/agent` as an additional signal, because an npm, pnpm, or bun install is often absent from the inherited `PATH` while its state directory is not; it then reports whether Beacon's managed extension is installed at `~/.pi/agent/extensions/beacon.ts`, and reports a `beacon.ts` without Beacon's marker as disabled rather than enabled. Oh My Pi discovery looks for the `omp` executable and treats the resolved agent directory as an additional signal for the same reason as Pi; it then reports whether Beacon's managed extension is installed at `~/.omp/agent/extensions/beacon.ts`, and honors `PI_CODING_AGENT_DIR` and `PI_CONFIG_DIR` when resolving that path. fx discovery looks for the `fx` executable and treats `~/.fx` as an additional signal; because fx has no file Beacon writes into, its telemetry status reports how much of the session store under `~/.fx/sessions` has actually been collected rather than whether a marker is present, distinguishing "no sessions yet" from "sessions present and none collected" from "collected and current". Qwen Code discovery looks for the `qwen` executable and treats `~/.qwen` as an additional signal, because an npm or version-manager install is often absent from the inherited `PATH` while its config directory is not; it then checks `~/.qwen/settings.json` for Beacon hook commands carrying `--platform qwen`, reporting hooks turned off by `disableAllHooks` as disabled and invalid settings JSON as misconfigured rather than missing. Devin CLI discovery looks for the `devin` executable, `~/.config/devin`, or `./.devin`, then checks whether Beacon endpoint hooks are installed in `~/.config/devin/config.json` or `./.devin/hooks.v1.json`; `devin` remains a legacy alias for `devin-cli`. Devin Desktop discovery checks Cascade/Windsurf hook files at `~/.codeium/windsurf/hooks.json` or `./.windsurf/hooks.json`. Factory Droid discovery looks for the `droid` executable and validates the effective `OTEL_TELEMETRY_ENDPOINT` launch environment without treating customer-managed shell export values as Beacon-owned configuration. Set MDM-managed launch environments to Beacon's local OTLP HTTP receiver through MDM or another customer-owned launch policy.+Gemini CLI discovery looks for the `gemini` executable and `~/.gemini/settings.json`, then checks whether local OTLP telemetry is enabled for Beacon. VS Code discovery checks Copilot Chat OpenTelemetry configuration and reports Beacon-managed state when the OTLP endpoint points at Beacon's local receiver. GitHub Copilot CLI discovery looks for the `copilot` executable or `~/.copilot/config.json`, then validates that `COPILOT_OTEL_ENABLED=true` and the effective OTLP endpoint points at Beacon's local HTTP receiver, usually `http://127.0.0.1:4318`. Claude Code discovery looks for the `claude` executable and Claude settings paths; optional Claude hook status is available through `beacon endpoint hooks status --harness claude`. Antigravity CLI discovery looks for the `antigravity` or `antigravity-cli` executable, `~/.gemini/config`, or `./.agents`, then checks whether Beacon endpoint hooks are installed in `~/.gemini/config/hooks.json` or `./.agents/hooks.json`. Grok Build discovery checks whether Beacon's managed hook file is installed at `~/.grok/hooks/beacon-endpoint.json` or `./.grok/hooks/beacon-endpoint.json`. Hermes Agent discovery looks for the `hermes` executable or `~/.hermes`, then checks `~/.hermes/config.yaml` for Beacon-managed hooks, identified by the endpoint settings flags (`--log`, `--config`, `--cli`) or a legacy `BEACON_ENDPOINT_MODE=1` prefix, together with `--platform hermes`. OpenCode discovery looks for the `opencode` executable or `~/.config/opencode`, then checks whether Beacon's managed plugin is installed at `~/.config/opencode/plugins/beacon.ts`. Cline discovery looks for `~/.cline` and treats a `cline` executable as an additional signal rather than the deciding one, because Cline's VS Code and JetBrains hosts ship no executable; it then checks whether Beacon's managed plugin is installed at `~/.cline/plugins/beacon.ts`. Pi discovery looks for the `pi` executable and treats `~/.pi/agent` as an additional signal, because an npm, pnpm, or bun install is often absent from the inherited `PATH` while its state directory is not; it then reports whether Beacon's managed extension is installed at `~/.pi/agent/extensions/beacon.ts`, and reports a `beacon.ts` without Beacon's marker as disabled rather than enabled. Oh My Pi discovery looks for the `omp` executable and treats the resolved agent directory as an additional signal for the same reason as Pi; it then reports whether Beacon's managed extension is installed at `~/.omp/agent/extensions/beacon.ts`, and honors `PI_CODING_AGENT_DIR` and `PI_CONFIG_DIR` when resolving that path. OpenClaw Gateway discovery looks for the `openclaw` executable and treats the extensions directory as an additional signal, because a gateway is commonly run as a daemon under an account whose `PATH` this process did not inherit; it then reports whether Beacon's managed plugin is installed at `~/.openclaw/extensions/beacon-endpoint/`, honors `OPENCLAW_STATE_DIR` when resolving that path, and reports a plugin directory missing either manifest as disabled rather than enabled, because OpenClaw skips such a directory silently. fx discovery looks for the `fx` executable and treats `~/.fx` as an additional signal; because fx has no file Beacon writes into, its telemetry status reports how much of the session store under `~/.fx/sessions` has actually been collected rather than whether a marker is present, distinguishing "no sessions yet" from "sessions present and none collected" from "collected and current". Qwen Code discovery looks for the `qwen` executable and treats `~/.qwen` as an additional signal, because an npm or version-manager install is often absent from the inherited `PATH` while its config directory is not; it then checks `~/.qwen/settings.json` for Beacon hook commands carrying `--platform qwen`, reporting hooks turned off by `disableAllHooks` as disabled and invalid settings JSON as misconfigured rather than missing. Devin CLI discovery looks for the `devin` executable, `~/.config/devin`, or `./.devin`, then checks whether Beacon endpoint hooks are installed in `~/.config/devin/config.json` or `./.devin/hooks.v1.json`; `devin` remains a legacy alias for `devin-cli`. Devin Desktop discovery checks Cascade/Windsurf hook files at `~/.codeium/windsurf/hooks.json` or `./.windsurf/hooks.json`. Factory Droid discovery looks for the `droid` executable and validates the effective `OTEL_TELEMETRY_ENDPOINT` launch environment without treating customer-managed shell export values as Beacon-owned configuration. Set MDM-managed launch environments to Beacon's local OTLP HTTP receiver through MDM or another customer-owned launch policy.## Flagsdiff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdxindex b6c9065f..6d186733 100644--- a/docs/cli/endpoint-install.mdx+++ b/docs/cli/endpoint-install.mdx@@ -22,7 +22,7 @@ By default, Beacon configures Claude Code and Codex CLI telemetry for local or c| `--user` | Use per-user endpoint paths. Enabled by default || `--system` | Use system endpoint paths and launch daemon. Requires root || `--log-path <path>` | Runtime JSONL log path |-| `--harness <list>` | Comma-separated harnesses to configure. Defaults to `claude,codex`; include `gemini` for Gemini CLI or `vscode` for VS Code Copilot OTLP telemetry. Hook harnesses can be listed alongside them: `claude-hooks` (Claude Code hooks), `cursor`, `factory`, `opencode`, `cline`, `pi`, `omp`, `grok`, `qwen`, `hermes`, `antigravity`, `devin-cli`, and `devin-desktop`, for example `beacon endpoint install --harness claude,codex,cursor`. `beacon endpoint hooks install` adds the same hooks to an existing install later, and is the only way to add VS Code hook telemetry. GitHub Copilot CLI and Factory Droid OTLP endpoints are managed through their launch environments |+| `--harness <list>` | Comma-separated harnesses to configure. Defaults to `claude,codex`; include `gemini` for Gemini CLI or `vscode` for VS Code Copilot OTLP telemetry. Hook harnesses can be listed alongside them: `claude-hooks` (Claude Code hooks), `cursor`, `factory`, `opencode`, `cline`, `pi`, `omp`, `openclaw`, `grok`, `qwen`, `hermes`, `antigravity`, `devin-cli`, and `devin-desktop`, for example `beacon endpoint install --harness claude,codex,cursor`. `beacon endpoint hooks install` adds the same hooks to an existing install later, and is the only way to add VS Code hook telemetry. GitHub Copilot CLI and Factory Droid OTLP endpoints are managed through their launch environments || `--otlp-grpc-port <port>` | Local OTLP gRPC port. Defaults to `4317` || `--otlp-http-port <port>` | Local OTLP HTTP port. Defaults to `4318` || `--collector <path>` | Path to a `beacon-otelcol` binary |diff --git a/docs/cli/endpoint-repair.mdx b/docs/cli/endpoint-repair.mdxindex bbfca88f..3b26ba31 100644--- a/docs/cli/endpoint-repair.mdx+++ b/docs/cli/endpoint-repair.mdx@@ -22,7 +22,7 @@ During repair, Beacon removes the existing managed service before reinstalling i| `--user` | Use per-user endpoint paths. Enabled by default || `--system` | Use system endpoint paths and launch daemon || `--log-path <path>` | Runtime JSONL log path |-| `--harness <list>` | Comma-separated harnesses to configure. Defaults to `claude,codex`; include `gemini` for Gemini CLI or `vscode` for VS Code Copilot OTLP telemetry. Hook harnesses can be listed alongside them: `claude-hooks` (Claude Code hooks), `cursor`, `factory`, `opencode`, `cline`, `pi`, `omp`, `grok`, `qwen`, `hermes`, `antigravity`, `devin-cli`, and `devin-desktop`, for example `beacon endpoint repair --harness claude,codex,cursor`. `beacon endpoint hooks install` adds the same hooks to an existing install later, and is the only way to add VS Code hook telemetry. GitHub Copilot CLI and Factory Droid OTLP endpoints are managed through their launch environments |+| `--harness <list>` | Comma-separated harnesses to configure. Defaults to `claude,codex`; include `gemini` for Gemini CLI or `vscode` for VS Code Copilot OTLP telemetry. Hook harnesses can be listed alongside them: `claude-hooks` (Claude Code hooks), `cursor`, `factory`, `opencode`, `cline`, `pi`, `omp`, `openclaw`, `grok`, `qwen`, `hermes`, `antigravity`, `devin-cli`, and `devin-desktop`, for example `beacon endpoint repair --harness claude,codex,cursor`. `beacon endpoint hooks install` adds the same hooks to an existing install later, and is the only way to add VS Code hook telemetry. GitHub Copilot CLI and Factory Droid OTLP endpoints are managed through their launch environments || `--otlp-grpc-port <port>` | Local OTLP gRPC port. Defaults to `4317` || `--otlp-http-port <port>` | Local OTLP HTTP port. Defaults to `4318` || `--collector <path>` | Path to a `beacon-otelcol` binary |diff --git a/docs/cli/hooks.mdx b/docs/cli/hooks.mdxindex 75587003..e3e13512 100644--- a/docs/cli/hooks.mdx+++ b/docs/cli/hooks.mdx@@ -50,7 +50,7 @@ In system mode, the hook binary is written under `/Library/Application Support/B| Flag | Description ||------|-------------|-| `--harness <list>` | Comma-separated hook harnesses, such as `antigravity`, `claude`, `cline`, `codex`, `cursor`, `devin-cli`, `devin-desktop`, `factory`, `grok`, `hermes`, `omp`, `opencode`, `pi`, `qwen`, or `antigravity,claude,cline,codex,cursor,devin-cli,devin-desktop,factory,grok,hermes,omp,opencode,pi,qwen`. `devin` remains a legacy alias for `devin-cli`; `hermes-agent` maps to `hermes`; `qwen-code` maps to `qwen`; `pi-cli` and `pi_cli` map to `pi`; `oh-my-pi` and `ohmypi` map to `omp`. Defaults to `cursor` |+| `--harness <list>` | Comma-separated hook harnesses, such as `antigravity`, `claude`, `cline`, `codex`, `cursor`, `devin-cli`, `devin-desktop`, `factory`, `grok`, `hermes`, `omp`, `openclaw`, `opencode`, `pi`, `qwen`, or `antigravity,claude,cline,codex,cursor,devin-cli,devin-desktop,factory,grok,hermes,omp,openclaw,opencode,pi,qwen`. `devin` remains a legacy alias for `devin-cli`; `hermes-agent` maps to `hermes`; `qwen-code` maps to `qwen`; `pi-cli` and `pi_cli` map to `pi`; `oh-my-pi` and `ohmypi` map to `omp`; `openclaw-gateway` maps to `openclaw`. Defaults to `cursor` || `--level <level>` | Hook install level: `user` or `project` || `--user` | Use per-user endpoint paths. Enabled by default || `--system` | Use system endpoint paths and launch daemon |diff --git a/docs/cli/openclaw.mdx b/docs/cli/openclaw.mdxindex fe4280fe..6b1bf3e8 100644--- a/docs/cli/openclaw.mdx+++ b/docs/cli/openclaw.mdx@@ -7,6 +7,18 @@ description: "Set up OpenClaw Gateway OpenTelemetry export for Beacon"OpenClaw Gateway can export diagnostics through the `diagnostics-otel` plugin. Beacon can print a local OTLP/HTTP Gateway configuration and validate whether OpenClaw-derived events are arriving in the endpoint runtime log.+<Note>+**This is the gateway half of OpenClaw support, not the whole of it.** These commands cover OpenClaw's own OpenTelemetry export, which carries gateway traces and metrics — and, unless `captureContent` is explicitly enabled, no prompt, tool, or file content at all.++What the **agent** did is collected by a separate, Beacon-managed plugin:++```bash+beacon endpoint hooks install --harness openclaw+```++Both paths report under the same `openclaw_gateway` harness and are wanted together. See [OpenClaw Gateway](/runtimes/openclaw-gateway) for the plugin, the config key token usage needs, and what is deliberately not collected.+</Note>+```bash title="Command syntax"beacon endpoint integrations openclaw [command]```diff --git a/docs/cli/token-usage.mdx b/docs/cli/token-usage.mdxindex 12cf655b..d7cb5716 100644--- a/docs/cli/token-usage.mdx+++ b/docs/cli/token-usage.mdx@@ -45,6 +45,9 @@ Token coverage is not uniform, and the reason is almost always the runtime rathe| Pi | input, output, cache read, cache creation, reasoning | Reported (`cost_usd`) | Yes | Yes || Oh My Pi | input, output, cache read, cache creation, reasoning | Reported (`cost_usd`) | Yes | Yes || fx (Vercel Labs) | input, output, cache read, cache creation | Reported (`cost_usd`) | Yes | Yes |+| OpenClaw Gateway | input, output, cache read, cache creation | Not reported on the hook | Yes, per model response | Yes |++OpenClaw reports usage on its `llm_output` hook, which is a *conversation* hook -- OpenClaw withholds those from every non-bundled plugin until `plugins.entries.beacon-endpoint.hooks.allowConversationAccess` is set in its config. An OpenClaw endpoint collecting prompts, tools, commands and files while reporting no tokens at all is almost always that key, and `beacon endpoint hooks status --harness openclaw` says so. OpenClaw does compute a per-turn price, from an operator-configured cost table rather than from a provider report, so Asymptote does not record it as a reported cost. See [OpenClaw Gateway](/runtimes/openclaw-gateway).Cline reports usage once per task rather than per model call, because Beacon's rollups sum `gen_ai.usage` across events and reporting at both granularities would count every token twice. fx reports cumulative totals, which Beacon differences into per-turn deltas for the same reason.@@ -56,7 +59,6 @@ Cline reports usage once per task rather than per model call, because Beacon's r| GitHub Copilot CLI | As above || VS Code Copilot | As above || Factory Droid | As above |-| OpenClaw Gateway | As above || Grok Bot | Reaches Asymptote only through Cursor's server-side OpenTelemetry export, so usage arrives only if that export carries the semconv names || goose | goose's `chat` spans carry the full `gen_ai.usage.*` set, cache reads and writes included, under the exact semconv names -- that much is read out of the runtime rather than hoped for. What is conditional is whether it arrives: usage reaches Asymptote only over OTLP, so a goose endpoint with hooks installed and `beacon endpoint install --harness goose` never run is correctly silent rather than faulty. goose reports no cost. See [goose](/runtimes/goose) |diff --git a/docs/mdm/index.mdx b/docs/mdm/index.mdxindex d044570f..44d3a0ed 100644--- a/docs/mdm/index.mdx+++ b/docs/mdm/index.mdx@@ -86,7 +86,7 @@ Environment variables take precedence over MDM script parameters:| `BEACON_FALCON_CA_FILE` | Optional Falcon LogScale CA certificate path |<Note>- Gemini CLI telemetry is opt-in. Set `BEACON_ENDPOINT_HARNESSES=claude,codex,gemini` when the deployment should manage Gemini's local OTLP settings. Supported hook runtime installation is separate from the base system package because runtime hook configuration is per user or per project. Run hook helpers only when an interactive console user is present. Manage GitHub Copilot CLI's `COPILOT_OTEL_ENABLED=true` and `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318` launch environment through MDM or another customer-owned policy; do the same for Factory Droid's `OTEL_TELEMETRY_ENDPOINT`. Configure OpenClaw Gateway in OpenClaw and point its diagnostics OTLP/HTTP export at the Beacon collector.+ Gemini CLI telemetry is opt-in. Set `BEACON_ENDPOINT_HARNESSES=claude,codex,gemini` when the deployment should manage Gemini's local OTLP settings. Supported hook runtime installation is separate from the base system package because runtime hook configuration is per user or per project. Run hook helpers only when an interactive console user is present. Manage GitHub Copilot CLI's `COPILOT_OTEL_ENABLED=true` and `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318` launch environment through MDM or another customer-owned policy; do the same for Factory Droid's `OTEL_TELEMETRY_ENDPOINT`. For OpenClaw Gateway, install the managed plugin in the account the gateway runs as (`beacon endpoint hooks install --harness openclaw`) and grant `plugins.entries.beacon-endpoint.hooks.allowConversationAccess` in OpenClaw's own config so token usage is collected; Beacon never writes that config. Its separate gateway OTLP/HTTP export is configured in OpenClaw and pointed at the Beacon collector.</Note>## Uninstall and rollbackdiff --git a/docs/mdm/jamf.mdx b/docs/mdm/jamf.mdxindex e97b8463..73f6721f 100644--- a/docs/mdm/jamf.mdx+++ b/docs/mdm/jamf.mdx@@ -145,7 +145,7 @@ Suggested Smart Groups:- Runtime log writability is not `writable` or `creatable`.- Splunk HEC forwarding is `not_configured` when HEC export is required.-Use `/opt/beacon/jamf/scripts/install-cursor-hooks.sh` as a separate user-context policy for hook telemetry. Set `BEACON_HOOK_HARNESSES=antigravity,claude,cline,cursor,devin-cli,devin-desktop,factory,grok,hermes,opencode,qwen` when you want Antigravity CLI, Claude Code, Cline, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, Hermes Agent, OpenCode, and Qwen Code hook integrations. Hook configuration is per user and should run only when an interactive console user is present. Gemini CLI is configured through the endpoint harness list instead; add `gemini` to Jamf parameter 4, for example `claude,codex,gemini`. GitHub Copilot CLI is MDM-managed outside the Beacon harness list; configure `COPILOT_OTEL_ENABLED=true` and `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318` in Copilot's launch environment. OpenClaw Gateway is configured in OpenClaw, not through Jamf hook helpers.+Use `/opt/beacon/jamf/scripts/install-cursor-hooks.sh` as a separate user-context policy for hook telemetry. Set `BEACON_HOOK_HARNESSES=antigravity,claude,cline,cursor,devin-cli,devin-desktop,factory,grok,hermes,opencode,qwen` when you want Antigravity CLI, Claude Code, Cline, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, Hermes Agent, OpenCode, and Qwen Code hook integrations. Hook configuration is per user and should run only when an interactive console user is present. Gemini CLI is configured through the endpoint harness list instead; add `gemini` to Jamf parameter 4, for example `claude,codex,gemini`. GitHub Copilot CLI is MDM-managed outside the Beacon harness list; configure `COPILOT_OTEL_ENABLED=true` and `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318` in Copilot's launch environment. OpenClaw Gateway takes a managed plugin like the other hook runtimes, installed in the account the gateway runs as; add `openclaw` to `BEACON_HOOK_HARNESSES`. Its gateway OTLP export, and the `plugins.entries.beacon-endpoint.hooks.allowConversationAccess` key that token usage needs, live in OpenClaw's own config and are not written by Beacon.For Google Cloud Storage, the package includes`/opt/beacon/jamf/claude/gcs/{install-forwarder.sh,run-forwarder.sh,repair-hooks-and-forwarder.sh}`.@@ -189,7 +189,7 @@ Beacon-managed directories, then pass only its path throughsudo /opt/beacon/bin/beacon endpoint wazuh validate```- If validation succeeds but events remain stale, confirm the configured harnesses match the agent harnesses installed or configured for the device and that the local collector ports are not in use by another process. If GitHub Copilot CLI events are missing, confirm Copilot's launch environment includes `COPILOT_OTEL_ENABLED=true` and a localhost OTLP HTTP endpoint. If Cline, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, Hermes Agent, or OpenCode hook events are missing, confirm the separate user-context hook policy has run for the logged-in user. For OpenClaw Gateway, confirm the `diagnostics-otel` plugin is enabled and pointed at Beacon's OTLP HTTP receiver.+ If validation succeeds but events remain stale, confirm the configured harnesses match the agent harnesses installed or configured for the device and that the local collector ports are not in use by another process. If GitHub Copilot CLI events are missing, confirm Copilot's launch environment includes `COPILOT_OTEL_ENABLED=true` and a localhost OTLP HTTP endpoint. If Cline, Cursor, Devin CLI, Devin Desktop, Factory, Grok Build, Hermes Agent, or OpenCode hook events are missing, confirm the separate user-context hook policy has run for the logged-in user. For OpenClaw Gateway, confirm the Beacon plugin is present in `~/.openclaw/extensions/beacon-endpoint/` and that the gateway was reloaded, and — for the separate gateway export — that the `diagnostics-otel` plugin is enabled and pointed at Beacon's OTLP HTTP receiver.</Accordion><Accordion title="Agent inventory heartbeats are stale">System-mode inventory heartbeats are written by a scheduled root job,diff --git a/docs/runtimes/index.mdx b/docs/runtimes/index.mdxindex 7019b49e..8356c099 100644--- a/docs/runtimes/index.mdx+++ b/docs/runtimes/index.mdx@@ -51,7 +51,7 @@ Two rows in that table are not hook or OTLP integrations. [fx](/runtimes/vercel-|----------------|-----------------|--------------------|| [Claude Cowork](/runtimes/claude-cowork) | Admin-configured OTLP | Prompt, assistant response, approval, command, tool, file, MCP, session, model, token usage, and runtime-reported cost telemetry when emitted through Cowork OTLP || [Hermes Agent](/runtimes/hermes-agent) | Shell hooks | Prompt, observed tool, command, file, approval request and response, session lifecycle, and subagent stop telemetry |-| [OpenClaw Gateway](/runtimes/openclaw-gateway) | Gateway-configured OTLP/HTTP | OTLP logs, traces, and metrics from the Gateway diagnostics plugin |+| [OpenClaw Gateway](/runtimes/openclaw-gateway) | Managed plugin, plus gateway-configured OTLP/HTTP | Session lifecycle, prompts with the sender and chat channel, tool, command with exit code and output, file with diffs, MCP, compaction, subagent, and token usage telemetry from the plugin; gateway traces and metrics from OpenClaw's own diagnostics export. Approvals are not exposed by OpenClaw and are not synthesized |### Browser chat surfaces@@ -114,9 +114,9 @@ MDM assets, meaning Jamf Pro Extension Attributes, Fleet osquery queries, and Ri| fx (Vercel Labs) | Nothing to configure in fx. Schedule [`beacon endpoint fx sync`](/cli/endpoint-fx) in the logged-in user's context, or leave `--watch` running, so committed sessions keep reaching the runtime log. Nothing sweeps on its own. || GitHub Copilot CLI | Configure launch environment through MDM or customer policy: `COPILOT_OTEL_ENABLED=true` and `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318`. Asymptote validates the endpoint but does not edit shell profiles or launch environments. || Factory Droid | Configure launch environment with `OTEL_TELEMETRY_ENDPOINT=http://127.0.0.1:4318`. Asymptote discovers the runtime and validates the endpoint but does not edit shell profiles or launch environments. |-| OpenClaw Gateway | Configure OTLP in OpenClaw. Use [`beacon endpoint integrations openclaw`](/cli/openclaw) to print local Gateway settings and validate events. |+| OpenClaw Gateway | Install the managed plugin in the account the gateway runs as with `beacon endpoint hooks install --harness openclaw`, then grant `plugins.entries.beacon-endpoint.hooks.allowConversationAccess` in OpenClaw's own config so token usage is collected. For the gateway's OTLP export, use [`beacon endpoint integrations openclaw`](/cli/openclaw) to print local settings and validate events; Asymptote never writes OpenClaw's config. |-Install hooks separately in the logged-in user's context when you need richer hook telemetry. This applies to Antigravity CLI, Claude Code, Cline, Codex CLI session-context hooks, Cursor, Devin CLI, Devin Desktop, Factory Droid, Grok Build, Hermes Agent, goose, Muse Code, Oh My Pi, OpenCode, OpenHands, Pi, Qwen Code, and the optional VS Code hooks. fx is the exception with no hooks to install: schedule [`beacon endpoint fx sync`](/cli/endpoint-fx) instead.+Install hooks separately in the logged-in user's context when you need richer hook telemetry. This applies to Antigravity CLI, Claude Code, Cline, Codex CLI session-context hooks, Cursor, Devin CLI, Devin Desktop, Factory Droid, Grok Build, Hermes Agent, goose, Muse Code, Oh My Pi, OpenClaw Gateway, OpenCode, OpenHands, Pi, Qwen Code, and the optional VS Code hooks. fx is the exception with no hooks to install: schedule [`beacon endpoint fx sync`](/cli/endpoint-fx) instead.If a system collector is running while the CLI is reading the default per-user log, `beacon endpoint status` and the local dashboard surface a runtime-log source warning so you can tell where OTLP events are being written.diff --git a/docs/runtimes/openclaw-gateway.mdx b/docs/runtimes/openclaw-gateway.mdxindex 9419a744..25249859 100644--- a/docs/runtimes/openclaw-gateway.mdx+++ b/docs/runtimes/openclaw-gateway.mdx@@ -5,50 +5,281 @@ description: "Asymptote support details for OpenClaw Gateway endpoint telemetry"## Runtime overview-Asymptote supports OpenClaw Gateway through gateway-configured OTLP/HTTP export.+[OpenClaw](https://docs.openclaw.ai) is a self-hosted gateway that connects chat apps — Discord, Slack, Signal, Telegram, WhatsApp, iMessage, Matrix, Microsoft Teams and more — to AI coding agents. Asymptote supports it through **two** collection paths, and both are wanted on the same machine:++```bash+beacon endpoint hooks install --harness openclaw # the Beacon-managed plugin+beacon endpoint integrations openclaw print-config # OpenClaw's own OTLP export+```++`--harness openclaw-gateway` is also accepted and installs the same thing.++The two are not alternatives. The plugin reports what the **agent** did — sessions, prompts, tool calls, commands, files, MCP activity and token usage. OpenClaw's own `diagnostics-otel` export reports what the **gateway** did, as traces and metrics, and by OpenClaw's default carries no prompt, tool, or system-prompt content at all unless `captureContent` is explicitly enabled.++<Note>+**A gateway is not a single-user CLI, and the telemetry reflects that.** One OpenClaw process fans several people's chat accounts into one or more agents. Every event therefore carries the chat channel, the sender, the OpenClaw agent id and the per-turn run id under `raw`, so a command executed on a repository can be traced back to the person who asked for it and the app they asked from.+</Note>## Prerequisites-Before enabling OpenClaw Gateway telemetry, make sure:+Before enabling OpenClaw telemetry, make sure:++- OpenClaw Gateway is installed and you can edit its config.+- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist. The plugin path does not need the collector running; the OTLP path does.+- The gateway is restarted, or `openclaw plugins reload beacon-endpoint` is run, after installing or removing the plugin.++## Collection path 1: the Beacon-managed plugin++OpenClaw discovers a plugin as a **directory**, reading each child of its extensions directories and loading the entrypoint that directory's `package.json` declares. So Asymptote owns the directory name `beacon-endpoint` and never reads or writes any other plugin beside it.++| Scope | Directory | Covers |+|-------|-----------|--------|+| User | `~/.openclaw/extensions/beacon-endpoint/` | Every gateway run by this user |+| Project | `<workspace>/.openclaw/extensions/beacon-endpoint/` | Gateways whose workspace is that directory |++`$OPENCLAW_STATE_DIR` relocates the user-scope location, matching how OpenClaw resolves its own state directory. The workspace path has no override — OpenClaw joins the literal onto the gateway's workspace.++<Warning>+**Prefer the user scope.** OpenClaw resolves a workspace plugin root relative to the **gateway's** workspace, which for a daemonized gateway is wherever the service manager started it rather than the checkout you installed from. A user-scope install follows the gateway either way.+</Warning>++Three files are written, and all three are required — OpenClaw skips a directory missing either manifest during discovery and **reports nothing about it**:++| File | Purpose |+|------|---------|+| `beacon.js` | The plugin entry. Plain JavaScript, so no transpilation stands between OpenClaw and the plugin |+| `package.json` | Declares the entry under both `openclaw.extensions` and `openclaw.runtimeExtensions` |+| `openclaw.plugin.json` | The manifest OpenClaw reads before loading any plugin code, with `activation.onStartup` so session hooks register in time |++`beacon endpoint inventory` reports both scopes, so an install at either is visible.++### Registered hooks++OpenClaw publishes forty-one typed plugin hooks. Asymptote registers ten, and the exclusions are covered under [What Asymptote deliberately does not register](#what-asymptote-deliberately-does-not-register).++| Hook | Recorded as |+|------|-------------|+| `session_start` | `session.started`, with `resumedFrom` when the session has history behind it |+| `session_end` | `session.ended`, with the end reason and the next session id when one rotated |+| `message_received` | `prompt.submitted`, with the sender and the channel |+| `before_tool_call` | `tool.invoked` |+| `after_tool_call` | `command.executed`, `file.*`, `mcp.tool_invoked`, `tool.completed`, or `tool.failed` |+| `llm_output` | `token.usage` and `agent.message` |+| `before_compaction` / `after_compaction` | `session.compacting` / `session.compacted` |+| `subagent_spawned` / `subagent_ended` | `subagent.started` / `subagent.stopped` |++### The plugin never makes the gateway wait on a tool call++<Warning>+**OpenClaw registers `before_tool_call` fail-closed.** A handler that throws, or that exceeds its timeout, **blocks the tool call** — that is OpenClaw's default failure policy for this hook, not a misconfiguration.++Asymptote's handler therefore dispatches its work and returns **synchronously**, with no promise for OpenClaw to wait on, so telemetry cannot stop an agent from working even if the hook binary hangs or the disk is full.++The cost is ordering: a `tool.invoked` row can land in the log *after* the `tool.completed` row for the same call. That is fine, because ordering was never the join — `gen_ai.tool.call.id` is, and both halves carry it.+</Warning>++Every other handler resolves to `undefined`. OpenClaw reads a returned object on its modify-kind hooks as a request to change behaviour, so returning nothing is what keeps the plugin an observer.++### Asymptote owns one directory and nothing else++If `beacon.js` in that directory was not written by Asymptote — a `beacon-endpoint` plugin installed from ClawHub, say — both install and uninstall **refuse** rather than overwriting or deleting it.++Uninstall removes the three files **and the directory**, because a directory holding manifests and no entrypoint is a plugin OpenClaw tries to load and reports as broken. A file you put in there stops the directory removal rather than being deleted with Asymptote's.++## Collection path 2: OpenClaw's OpenTelemetry export++OpenClaw ships a `diagnostics-otel` plugin that exports OTLP logs, traces and metrics. It is configured **in OpenClaw**, not by `beacon endpoint install`:++```bash+beacon endpoint integrations openclaw print-config # the settings to paste into OpenClaw's config+beacon endpoint integrations openclaw status # whether OpenClaw-derived events have arrived+beacon endpoint integrations openclaw validate # fail if none have+```++This path carries gateway-level traces and metrics. It does **not** replace the plugin: without `captureContent` explicitly enabled it carries no prompt, response, tool-input, tool-output or system-prompt content, and OpenClaw documents that default deliberately.++By default Asymptote filters OpenClaw's operational metrics out of the runtime log as low-signal; `beacon endpoint install --include-runtime-metrics` keeps them.++## Your gateway config is read, never written++Asymptote does **not** edit `~/.openclaw/openclaw.json`. This is the one deliberate departure from how every other runtime is handled, and the reason is that OpenClaw's config is "JSON or JSON5" by its own documentation: JSON5 permits comments, trailing commas and unquoted keys, none of which survive a round trip through a JSON encoder. Rewriting it would silently strip your comments out of the file that configures every chat channel you run.++Instead, the installer reads that config and tells you what is missing. Two keys can matter:++<Warning>+**Token usage and agent messages need one config key.** OpenClaw withholds *conversation hooks* from every non-bundled plugin until you opt in, and `llm_output` is one of them. Without this key, the plugin collects sessions, prompts, tools, commands, files and MCP activity — and collects **no token usage and no agent messages**:++```json+{+ "plugins": {+ "entries": {+ "beacon-endpoint": {+ "enabled": true,+ "hooks": { "allowConversationAccess": true }+ }+ }+ }+}+```-- You can configure the OpenClaw Gateway `diagnostics-otel` plugin.-- `beacon endpoint install` has run so the local collector and runtime log path exist.-- You have run `beacon endpoint integrations openclaw print-config` to get the local OTLP/HTTP settings for Gateway.-- OpenClaw Gateway points at the same Asymptote collector and runtime log that you will inspect with `beacon` commands.-- `captureContent` is explicitly enabled in OpenClaw if you expect prompt content rather than metadata-only telemetry.+This is the failure mode that looks most like success, so `beacon endpoint hooks install` prints it and `beacon endpoint hooks status --harness openclaw` repeats it on every check.+</Warning>-## Collection path+If — and only if — your config already has a `plugins.allow` allowlist, `beacon-endpoint` has to be named in it or the plugin will not load at all. Asymptote says so when the key is present and stays silent when it is not: introducing an allowlist where none existed would deny every other plugin you run.-OpenClaw Gateway emits OTLP logs, traces, and metrics through the `diagnostics-otel` plugin. Asymptote prints local OTLP/HTTP Gateway config and validates whether OpenClaw-derived events have reached the endpoint runtime log.+A config Asymptote cannot parse produces no advice rather than a guess, which is the common case for JSON5.## Discovery and status-Asymptote validates OpenClaw Gateway support by scanning the endpoint runtime log for OpenClaw-derived events after Gateway diagnostics are configured.+```bash title="Show OpenClaw status on both paths"+beacon endpoint hooks status --harness openclaw+beacon endpoint integrations openclaw status+beacon endpoint discover --all+```-Use `beacon endpoint integrations openclaw status` to check whether OpenClaw events have been observed.+OpenClaw reports as the `openclaw_gateway` harness on **both** paths, so one gateway is one harness in any query that groups by `harness.name`. Plugin events carry `harness.collection_method=plugin` — Asymptote ships the plugin source OpenClaw loads, so its coverage is Asymptote's to fix rather than OpenClaw's to expose — while OTLP events carry `otlp`.-## Install or configuration support+Status checks the manifests as well as the plugin entry, because a directory OpenClaw skipped and a plugin that loaded and saw nothing look identical from the log alone.-OpenClaw Gateway is configured in OpenClaw, not by `beacon endpoint install`.+## Install or configuration support-Use `beacon endpoint integrations openclaw print-config` to print local Gateway OTLP settings, then configure OpenClaw Gateway with the `diagnostics-otel` plugin.+```bash+beacon endpoint hooks install --harness openclaw # ~/.openclaw/extensions/beacon-endpoint/+beacon endpoint hooks install --harness openclaw --level project # <workspace>/.openclaw/extensions/beacon-endpoint/+beacon endpoint hooks status --harness openclaw+beacon endpoint hooks uninstall --harness openclaw+```-OpenClaw Gateway is not hook-based.+`beacon endpoint install --harness openclaw` is **not** the command — OpenClaw's OTLP export lives in OpenClaw's own config, so Asymptote prints the settings rather than writing them. Running it says so and names both commands.## Telemetry coverage| Area | Support ||------|---------|-| Prompt telemetry | Disabled by default unless OpenClaw `captureContent` settings are explicitly enabled |-| Command, tool, and file telemetry | Supported for OTLP logs, traces, and metrics emitted by the Gateway diagnostics plugin |-| Local JSONL and dashboard | Supported after events reach the collector |-| MDM deployment | Supported for the endpoint agent. Gateway diagnostics configuration is managed in OpenClaw |+| Runtime discovery | Supported through the plugin directory at both scopes |+| Harness attribution | Supported. `openclaw`, `openclaw_gateway`, `open-claw` and related spellings normalize to `openclaw_gateway` |+| Plugin install, status, uninstall, and repair | Supported |+| OTLP export configuration | Printed, not written. It lives in OpenClaw's own config |+| Session lifecycle | Supported, including resumed sessions and the nine end reasons OpenClaw distinguishes |+| Prompts | Supported. `prompt.submitted` from the inbound chat message, with the sender and the channel |+| Tool use | Supported for both halves, correlated by `gen_ai.tool.call.id` |+| Commands | Supported. `command.executed` with the command line, **exit code and captured output** |+| File activity | Supported. `file.read`, `file.created` and `file.modified` with paths and diffs |+| MCP activity | Supported. Recognized from OpenClaw's `<server>__<tool>` naming, with the server and tool split out |+| Failed tools | Supported. `tool.failed` at high severity, with OpenClaw's error text |+| Token usage | Supported — **once `allowConversationAccess` is granted**. Input, output, cache reads and cache writes, plus the context budget |+| Agent messages | Supported on the same terms, from the assistant's response text |+| Compaction | Supported, including the session-id rotation a compaction can cause |+| Subagents | Supported. Started and stopped, with the child session key, its resolved model, and its outcome |+| Approval decisions | Not collected. See [Approvals and enforcement](#approvals-and-enforcement) |+| Reported cost | Not collected. See [Known gaps](#known-gaps) |+| Local JSONL and dashboard | Supported |+| MDM deployment | Supported for the endpoint agent. The plugin is installed in the account the gateway runs as |++### Tool taxonomy++| Tool | Recorded as |+|------|-------------|+| `exec` | `command.executed`, with the command line, exit code and captured output |+| `read` | `file.read` |+| `write` | `file.created`, with a diff of the new content |+| `edit` | `file.modified`, with a diff built from `oldText` and `newText` |+| `apply_patch` | One `file.modified` **per changed path**, with the patch retained once |+| `<server>__<tool>` | `mcp.tool_invoked`, with `mcp.server` and `mcp.tool` |+| `ls`, `process`, the `openclaw` family, and plugin-registered tools | `tool.completed` |++<Note>+**MCP calls are identified by their separator, and they have to be.** OpenClaw names a tool from an MCP server `<server>__<tool>` — no `mcp` anywhere in the name, no `mcp_*` argument, and nothing in the result saying where the tool came from. So the usual `mcp__server__tool` reader finds nothing, and a GitHub server's `github__create_issue` would land under `tool.completed` with no server attribution at all.++The Claude-style `mcp__server__tool` form is still recognized first, because OpenClaw's own Codex and Claude harness bridges mint it.+</Note>++A backgrounded `exec` reports `status: "running"` with a partial tail and no exit code. Asymptote records the command line and **no outcome** for it, rather than presenting a partial tail as the command's output.++### apply_patch, and why it needs both halves of the call++`apply_patch` takes the whole patch envelope as one opaque string, and OpenClaw derives its destination paths only on `before_tool_call`. The plugin therefore remembers those paths, keyed by OpenClaw's own tool call id, and attaches them to the completion — without which a completed patch would be a blob with no file rows, and every file-scoped detection matches on `file.path`.++Paths from a call the plugin never saw proposed are **dropped rather than guessed**: a patch event enriched with another call's paths would read as evidence that those files changed. Such a call is recorded as a completed tool carrying its patch text instead.++## Approvals and enforcement++**Asymptote records no approval decisions for OpenClaw, and does not synthesize any.**++OpenClaw genuinely does ask operators to approve tool calls, and exposes no hook reporting the answer: there is no `tool_approval_*` event in its catalog, and the only approval surface a plugin has is `before_tool_call`'s `requireApproval` result — a plugin *requesting* a prompt and being told its own outcome. Asymptote does not request approvals, so it never sees one. This is the same call already settled for [Cline](/runtimes/cline), [Pi](/runtimes/pi), [goose](/runtimes/goose), [OpenHands](/runtimes/openhands) and [Kiro](/runtimes/kiro).++<Warning>+**`approvalReviewOutcome` is not an approval.** An `exec` result carries `details.approvalReviewOutcome` with the values `approved`, `denied` and `reviewing`, alongside `approvalReviews[]` entries with a status and a rationale. OpenClaw's own type calls these **model-backed** approval reviews: an LLM judging the command, not a person deciding about it.++Recording one as `approval.allowed` would put a machine's opinion into the field every approval detection reads as a human decision. They stay in `raw` with the rest of the tool result, where they are still searchable and cannot be mistaken for consent.+</Warning>++Enforcement stays behind the optional, off-by-default policy provider seam (`BEACON_POLICY_PROVIDER`), which is inert unless it names an executable and fails open on any error.++## What Asymptote deliberately does not register++Some exclusions are about volume, and some are about what a telemetry plugin is allowed to be.++**Because registering them would give Asymptote power over your agent:**++- `before_prompt_build`, `agent_turn_prepare` and `heartbeat_prompt_contribution` are prompt **injection** hooks.+- `inbound_claim`, `before_dispatch` and `reply_dispatch` are claim hooks that can swallow a message before the agent sees it.+- `before_install` gates skill and plugin installation.+- `skill_proposal_evaluate` makes its handler a **voting evaluator** on whether a skill may be created.++Asymptote observes. A test asserts none of these is ever registered.++**Because they duplicate what is already collected, at much higher volume:**++- `llm_input` carries the full system prompt, the assembled prompt and the entire history array on **every model call**. `message_received` already carries what the person actually wrote, which is the prompt an investigation asks about.+- `agent_end` carries the whole `messages` array for the turn; its unique fields are a success flag and a duration.+- `model_call_started` and `model_call_ended` fire once per provider call — several per turn with a tool loop — and neither carries usage.+- The delivery hooks (`message_sending`, `message_sent`, `reply_payload_sending`) describe chat plumbing rather than agent action.++**Because they cannot work:**++- `tool_result_persist` and `before_message_write` are OpenClaw's two **synchronous** hooks. Promises are ignored with a warning, so a handler that spawns a process could not wait for it.++## Data handling++OpenClaw content is handled like every other runtime. Prompts, tool arguments, command lines, command output, paths and diffs are retained in local or customer-controlled logs, with local secret redaction and per-string limits applied before writing, and a hash and byte count on each content-bearing event. Events over the 64 KiB limit drop raw and retained content, preserve stable metadata, and set `field_truncated`.++The whole hook envelope is kept under `raw.openclaw`, which preserves the fields OpenClaw reports that the event schema has no column for — the channel, the sender, the agent id, the run id and the conversation key. It goes through the same redaction and limits as everything else and is the first thing dropped when an event exceeds the ceiling.++<Note>+**Chat messages are prompts here.** On a gateway the prompt is a message someone sent from Discord or WhatsApp, so retained prompt text includes chat content from those apps. That is the point of the integration, and it is worth knowing before you enable it on a shared gateway.+</Note>++## Known gaps++- **No approval decisions.** OpenClaw exposes no approval event to a plugin, and Asymptote does not synthesize one. Approval rules and dashboards show nothing for this runtime.+- **No reported cost.** OpenClaw computes a per-turn USD figure from an operator-configured cost table rather than from a provider report, and it is not on the `llm_output` hook. Asymptote records runtime-*reported* cost only, so `gen_ai.usage.cost_usd` stays empty rather than carrying a local estimate.+- **Token usage needs a config key.** See [Your gateway config is read, never written](#your-gateway-config-is-read-never-written). This is the most common reason an otherwise healthy OpenClaw install reports no tokens.+- **Tool ordering is not guaranteed.** `tool.invoked` can be written after the completion for the same call, because the `before_tool_call` handler never blocks. Correlate on `gen_ai.tool.call.id`.+- **No working directory outside a repository.** OpenClaw sets `workspaceDir` for runs that have one and omits it otherwise — a chat turn that never touched a repository genuinely has none. Asymptote leaves the field absent rather than falling back to the gateway daemon's own directory, which would attribute the work to wherever the service manager started it.+- **No per-call tool result for most tools.** `after_tool_call` carries a `result`, but only `exec` publishes a documented structure inside it. Other tools' results are kept under `raw` rather than promoted to schema fields.+- **Gateway lifecycle is not collected.** `gateway_start` and `gateway_stop` describe the service rather than agent activity, and the event schema has no action for them.## Deployment notes-Because OpenClaw Gateway configuration lives in OpenClaw, use Asymptote's OpenClaw integration commands to print the expected local OTLP/HTTP configuration and validate observed runtime events.+Plugins are discovered at gateway startup, so an install taken while the gateway is running takes effect after a reload. Restart the gateway, or run `openclaw plugins reload beacon-endpoint`.++Confirm status, then generate one event and check the log:++```bash+beacon endpoint hooks status --harness openclaw+grep '"name":"openclaw_gateway"' ~/.beacon/endpoint/logs/runtime.jsonl | tail -3+```++If OpenClaw plugin telemetry is missing:++- Confirm the gateway was reloaded after the install.+- Check `$OPENCLAW_STATE_DIR`: if it is set, the user-scope plugin is under that directory, not `~/.openclaw`.+- Confirm all three files are present in `~/.openclaw/extensions/beacon-endpoint/`. OpenClaw skips a directory missing a manifest without reporting it.+- Check `plugins.deny` and `plugins.entries.beacon-endpoint.enabled` in OpenClaw's config, and `plugins.allow` if you use one.+- Run `openclaw plugins inspect beacon-endpoint --runtime --json` to see what the gateway thinks of it.-If no OpenClaw events appear, confirm the Gateway diagnostics plugin is enabled, the OTLP endpoint points at the Asymptote collector, and the runtime log being inspected is the same log the collector writes.+If everything **except** token usage and agent messages is arriving, the plugin is working and `allowConversationAccess` is not set. `beacon endpoint hooks status --harness openclaw` says so.## Related@@ -57,6 +288,6 @@ If no OpenClaw events appear, confirm the Gateway diagnostics plugin is enabled,Return to the runtime support overview.</Card><Card title="OpenClaw commands" icon="plug" href="/cli/openclaw">- Print config, check status, and validate OpenClaw telemetry.+ Print config, check status, and validate the gateway's OTLP export.</Card></Columns>diff --git a/docs/security/data-inventory.mdx b/docs/security/data-inventory.mdxindex 428674ce..34622735 100644--- a/docs/security/data-inventory.mdx+++ b/docs/security/data-inventory.mdx@@ -24,7 +24,7 @@ Beacon writes normalized endpoint events only when supported runtimes provide te| Factory Droid | OTLP HTTP plus optional hooks | Session, prompt, write/edit/create tool use, stop, session-end, and available OTLP telemetry || Cursor | Native hooks | Prompt, tool, shell command, MCP-like, approval, and file edit telemetry || Claude Cowork | Admin-configured OTLP | Prompt and assistant response content; approvals; command, tool, file, and MCP activity; session lifecycle; model and token usage; runtime-reported cost; source user identifier and cloud origin when emitted through Cowork OTLP |-| OpenClaw Gateway | Gateway-configured OTLP/HTTP | OTLP logs, traces, and metrics from the Gateway diagnostics plugin |+| OpenClaw Gateway | Managed plugin, plus gateway-configured OTLP/HTTP | Prompts (the inbound chat message, with the sender and the chat channel), tool inputs and results, commands with exit code and output, file activity and diffs, MCP calls, agent response text, token usage, session and subagent lifecycle, and compaction; the verbatim hook envelope is retained under `raw.openclaw`. Gateway traces and metrics come separately from OpenClaw's own diagnostics export || [Claude.ai](/runtimes/claude-web) (`claude_web`) | Managed browser extension over local OTLP | Prompt text, assistant response text, request and response model, tool call id/name/arguments/results, conversation id, and token usage when the stream carries it, from the claude.ai chat stream || [ChatGPT](/runtimes/chatgpt-web) (`chatgpt_web`) | Managed browser extension over local OTLP | Prompt text, assistant response text, model, tool call activity, and conversation id from the chatgpt.com chat stream. ChatGPT web does not report token usage in its stream |