Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Install the OpenClaw plugin from `beacon endpoint hooks`

Claudef6fb689524c9
diff --git a/cli/beacon/cmd/endpoint_diagnostics.go b/cli/beacon/cmd/endpoint_diagnostics.go
index 4e38dbaa..4c52159f 100644
--- a/cli/beacon/cmd/endpoint_diagnostics.go
+++ b/cli/beacon/cmd/endpoint_diagnostics.go
@@ -957,7 +957,7 @@ var userScopeOnlyHookTargets = map[string]bool{
}
func allHookTargetsForLevel() []string {
- all := []string{"cursor", "codex", "vscode", "factory", "opencode", "openhands", "kiro", "cline", "pi", "omp", "grok", "qwen", "muse", "hermes", "devin-cli", "devin-desktop", "antigravity"}
+ all := []string{"cursor", "codex", "vscode", "factory", "opencode", "openhands", "kiro", "cline", "pi", "omp", "openclaw", "grok", "qwen", "muse", "hermes", "devin-cli", "devin-desktop", "antigravity"}
if endpointOpts.hookLevel != "project" {
return all
}
@@ -1014,6 +1014,9 @@ func hookStatusesWithConfig(targets []string, cfg endpointconfig.Config) map[str
case "omp":
status := endpointhooks.OmpHookStatus(endpointhooks.OmpOptions{Level: endpointhooks.Level(endpointOpts.hookLevel), LogPath: cfg.LogPath, UserMode: cfg.UserMode})
statuses[name] = hookTargetResult{Target: name, Status: targetStatus(status.Installed), Installed: status.Installed, Message: status.Message, Path: status.ExtensionPath, Raw: status}
+ case "openclaw":
+ status := endpointhooks.OpenClawHookStatus(endpointhooks.OpenClawOptions{Level: endpointhooks.Level(endpointOpts.hookLevel), LogPath: cfg.LogPath, UserMode: cfg.UserMode})
+ statuses[name] = hookTargetResult{Target: name, Status: targetStatus(status.Installed), Installed: status.Installed, Message: status.Message, Path: status.PluginPath, Raw: status}
case "grok":
status := endpointhooks.GrokHookStatus(endpointhooks.GrokOptions{Level: endpointhooks.Level(endpointOpts.hookLevel), LogPath: cfg.LogPath, UserMode: cfg.UserMode})
statuses[name] = hookTargetResult{Target: name, Status: targetStatus(status.Installed), Installed: status.Installed, Message: status.Message, Path: status.HooksPath, Raw: status}
diff --git a/cli/beacon/cmd/endpoint_hooks.go b/cli/beacon/cmd/endpoint_hooks.go
index b5ac779d..c354fde0 100644
--- a/cli/beacon/cmd/endpoint_hooks.go
+++ b/cli/beacon/cmd/endpoint_hooks.go
@@ -170,6 +170,30 @@ func installEndpointHookTarget(name string, cfg endpointconfig.Config) error {
// checkout, and the operator's other Oh My Pi sessions stay uninstrumented.
fmt.Println("Project-level Oh My Pi extensions cover only this working directory; a user-level install follows the operator across checkouts.")
}
+ case "openclaw":
+ status, err := endpointhooks.InstallOpenClaw(endpointhooks.OpenClawOptions{
+ Level: endpointhooks.Level(endpointOpts.hookLevel),
+ LogPath: cfg.LogPath,
+ UserMode: cfg.UserMode,
+ })
+ if err != nil {
+ return err
+ }
+ fmt.Printf("OpenClaw plugin installed: %s\n", status.PluginPath)
+ if endpointhooks.Level(endpointOpts.hookLevel) == endpointhooks.LevelProject {
+ // OpenClaw reads a workspace plugin root relative to the gateway's working directory,
+ // which for a daemonized gateway is wherever the service manager started it rather
+ // than the checkout the operator is thinking of. A user-level install follows the
+ // gateway regardless, which is why it is the default.
+ fmt.Println("Project-level OpenClaw plugins are discovered relative to the gateway's workspace, not the directory you install from; a user-level install follows the gateway.")
+ }
+ // OpenClaw gates conversation hooks behind a config key Beacon does not write, and an
+ // allowlisted config has to name the plugin. Printed at install time because the symptom
+ // otherwise is partial telemetry that looks like working telemetry.
+ for _, advice := range status.ConfigAdvice {
+ fmt.Println(advice)
+ }
+ fmt.Println("Restart the gateway, or run `openclaw plugins reload beacon-endpoint`, for OpenClaw to pick the plugin up.")
case "grok":
status, err := endpointhooks.InstallGrok(endpointhooks.GrokOptions{
Level: endpointhooks.Level(endpointOpts.hookLevel),
@@ -410,6 +434,16 @@ func uninstallEndpointHookTarget(name string, cfg endpointconfig.Config) error {
return err
}
fmt.Println(status.Message)
+ case "openclaw":
+ status, err := endpointhooks.UninstallOpenClaw(endpointhooks.OpenClawOptions{
+ Level: endpointhooks.Level(endpointOpts.hookLevel),
+ LogPath: cfg.LogPath,
+ UserMode: cfg.UserMode,
+ })
+ if err != nil {
+ return err
+ }
+ fmt.Println(status.Message)
case "grok":
status, err := endpointhooks.UninstallGrok(endpointhooks.GrokOptions{
Level: endpointhooks.Level(endpointOpts.hookLevel),
@@ -566,6 +600,12 @@ func runEndpointHooksStatus(cmd *cobra.Command, args []string) error {
LogPath: cfg.LogPath,
UserMode: cfg.UserMode,
})
+ case "openclaw":
+ statuses["openclaw"] = endpointhooks.OpenClawHookStatus(endpointhooks.OpenClawOptions{
+ Level: endpointhooks.Level(endpointOpts.hookLevel),
+ LogPath: cfg.LogPath,
+ UserMode: cfg.UserMode,
+ })
case "grok":
statuses["grok"] = endpointhooks.GrokHookStatus(endpointhooks.GrokOptions{
Level: endpointhooks.Level(endpointOpts.hookLevel),
@@ -660,6 +700,16 @@ func runEndpointHooksStatus(cmd *cobra.Command, args []string) error {
status := statuses["omp"].(endpointhooks.OmpStatus)
fmt.Printf("Oh My Pi extension: installed=%t path=%s\n", status.Installed, status.ExtensionPath)
fmt.Println(status.Message)
+ case "openclaw":
+ status := statuses["openclaw"].(endpointhooks.OpenClawStatus)
+ fmt.Printf("OpenClaw plugin: installed=%t path=%s\n", status.Installed, status.PluginPath)
+ fmt.Println(status.Message)
+ // An installed plugin with conversation access withheld collects everything except
+ // tokens and agent messages, which reads as working until somebody looks for a token
+ // count. Surfaced on every status check rather than only at install.
+ for _, advice := range status.ConfigAdvice {
+ fmt.Println(advice)
+ }
case "grok":
status := statuses["grok"].(endpointhooks.GrokStatus)
fmt.Printf("Grok hooks: installed=%t path=%s\n", status.Installed, status.HooksPath)
diff --git a/cli/beacon/cmd/endpoint_hooks_repair.go b/cli/beacon/cmd/endpoint_hooks_repair.go
index b40e3657..76ee8274 100644
--- a/cli/beacon/cmd/endpoint_hooks_repair.go
+++ b/cli/beacon/cmd/endpoint_hooks_repair.go
@@ -148,7 +148,7 @@ func installedHookTargetsForUser(homeDir, logPath string) ([]string, error) {
}
func repairTargetOrder() []string {
- return []string{"claude", "codex", "cursor", "vscode", "factory", "opencode", "openhands", "kiro", "cline", "pi", "omp", "grok", "qwen", "muse", "hermes", "devin-cli", "devin-desktop", "antigravity"}
+ return []string{"claude", "codex", "cursor", "vscode", "factory", "opencode", "openhands", "kiro", "cline", "pi", "omp", "openclaw", "grok", "qwen", "muse", "hermes", "devin-cli", "devin-desktop", "antigravity"}
}
// withUserHome runs fn as if it were executing inside another user's profile.
diff --git a/cli/beacon/cmd/endpoint_targets.go b/cli/beacon/cmd/endpoint_targets.go
index 91f74bbe..76da0889 100644
--- a/cli/beacon/cmd/endpoint_targets.go
+++ b/cli/beacon/cmd/endpoint_targets.go
@@ -71,6 +71,19 @@ var harnessTargets = []harnessTarget{
// people say it; Kiro's own documentation does not, which is why it is an alias and not the
// name.
{name: "kiro", endpointKind: endpointTargetHook, endpointAliases: []string{"kiro", "kiro-ide", "kiro-cli", "kiro-code"}, hookAliases: []string{"kiro", "kiro-ide", "kiro-cli", "kiro-code"}},
+ // OpenClaw Gateway. One row, and it is the plugin row: `--harness openclaw` installs the
+ // Beacon-managed plugin, which is the path that collects the agent's work. The gateway's other
+ // surface, its own diagnostics-otel plugin, is configured inside OpenClaw rather than by
+ // Beacon and has its own commands under `beacon endpoint integrations openclaw`, so it is not
+ // an endpoint target here.
+ //
+ // "openclaw-gateway" and "openclaw_gateway" both normalize to "openclaw-gateway" through
+ // normalizeHarnessKey, so the two spellings need one alias between them; it is accepted
+ // because `openclaw_gateway` is the canonical harness name events are written under, and a row
+ // read out of the runtime log and passed back to --harness should resolve to the runtime it
+ // names. "claw" is deliberately not an alias: it is short enough to collide with something
+ // else later, and nothing calls the product that.
+ {name: "openclaw", endpointKind: endpointTargetHook, endpointAliases: []string{"openclaw", "openclaw-gateway"}, hookAliases: []string{"openclaw", "openclaw-gateway"}},
{name: "grok", endpointKind: endpointTargetHook, endpointAliases: []string{"grok"}, hookAliases: []string{"grok"}},
// "qwen-code" and "qwen_code" both normalize to "qwen-code" through normalizeHarnessKey, so the
// two spellings need one alias between them. "qwen-cli" is not accepted: the product is Qwen
diff --git a/cli/beacon/internal/endpoint/harness/harness.go b/cli/beacon/internal/endpoint/harness/harness.go
index f7c59bcb..45652b62 100644
--- a/cli/beacon/internal/endpoint/harness/harness.go
+++ b/cli/beacon/internal/endpoint/harness/harness.go
@@ -59,6 +59,7 @@ func DiscoverAll() []Harness {
DiscoverCline(),
DiscoverPi(),
DiscoverOmp(),
+ DiscoverOpenClaw(),
DiscoverFx(),
DiscoverQwen(),
DiscoverHermes(),
diff --git a/cli/beacon/internal/endpoint/harness/openclaw.go b/cli/beacon/internal/endpoint/harness/openclaw.go
new file mode 100644
index 00000000..7145cdcb
--- /dev/null
+++ b/cli/beacon/internal/endpoint/harness/openclaw.go
@@ -0,0 +1,82 @@
+package harness
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks"
+)
+
+// DiscoverOpenClaw reports whether OpenClaw Gateway is present and whether Beacon is observing it.
+//
+// Its capability is "plugin": the plugin path is what collects the agent's work, and it is the one
+// `beacon endpoint hooks install --harness openclaw` writes. OpenClaw also has an OTLP surface --
+// its own `diagnostics-otel` plugin, configured through `beacon endpoint integrations openclaw` --
+// but that one is set up inside OpenClaw rather than by Beacon, carries gateway traces and metrics
+// rather than agent actions, and by OpenClaw's default carries no content at all. Reporting the
+// capability that Beacon installs is what makes `endpoint discover` answer the question an
+// operator is actually asking.
+func DiscoverOpenClaw() Harness {
+ h := Harness{Name: "openclaw", DisplayName: "OpenClaw Gateway", Capability: "plugin"}
+ detectExecutable(&h, "openclaw")
+
+ // A missing home directory leaves the config path empty rather than resolving to a relative
+ // path like ".openclaw/extensions/beacon-endpoint/beacon.js", which would make discovery
+ // report on whatever happens to sit under the current working directory.
+ entryPath, err := hooks.OpenClawEntryPath(hooks.LevelUser)
+ if err != nil {
+ h.TelemetryStatus = TelemetryMissing
+ h.Message = "OpenClaw plugin directory could not be resolved: " + err.Error()
+ return h
+ }
+ h.ConfigPath = entryPath
+
+ // OpenClaw installed through npm, Docker, or a service manager that this process did not
+ // inherit on PATH is still detectable by its state directory -- and a gateway is more likely
+ // than most runtimes to be running as a daemon under another account's PATH. Treating the
+ // directory as evidence keeps `endpoint discover` from reporting "not detected" for a gateway
+ // the operator is actively running, the same fallback the Pi, Oh My Pi, opencode, Cursor and
+ // Hermes probes make for the same reason.
+ //
+ // The directory checked is the extensions root the resolved entry lives under, two levels up
+ // from the entry file, so an OPENCLAW_STATE_DIR override is detected where it actually is
+ // rather than being missed at the default location.
+ if !h.Detected && dirExists(filepath.Dir(filepath.Dir(entryPath))) {
+ h.Detected = true
+ }
+
+ h.TelemetryStatus, h.Message = openClawStatus(entryPath)
+ return h
+}
+
+// openClawStatus classifies the plugin directory holding entryPath.
+//
+// The middle case is the one worth spelling out: an entry that exists without Beacon's marker is
+// somebody else's plugin occupying the `beacon-endpoint` id, so it is reported as disabled rather
+// than enabled. Reporting it as enabled would claim telemetry Beacon is not collecting, and
+// install refuses to overwrite the same file for the same reason.
+//
+// A directory missing a manifest is reported as disabled too, and this is the failure this probe
+// exists to catch. OpenClaw skips such a directory during discovery and says nothing about it, so
+// a plugin that never loaded is indistinguishable from one that loaded and saw no activity --
+// unless something looks at the directory.
+func openClawStatus(entryPath string) (TelemetryStatus, string) {
+ data, err := os.ReadFile(entryPath)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return TelemetryMissing, "Beacon OpenClaw plugin was not found"
+ }
+ return TelemetryMissing, err.Error()
+ }
+ if !strings.Contains(string(data), hooks.OpenClawManagedPluginMarker) {
+ return TelemetryDisabled, "OpenClaw plugin entry exists but Beacon endpoint plugin was not found"
+ }
+ dir := filepath.Dir(entryPath)
+ for _, name := range []string{"package.json", "openclaw.plugin.json"} {
+ if _, err := os.Stat(filepath.Join(dir, name)); err != nil {
+ return TelemetryDisabled, "Beacon OpenClaw plugin is missing " + name + ", so OpenClaw will not load it"
+ }
+ }
+ return TelemetryEnabled, "Beacon OpenClaw plugin is configured"
+}
diff --git a/cli/beacon/internal/endpoint/hooks/openclaw.go b/cli/beacon/internal/endpoint/hooks/openclaw.go
new file mode 100644
index 00000000..8e7f6fa9
--- /dev/null
+++ b/cli/beacon/internal/endpoint/hooks/openclaw.go
@@ -0,0 +1,433 @@
+package hooks
+
+import (
+ "encoding/json"
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+
+ openclawplugin "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks/assets/openclaw"
+)
+
+// OpenClaw Gateway is integrated as a Beacon-managed plugin, the Cline and Pi-family shape, with
+// one structural difference: OpenClaw discovers a plugin as a *directory* rather than as a file.
+//
+// A plugin root is a directory holding `package.json`, `openclaw.plugin.json`, and the entrypoint
+// the first of those declares. OpenClaw scans the immediate children of its extensions directories
+// and reads each child's manifests, so Beacon owns the directory `beacon-endpoint` rather than a
+// filename inside a directory somebody else also writes to -- the goose arrangement, for the same
+// reason.
+//
+// The gateway also collects over OTLP, through OpenClaw's own `diagnostics-otel` plugin and
+// `beacon endpoint integrations openclaw`. The two paths are complementary rather than
+// alternatives: OTLP carries gateway-level traces and metrics, and by OpenClaw's default carries
+// no prompt, tool, or file content at all, while this path carries the agent's actual work.
+const (
+ // openClawPlatform is the `--platform` value written into the hook invocation.
+ openClawPlatform = "openclaw"
+
+ // openClawPluginID is the directory Beacon owns and the id both manifests declare.
+ //
+ // It is also the id an operator addresses the plugin by -- `openclaw plugins enable
+ // beacon-endpoint`, `plugins.entries.beacon-endpoint` in the config -- so it is a contract with
+ // the operator's config file, not just a directory name. A test asserts the manifests agree
+ // with this constant.
+ openClawPluginID = "beacon-endpoint"
+
+ // openClawEntryFileName is the plugin entrypoint, declared by package.json.
+ openClawEntryFileName = "beacon.js"
+
+ // openClawPackageFileName and openClawManifestFileName are the two manifests OpenClaw reads
+ // before it loads any plugin code. A directory missing either is not a plugin, and OpenClaw
+ // skips it during discovery without reporting anything.
+ openClawPackageFileName = "package.json"
+ openClawManifestFileName = "openclaw.plugin.json"
+
+ // OpenClawManagedPluginMarker identifies a plugin entry as one Beacon wrote.
+ //
+ // The version suffix is part of the contract with the plugin source. Bump it when the plugin's
+ // behavior changes in a way that makes an older installed copy wrong, which is what lets a
+ // repair recognize a stale file rather than leave it in place. Exported for the same reason
+ // the Pi-family markers are: the harness probe and the inventory scanner both read it.
+ OpenClawManagedPluginMarker = "beacon-managed-openclaw-plugin:v1"
+
+ // openClawStateDirName is OpenClaw's state directory under the home directory.
+ openClawStateDirName = ".openclaw"
+
+ // openClawStateDirEnv relocates that state directory outright. OpenClaw reads it itself, so an
+ // install performed from inside a shell that sets it lands where that gateway actually looks.
+ openClawStateDirEnv = "OPENCLAW_STATE_DIR"
+
+ // openClawConfigPathEnv names the config file directly, overriding the state directory for
+ // that one file. Only read for the advisory config inspection below -- Beacon never writes it.
+ openClawConfigPathEnv = "OPENCLAW_CONFIG_PATH"
+
+ // openClawConfigFileName is the config OpenClaw writes by default. Read-only here; see
+ // OpenClawConfigAdvice.
+ openClawConfigFileName = "openclaw.json"
+)
+
+type OpenClawOptions struct {
+ Level Level
+ LogPath string
+ UserMode bool
+}
+
+type OpenClawStatus struct {
+ Installed bool `json:"installed"`
+ BinaryPath string `json:"binary_path,omitempty"`
+ PluginPath string `json:"plugin_path,omitempty"`
+ Message string `json:"message,omitempty"`
+ // ConfigAdvice is what the operator still has to do in OpenClaw's own config, if anything. It
+ // is advice rather than an action because Beacon does not write that file; see
+ // OpenClawConfigAdvice.
+ ConfigAdvice []string `json:"config_advice,omitempty"`
+}
+
+var openClawRuntime = hookRuntime{
+ displayName: "OpenClaw Gateway",
+ configPath: OpenClawEntryPath,
+ install: installOpenClawPlugin,
+ uninstall: removeOpenClawPlugin,
+ isInstalled: openClawInstalledAt,
+}
+
+func InstallOpenClaw(opts OpenClawOptions) (OpenClawStatus, error) {
+ status, err := installRuntimeHooks(openClawRuntime, RuntimeOptions(opts))
+ if err != nil {
+ return OpenClawStatus{}, err
+ }
+ return openClawStatusFromRuntime(status), nil
+}
+
+func UninstallOpenClaw(opts OpenClawOptions) (OpenClawStatus, error) {
+ status, err := uninstallRuntimeHooks(openClawRuntime, RuntimeOptions(opts))
+ if err != nil {
+ return OpenClawStatus{}, err
+ }
+ // Advice describes what is still missing for collection to work, which is meaningless once the
+ // plugin is gone -- and printing "add this to your config" after an uninstall would read as an
+ // instruction to re-enable what was just removed.
+ out := openClawStatusFromRuntime(status)
+ out.ConfigAdvice = nil
+ return out, nil
+}
+
+func OpenClawHookStatus(opts OpenClawOptions) OpenClawStatus {
+ return openClawStatusFromRuntime(runtimeHookStatus(openClawRuntime, RuntimeOptions(opts)))
+}
+
+func IsOpenClawInstalled(opts OpenClawOptions) bool {
+ return isRuntimeInstalled(openClawRuntime, RuntimeOptions(opts))
+}
+
+// openClawStatusFromRuntime reports installed only when the plugin can actually reach the hook
+// binary, and attaches whatever the operator still owes OpenClaw's config.
+func openClawStatusFromRuntime(status runtimeStatus) OpenClawStatus {
+ status = openClawReachableStatus(status)
+ out := OpenClawStatus{
+ Installed: status.Installed,
+ BinaryPath: status.BinaryPath,
+ PluginPath: filepath.Dir(status.ConfigPath),
+ Message: status.Message,
+ }
+ if status.Installed {
+ out.ConfigAdvice = OpenClawConfigAdvice()
+ }
+ return out
+}
+
+// openClawReachableStatus downgrades an "installed" verdict the directory on disk does not support.
+//
+// The marker on the entry is not enough. A plugin directory survives a Beacon uninstall, a
+// partially applied update, or a home directory restored onto a machine where the binary lives
+// elsewhere; in each case OpenClaw loads a plugin that spawns nothing, and reporting that as
+// installed tells an operator telemetry is being collected when none is. The manifests are checked
+// too, because OpenClaw skips a directory missing either one during discovery and says nothing
+// about it -- a plugin that never loads looks exactly like a plugin that loaded and saw nothing.
+func openClawReachableStatus(status runtimeStatus) runtimeStatus {
+ if !status.Installed {
+ return status
+ }
+ dir := filepath.Dir(status.ConfigPath)
+ if status.BinaryPath == "" {
+ return status
+ }
+ if _, err := os.Stat(status.BinaryPath); err != nil {
+ status.Installed = false
+ status.Message = fmt.Sprintf("OpenClaw plugin is installed, but Beacon hook binary is missing at %s",
+ status.BinaryPath)
+ return status
+ }
+ for _, name := range []string{openClawPackageFileName, openClawManifestFileName} {
+ if _, err := os.Stat(filepath.Join(dir, name)); err != nil {
+ status.Installed = false
+ status.Message = fmt.Sprintf("OpenClaw plugin at %s is missing %s, so OpenClaw will not load it",
+ dir, name)
+ return status
+ }
+ }
+ data, err := os.ReadFile(status.ConfigPath)
+ if err != nil || !extensionReferencesBinary(string(data), status.BinaryPath) ||
+ strings.Contains(string(data), "__BEACON_") {
+ status.Installed = false
+ status.Message = fmt.Sprintf("OpenClaw plugin at %s does not reference the active Beacon hook binary",
+ status.ConfigPath)
+ }
+ return status
+}
+
+// installOpenClawPlugin writes the three files that make a directory an OpenClaw plugin.
+//
+// path is the entrypoint; the manifests go beside it. The refusal is keyed on the entry rather
+// than on the directory so a directory Beacon created and an operator later edited by hand is
+// still recognised as Beacon's, while a `beacon-endpoint` plugin somebody else installed from
+// ClawHub is not overwritten.
+func installOpenClawPlugin(path, binaryPath, logPath, configPath string) error {
+ if existing, err := os.ReadFile(path); err == nil {
+ if !strings.Contains(string(existing), OpenClawManagedPluginMarker) {
+ return fmt.Errorf("refusing to overwrite unmanaged OpenClaw plugin at %s", path)
+ }
+ } else if !os.IsNotExist(err) {
+ return err
+ }
+ entry, err := renderOpenClawEntry(binaryPath, logPath, configPath)
+ if err != nil {
+ return err
+ }
+ dir := filepath.Dir(path)
+ if err := os.MkdirAll(dir, 0755); err != nil {
+ return err
+ }
+ // The manifests first, then the entry. OpenClaw's scan reads the manifests before it loads the
+ // entry, so writing them last would leave a window in which a scan finds a directory it treats
+ // as a broken plugin. Writing the entry last also makes the marker check above the last thing
+ // to become true, so a half-written install is never reported as installed.
+ for _, file := range []struct {
+ name string
+ content string
+ }{
+ {openClawPackageFileName, openclawplugin.PackageManifest},
+ {openClawManifestFileName, openclawplugin.PluginManifest},
+ } {
+ if err := os.WriteFile(filepath.Join(dir, file.name), []byte(file.content), 0644); err != nil {
+ return err
+ }
+ }
+ return os.WriteFile(path, []byte(entry), 0644)
+}
+
+// renderOpenClawEntry substitutes the hook invocation and the marker into the plugin source.
+//
+// Deliberately the same substitution managedExtension.render performs, spelled out here rather
+// than shared, because that type models a runtime whose whole install is one file and this one is
+// not. The argv goes in as a JSON array rather than a command line because the plugin spawns the
+// binary directly, which removes the shell -- and with it the per-shell quoting problem
+// endpointCommandPrefix documents -- from a gateway that runs on Windows as readily as on macOS.
+func renderOpenClawEntry(binaryPath, logPath, configPath string) (string, error) {
+ args := append(endpointCommandArgs(openClawPlatform, binaryPath, logPath, configPath), openClawPlatform+"-event")
+ argv, err := json.Marshal(args)
+ if err != nil {
+ return "", err
+ }
+ source := strings.ReplaceAll(openclawplugin.Template, managedMarkerPlaceholder, OpenClawManagedPluginMarker)
+ if !strings.Contains(source, argvPlaceholder) {
+ return "", fmt.Errorf("OpenClaw plugin template is missing the %s placeholder", argvPlaceholder)
+ }
+ source = strings.ReplaceAll(source, argvPlaceholder, string(argv))
+ if strings.Contains(source, "__BEACON_") {
+ return "", fmt.Errorf("OpenClaw plugin template contains unresolved Beacon placeholders")
+ }
+ return source, nil
+}
+
+// removeOpenClawPlugin deletes the plugin directory, and only one Beacon wrote.
+//
+// The whole directory rather than the entry alone: a directory holding two manifests and no
+// entrypoint is a plugin OpenClaw tries to load and cannot, which it reports as a broken plugin
+// rather than as an absent one. Removal is file by file and then the directory, so an operator's
+// own file dropped in there stops the rmdir rather than being deleted with it.
+func removeOpenClawPlugin(path string) (bool, error) {
+ data, err := os.ReadFile(path)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return false, nil
+ }
+ return false, err
+ }
+ if !strings.Contains(string(data), OpenClawManagedPluginMarker) {
+ return false, nil
+ }
+ dir := filepath.Dir(path)
+ for _, name := range []string{openClawEntryFileName, openClawPackageFileName, openClawManifestFileName} {
+ if err := os.Remove(filepath.Join(dir, name)); err != nil && !os.IsNotExist(err) {
+ return false, err
+ }
+ }
+ // Fails harmlessly when the operator left something else in there, which is the intended
+ // outcome: the plugin is gone either way, and their file is not.
+ _ = os.Remove(dir)
+ return true, nil
+}
+
+func openClawInstalledAt(path string) bool {
+ data, err := os.ReadFile(path)
+ if err != nil {
+ return false
+ }
+ return strings.Contains(string(data), OpenClawManagedPluginMarker)
+}
+
+// OpenClawEntryPath returns the plugin entrypoint Beacon manages for a given install level.
+func OpenClawEntryPath(level Level) (string, error) {
+ home, err := os.UserHomeDir()
+ if err != nil {
+ // Only the user level needs a home directory. Failing here for a project install would
+ // refuse a path that does not depend on the value that could not be read.
+ if level == LevelProject {
+ return OpenClawEntryPathForHome("", level)
+ }
+ return "", err
+ }
+ return OpenClawEntryPathForHome(home, level)
+}
+
+// OpenClawEntryPathForHome is OpenClawEntryPath against a caller-supplied home directory.
+//
+// Exported for inventory, which scans a home directory it was handed rather than the process's own
+// -- a scan of another user's tree, or of a fixture. Sharing the resolution rather than rebuilding
+// the path there is what keeps inventory from reporting on a file the installer does not write,
+// since OPENCLAW_STATE_DIR moves it.
+func OpenClawEntryPathForHome(home string, level Level) (string, error) {
+ dir, err := openClawPluginDir(home, level)
+ if err != nil {
+ return "", err
+ }
+ return filepath.Join(dir, openClawEntryFileName), nil
+}
+
+// openClawPluginDir resolves the plugin root OpenClaw will discover.
+//
+// Two scopes, resolved asymmetrically because OpenClaw resolves them that way. Its global root is
+// the extensions directory under the state directory -- `~/.openclaw/extensions` -- which
+// OPENCLAW_STATE_DIR replaces outright. Its workspace root is `<workspace>/.openclaw/extensions`,
+// with no environment override: the runtime joins the literal onto the working directory.
+//
+// Which one wins when both exist is OpenClaw's business and it is not symmetric either: a
+// workspace copy does not shadow a bundled plugin, and `plugins.load.paths` outranks both. That
+// does not affect Beacon, whose plugin id collides with nothing shipped, but it is why a project
+// install is not simply "the same thing, closer".
+func openClawPluginDir(home string, level Level) (string, error) {
+ switch level {
+ case "", LevelUser:
+ if stateDir := strings.TrimSpace(os.Getenv(openClawStateDirEnv)); stateDir != "" {
+ return filepath.Join(stateDir, "extensions", openClawPluginID), nil
+ }
+ if home == "" {
+ return "", fmt.Errorf("home directory is required to resolve the OpenClaw plugin path")
+ }
+ return filepath.Join(home, openClawStateDirName, "extensions", openClawPluginID), nil
+ case LevelProject:
+ cwd, err := os.Getwd()
+ if err != nil {
+ return "", err
+ }
+ return filepath.Join(cwd, openClawStateDirName, "extensions", openClawPluginID), nil
+ default:
+ return "", fmt.Errorf("unknown hook level %q", level)
+ }
+}
+
+// OpenClawConfigAdvice reports what the operator still owes OpenClaw's own config, if anything.
+//
+// Beacon does not write that file, and the reason is worth stating because every other runtime
+// Beacon supports gets its settings merged. OpenClaw's config is "JSON or JSON5" by its own
+// documentation, under either of two filenames, and JSON5 permits comments, trailing commas and
+// unquoted keys -- none of which survive a round trip through a Go JSON encoder. Rewriting an
+// operator's gateway config would silently strip their comments and reformat a file that
+// configures every chat channel they run. A plugin directory Beacon owns outright is a footprint
+// worth taking; their gateway config is not.
+//
+// So this reads the config and says what is missing, and `beacon endpoint hooks install` prints
+// it. Two things can be missing:
+//
+// - `plugins.entries.beacon-endpoint.hooks.allowConversationAccess`. OpenClaw requires every
+// non-bundled plugin to opt in explicitly before it will register a conversation hook, and
+// `llm_output` is one. Without it the plugin still collects sessions, prompts, tools,
+// commands, files and MCP activity, and collects no token usage and no agent messages. It is
+// advisory rather than fatal for that reason.
+// - `plugins.allow`. An operator using an allowlist has to name this plugin in it. Beacon only
+// mentions it when the key is already present: an allowlist introduced where none existed
+// would deny every other plugin the operator runs, which is a far worse outcome than the one
+// it would fix.
+//
+// A config that cannot be read or parsed produces no advice rather than a guess. JSON5 is the
+// common case there, and telling an operator their config is missing a key that is in it -- three
+// lines below a comment -- would be worse than saying nothing.
+func OpenClawConfigAdvice() []string {
+ data, err := os.ReadFile(openClawConfigPath())
+ if err != nil {
+ return nil
+ }
+ var config struct {
+ Plugins struct {
+ Allow []string `json:"allow"`
+ Entries map[string]struct {
+ Enabled *bool `json:"enabled"`
+ Hooks struct {
+ AllowConversationAccess *bool `json:"allowConversationAccess"`
+ } `json:"hooks"`
+ } `json:"entries"`
+ } `json:"plugins"`
+ }
+ if err := json.Unmarshal(data, &config); err != nil {
+ return nil
+ }
+
+ var advice []string
+ entry, hasEntry := config.Plugins.Entries[openClawPluginID]
+ if !hasEntry || entry.Hooks.AllowConversationAccess == nil || !*entry.Hooks.AllowConversationAccess {
+ advice = append(advice, fmt.Sprintf(
+ "Add plugins.entries.%s.hooks.allowConversationAccess = true to %s to collect token usage and agent messages; everything else is collected without it.",
+ openClawPluginID, openClawConfigPath()))
+ }
+ if len(config.Plugins.Allow) > 0 {
+ allowed := false
+ for _, id := range config.Plugins.Allow {
+ if id == openClawPluginID {
+ allowed = true
+ break
+ }
+ }
+ if !allowed {
+ advice = append(advice, fmt.Sprintf(
+ "Add %q to plugins.allow in %s; your config uses an allowlist, so the plugin will not load until it is named there.",
+ openClawPluginID, openClawConfigPath()))
+ }
+ }
+ return advice
+}
+
+// openClawConfigPath resolves the config file OpenClaw reads. Read-only; see OpenClawConfigAdvice.
+func openClawConfigPath() string {
+ if override := strings.TrimSpace(os.Getenv(openClawConfigPathEnv)); override != "" {
+ return override
+ }
+ if stateDir := strings.TrimSpace(os.Getenv(openClawStateDirEnv)); stateDir != "" {
+ return filepath.Join(stateDir, openClawConfigFileName)
+ }
+ home, err := os.UserHomeDir()
+ if err != nil {
+ return ""
+ }
+ return filepath.Join(home, openClawStateDirName, openClawConfigFileName)
+}
+
+func openClawEmbeddedPluginSourcePath() string {
+ return filepath.Clean(filepath.Join("assets", "openclaw", openClawEntryFileName))
+}
+
+func openClawRootPluginSourcePath() string {
+ return filepath.Clean(filepath.Join("..", "..", "..", "..", "..", "plugins", "openclaw-beacon", "src", openClawEntryFileName))
+}
diff --git a/cli/beacon/internal/endpoint/hooks/openclaw_test.go b/cli/beacon/internal/endpoint/hooks/openclaw_test.go
new file mode 100644
index 00000000..5496e1eb
--- /dev/null
+++ b/cli/beacon/internal/endpoint/hooks/openclaw_test.go
@@ -0,0 +1,460 @@
+package hooks
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+// openClawInstall runs a user-level install against a temporary home and returns the plugin
+// directory it wrote.
+func openClawInstall(t *testing.T) (OpenClawStatus, string) {
+ t.Helper()
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv(openClawStateDirEnv, "")
+ t.Setenv(openClawConfigPathEnv, "")
+
+ status, err := InstallOpenClaw(OpenClawOptions{
+ Level: LevelUser,
+ LogPath: filepath.Join(home, "runtime.jsonl"),
+ UserMode: true,
+ })
+ if err != nil {
+ t.Fatalf("install: %v", err)
+ }
+ return status, filepath.Join(home, ".openclaw", "extensions", "beacon-endpoint")
+}
+
+// OpenClaw discovers a plugin as a directory and skips one missing either manifest, without
+// reporting anything. An install that wrote only the entry would look like a working install and
+// collect nothing.
+func TestOpenClawInstallWritesTheWholePluginDirectory(t *testing.T) {
+ status, dir := openClawInstall(t)
+
+ if !status.Installed {
+ t.Fatalf("install reported not installed: %s", status.Message)
+ }
+ if status.PluginPath != dir {
+ t.Fatalf("plugin path = %q, want %q", status.PluginPath, dir)
+ }
+ for _, name := range []string{"beacon.js", "package.json", "openclaw.plugin.json"} {
+ if _, err := os.Stat(filepath.Join(dir, name)); err != nil {
+ t.Fatalf("install did not write %s: %v", name, err)
+ }
+ }
+}
+
+func TestOpenClawInstallRendersTheHookInvocation(t *testing.T) {
+ status, dir := openClawInstall(t)
+
+ entry, err := os.ReadFile(filepath.Join(dir, "beacon.js"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ source := string(entry)
+ if strings.Contains(source, "__BEACON_") {
+ t.Fatal("installed plugin still carries an unresolved Beacon placeholder")
+ }
+ if !strings.Contains(source, OpenClawManagedPluginMarker) {
+ t.Fatal("installed plugin carries no Beacon marker")
+ }
+ // The argv is JSON, so the binary path appears JSON-escaped. Asserted through the same helper
+ // status uses, which is what makes a Windows path with backslashes compare correctly.
+ if !extensionReferencesBinary(source, status.BinaryPath) {
+ t.Fatalf("installed plugin does not spawn %s", status.BinaryPath)
+ }
+ for _, want := range []string{`"--platform"`, `"openclaw"`, `"openclaw-event"`} {
+ if !strings.Contains(source, want) {
+ t.Fatalf("installed plugin argv is missing %s:\n%s", want, firstLines(source, 40))
+ }
+ }
+}
+
+// The manifests are written verbatim, so an install is byte-identical to the reviewed source.
+func TestOpenClawInstallWritesTheReviewedManifests(t *testing.T) {
+ _, dir := openClawInstall(t)
+
+ var pkg struct {
+ Type string `json:"type"`
+ OpenClaw struct {
+ Extensions []string `json:"extensions"`
+ } `json:"openclaw"`
+ }
+ data, err := os.ReadFile(filepath.Join(dir, "package.json"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := json.Unmarshal(data, &pkg); err != nil {
+ t.Fatalf("installed package.json does not parse: %v", err)
+ }
+ if pkg.Type != "module" || len(pkg.OpenClaw.Extensions) != 1 || pkg.OpenClaw.Extensions[0] != "./beacon.js" {
+ t.Fatalf("installed package.json does not declare the entry: %+v", pkg)
+ }
+
+ var manifest struct {
+ ID string `json:"id"`
+ }
+ data, err = os.ReadFile(filepath.Join(dir, "openclaw.plugin.json"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := json.Unmarshal(data, &manifest); err != nil {
+ t.Fatalf("installed openclaw.plugin.json does not parse: %v", err)
+ }
+ // The id an operator addresses the plugin by, in `openclaw plugins enable` and in the config
+ // key the advice below names. It is a contract with their config file, not a directory name.
+ if manifest.ID != openClawPluginID {
+ t.Fatalf("installed manifest id = %q, want %q", manifest.ID, openClawPluginID)
+ }
+}
+
+func TestOpenClawInstallIsIdempotent(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv(openClawStateDirEnv, "")
+
+ opts := OpenClawOptions{Level: LevelUser, LogPath: filepath.Join(home, "runtime.jsonl"), UserMode: true}
+ if _, err := InstallOpenClaw(opts); err != nil {
+ t.Fatalf("first install: %v", err)
+ }
+ first, err := os.ReadFile(filepath.Join(home, ".openclaw", "extensions", "beacon-endpoint", "beacon.js"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ if _, err := InstallOpenClaw(opts); err != nil {
+ t.Fatalf("second install: %v", err)
+ }
+ second, err := os.ReadFile(filepath.Join(home, ".openclaw", "extensions", "beacon-endpoint", "beacon.js"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ if string(first) != string(second) {
+ t.Fatal("a repeated install rewrote the plugin differently")
+ }
+}
+
+// A `beacon-endpoint` plugin somebody else installed is not Beacon's to replace.
+func TestOpenClawInstallRefusesAnUnmanagedPlugin(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv(openClawStateDirEnv, "")
+
+ dir := filepath.Join(home, ".openclaw", "extensions", "beacon-endpoint")
+ if err := os.MkdirAll(dir, 0755); err != nil {
+ t.Fatal(err)
+ }
+ theirs := "export default { id: 'beacon-endpoint', register() {} }\n"
+ if err := os.WriteFile(filepath.Join(dir, "beacon.js"), []byte(theirs), 0644); err != nil {
+ t.Fatal(err)
+ }
+
+ _, err := InstallOpenClaw(OpenClawOptions{Level: LevelUser, LogPath: filepath.Join(home, "runtime.jsonl"), UserMode: true})
+ if err == nil {
+ t.Fatal("install overwrote a plugin Beacon did not write")
+ }
+ data, _ := os.ReadFile(filepath.Join(dir, "beacon.js"))
+ if string(data) != theirs {
+ t.Fatal("the unmanaged plugin was modified")
+ }
+}
+
+// Uninstall removes the whole directory. A directory holding manifests and no entry is a plugin
+// OpenClaw tries to load and cannot, which it reports as broken rather than as absent.
+func TestOpenClawUninstallRemovesTheDirectory(t *testing.T) {
+ _, dir := openClawInstall(t)
+
+ status, err := UninstallOpenClaw(OpenClawOptions{Level: LevelUser, UserMode: true})
+ if err != nil {
+ t.Fatalf("uninstall: %v", err)
+ }
+ if status.Installed {
+ t.Fatalf("still installed after uninstall: %s", status.Message)
+ }
+ if _, err := os.Stat(dir); !os.IsNotExist(err) {
+ t.Fatalf("plugin directory survived uninstall: %v", err)
+ }
+}
+
+// An operator's own file in the plugin directory stops the rmdir rather than being deleted with
+// Beacon's files.
+func TestOpenClawUninstallKeepsAnOperatorFile(t *testing.T) {
+ _, dir := openClawInstall(t)
+ theirs := filepath.Join(dir, "notes.md")
+ if err := os.WriteFile(theirs, []byte("mine\n"), 0644); err != nil {
+ t.Fatal(err)
+ }
+
+ if _, err := UninstallOpenClaw(OpenClawOptions{Level: LevelUser, UserMode: true}); err != nil {
+ t.Fatalf("uninstall: %v", err)
+ }
+ if _, err := os.Stat(theirs); err != nil {
+ t.Fatalf("uninstall deleted a file Beacon did not write: %v", err)
+ }
+ if _, err := os.Stat(filepath.Join(dir, "beacon.js")); !os.IsNotExist(err) {
+ t.Fatal("uninstall left the plugin entry behind")
+ }
+}
+
+func TestOpenClawUninstallLeavesAnUnmanagedPlugin(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv(openClawStateDirEnv, "")
+
+ dir := filepath.Join(home, ".openclaw", "extensions", "beacon-endpoint")
+ if err := os.MkdirAll(dir, 0755); err != nil {
+ t.Fatal(err)
+ }
+ theirs := "export default { id: 'beacon-endpoint', register() {} }\n"
+ if err := os.WriteFile(filepath.Join(dir, "beacon.js"), []byte(theirs), 0644); err != nil {
+ t.Fatal(err)
+ }
+
+ if _, err := UninstallOpenClaw(OpenClawOptions{Level: LevelUser, UserMode: true}); err != nil {
+ t.Fatalf("uninstall: %v", err)
+ }
+ data, err := os.ReadFile(filepath.Join(dir, "beacon.js"))
+ if err != nil || string(data) != theirs {
+ t.Fatal("uninstall removed a plugin Beacon did not write")
+ }
+}
+
+// A directory OpenClaw will skip must not be reported as installed. This is the failure the probe
+// exists for: OpenClaw says nothing about a plugin it skipped, so "never loaded" and "loaded and
+// saw nothing" are indistinguishable from the log alone.
+func TestOpenClawStatusRejectsAMissingManifest(t *testing.T) {
+ _, dir := openClawInstall(t)
+ if err := os.Remove(filepath.Join(dir, "openclaw.plugin.json")); err != nil {
+ t.Fatal(err)
+ }
+
+ status := OpenClawHookStatus(OpenClawOptions{Level: LevelUser, UserMode: true})
+ if status.Installed {
+ t.Fatal("status reported installed with a manifest missing")
+ }
+ if !strings.Contains(status.Message, "openclaw.plugin.json") {
+ t.Fatalf("status does not name the missing manifest: %s", status.Message)
+ }
+}
+
+func TestOpenClawStatusRejectsAMissingBinary(t *testing.T) {
+ status, _ := openClawInstall(t)
+ if err := os.Remove(status.BinaryPath); err != nil {
+ t.Fatal(err)
+ }
+
+ got := OpenClawHookStatus(OpenClawOptions{Level: LevelUser, UserMode: true})
+ if got.Installed {
+ t.Fatal("status reported installed with the hook binary gone")
+ }
+}
+
+// OPENCLAW_STATE_DIR relocates the whole state directory, and OpenClaw reads it itself. An install
+// that ignored it would write where that gateway does not look and report success.
+func TestOpenClawStateDirOverrideMovesThePlugin(t *testing.T) {
+ home := t.TempDir()
+ state := filepath.Join(t.TempDir(), "gateway-state")
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv(openClawStateDirEnv, state)
+
+ if _, err := InstallOpenClaw(OpenClawOptions{Level: LevelUser, LogPath: filepath.Join(home, "runtime.jsonl"), UserMode: true}); err != nil {
+ t.Fatalf("install: %v", err)
+ }
+ if _, err := os.Stat(filepath.Join(state, "extensions", "beacon-endpoint", "beacon.js")); err != nil {
+ t.Fatalf("install ignored %s: %v", openClawStateDirEnv, err)
+ }
+ if _, err := os.Stat(filepath.Join(home, ".openclaw")); !os.IsNotExist(err) {
+ t.Fatal("install also wrote to the default location")
+ }
+}
+
+func TestOpenClawProjectLevelPathIsTheWorkspaceRoot(t *testing.T) {
+ wd := t.TempDir()
+ t.Chdir(wd)
+ t.Setenv(openClawStateDirEnv, "")
+
+ path, err := OpenClawEntryPath(LevelProject)
+ if err != nil {
+ t.Fatal(err)
+ }
+ want := filepath.Join(wd, ".openclaw", "extensions", "beacon-endpoint", "beacon.js")
+ if path != want {
+ t.Fatalf("project entry path = %q, want %q", path, want)
+ }
+}
+
+// OPENCLAW_STATE_DIR is a global-scope override. OpenClaw joins the workspace literal for the
+// project scope with no override at all, so applying it to both would write the project plugin
+// where nothing reads it.
+func TestOpenClawStateDirDoesNotMoveTheProjectPlugin(t *testing.T) {
+ wd := t.TempDir()
+ t.Chdir(wd)
+ t.Setenv(openClawStateDirEnv, filepath.Join(t.TempDir(), "elsewhere"))
+
+ path, err := OpenClawEntryPath(LevelProject)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.HasPrefix(path, wd) {
+ t.Fatalf("project entry path = %q, want one under %q", path, wd)
+ }
+}
+
+// The checked-in plugin and its embedded copy are two files with the same content, and nothing but
+// a test keeps them that way.
+func TestOpenClawEmbeddedPluginMatchesRootSource(t *testing.T) {
+ embedded, err := os.ReadFile(openClawEmbeddedPluginSourcePath())
+ if err != nil {
+ t.Fatalf("embedded plugin source is unreadable: %v", err)
+ }
+ root, err := os.ReadFile(openClawRootPluginSourcePath())
+ if err != nil {
+ t.Fatalf("root plugin source is unreadable: %v", err)
+ }
+ if string(embedded) != string(root) {
+ t.Fatal("plugins/openclaw-beacon/src/beacon.js and its embedded copy have drifted; " +
+ "run `bun run sync` in plugins/openclaw-beacon")
+ }
+}
+
+// Conversation hooks are withheld from a non-bundled plugin until the operator grants access, so
+// an otherwise perfect install collects no tokens. Advice is how that gap becomes visible.
+func TestOpenClawConfigAdviceAsksForConversationAccess(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv(openClawStateDirEnv, "")
+ t.Setenv(openClawConfigPathEnv, "")
+ writeOpenClawConfig(t, home, `{"plugins":{"entries":{}}}`)
+
+ advice := OpenClawConfigAdvice()
+ if len(advice) != 1 || !strings.Contains(advice[0], "allowConversationAccess") {
+ t.Fatalf("advice = %v, want one line about allowConversationAccess", advice)
+ }
+}
+
+func TestOpenClawConfigAdviceIsSilentWhenAccessIsGranted(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv(openClawStateDirEnv, "")
+ t.Setenv(openClawConfigPathEnv, "")
+ writeOpenClawConfig(t, home,
+ `{"plugins":{"entries":{"beacon-endpoint":{"enabled":true,"hooks":{"allowConversationAccess":true}}}}}`)
+
+ if advice := OpenClawConfigAdvice(); len(advice) != 0 {
+ t.Fatalf("advice = %v, want none", advice)
+ }
+}
+
+// An allowlist that does not name the plugin stops it loading entirely, which is worth saying.
+func TestOpenClawConfigAdviceNamesAnExcludingAllowlist(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv(openClawStateDirEnv, "")
+ t.Setenv(openClawConfigPathEnv, "")
+ writeOpenClawConfig(t, home,
+ `{"plugins":{"allow":["codex"],"entries":{"beacon-endpoint":{"hooks":{"allowConversationAccess":true}}}}}`)
+
+ advice := OpenClawConfigAdvice()
+ if len(advice) != 1 || !strings.Contains(advice[0], "plugins.allow") {
+ t.Fatalf("advice = %v, want one line about plugins.allow", advice)
+ }
+}
+
+// Beacon never introduces an allowlist. A config with no `allow` key permits every plugin; adding
+// one to fix Beacon's load would deny every other plugin the operator runs.
+func TestOpenClawConfigAdviceDoesNotMentionAnAbsentAllowlist(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv(openClawStateDirEnv, "")
+ t.Setenv(openClawConfigPathEnv, "")
+ writeOpenClawConfig(t, home,
+ `{"plugins":{"entries":{"beacon-endpoint":{"hooks":{"allowConversationAccess":true}}}}}`)
+
+ for _, line := range OpenClawConfigAdvice() {
+ if strings.Contains(line, "plugins.allow") {
+ t.Fatalf("advice suggests creating an allowlist: %q", line)
+ }
+ }
+}
+
+// A JSON5 config -- comments, trailing commas -- is one OpenClaw accepts and Go's decoder does
+// not. Guessing at what it contains would mean telling an operator to add a key that is already
+// three lines below a comment.
+func TestOpenClawConfigAdviceIsSilentOnAnUnparseableConfig(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv(openClawStateDirEnv, "")
+ t.Setenv(openClawConfigPathEnv, "")
+ writeOpenClawConfig(t, home, "{\n // the gateway\n plugins: { entries: {} },\n}\n")
+
+ if advice := OpenClawConfigAdvice(); len(advice) != 0 {
+ t.Fatalf("advice = %v, want none for a config Beacon could not read", advice)
+ }
+}
+
+func TestOpenClawConfigAdviceIsSilentWithNoConfig(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv(openClawStateDirEnv, "")
+ t.Setenv(openClawConfigPathEnv, "")
+
+ if advice := OpenClawConfigAdvice(); len(advice) != 0 {
+ t.Fatalf("advice = %v, want none before OpenClaw has written a config", advice)
+ }
+}
+
+// Beacon reads OpenClaw's config and never writes it: it is "JSON or JSON5" by OpenClaw's own
+// documentation, and a Go round trip would strip an operator's comments out of the file that
+// configures every chat channel they run.
+func TestOpenClawInstallDoesNotTouchTheGatewayConfig(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv(openClawStateDirEnv, "")
+ t.Setenv(openClawConfigPathEnv, "")
+ original := "{\n // hand written\n \"plugins\": { \"entries\": {} }\n}\n"
+ writeOpenClawConfig(t, home, original)
+
+ if _, err := InstallOpenClaw(OpenClawOptions{Level: LevelUser, LogPath: filepath.Join(home, "runtime.jsonl"), UserMode: true}); err != nil {
+ t.Fatalf("install: %v", err)
+ }
+ data, err := os.ReadFile(filepath.Join(home, ".openclaw", openClawConfigFileName))
+ if err != nil {
+ t.Fatal(err)
+ }
+ if string(data) != original {
+ t.Fatalf("install rewrote the gateway config:\n%s", data)
+ }
+}
+
+func writeOpenClawConfig(t *testing.T, home, content string) {
+ t.Helper()
+ dir := filepath.Join(home, ".openclaw")
+ if err := os.MkdirAll(dir, 0755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(filepath.Join(dir, openClawConfigFileName), []byte(content), 0644); err != nil {
+ t.Fatal(err)
+ }
+}
+
+func firstLines(s string, n int) string {
+ lines := strings.SplitN(s, "\n", n+1)
+ if len(lines) > n {
+ lines = lines[:n]
+ }
+ return strings.Join(lines, "\n")
+}
diff --git a/cli/beacon/internal/endpoint/inventory/inventory.go b/cli/beacon/internal/endpoint/inventory/inventory.go
index 1f6464ec..dbc022f9 100644
--- a/cli/beacon/internal/endpoint/inventory/inventory.go
+++ b/cli/beacon/internal/endpoint/inventory/inventory.go
@@ -237,6 +237,7 @@ func candidates(home, wd string) []candidate {
items = append(items, clineCandidates(home, wd)...)
items = append(items, piCandidates(home, wd)...)
items = append(items, ompCandidates(home, wd)...)
+ items = append(items, openClawCandidates(home, wd)...)
items = append(items, hermesCandidates(home)...)
items = append(items, devinCandidates(home, wd)...)
items = append(items, grokCandidates(home, wd)...)
@@ -384,6 +385,36 @@ func ompCandidates(home, wd string) []candidate {
return items
}
+// openClawCandidates covers both OpenClaw plugin locations.
+//
+// The user path comes from the installer rather than being rebuilt here, for the reason
+// ompCandidates gives: OPENCLAW_STATE_DIR moves it, and only the installer knows the rule. The
+// project path is the literal OpenClaw joins onto its workspace, which has no override.
+//
+// The candidate is the plugin *entry*, not its directory, because the entry is what carries
+// Beacon's marker -- the manifests beside it are byte-identical for every install and identify
+// nothing.
+func openClawCandidates(home, wd string) []candidate {
+ items := []candidate{}
+ if home != "" {
+ if path, err := hooks.OpenClawEntryPathForHome(home, hooks.LevelUser); err == nil {
+ items = append(items, candidate{
+ runtime: "openclaw_gateway",
+ path: path,
+ scope: ScopeUser, format: formatMetadataOnly, kind: KindPlugin,
+ })
+ }
+ }
+ if wd != "" {
+ items = append(items, candidate{
+ runtime: "openclaw_gateway",
+ path: filepath.Join(wd, ".openclaw", "extensions", "beacon-endpoint", "beacon.js"),
+ scope: ScopeProject, format: formatMetadataOnly, kind: KindPlugin,
+ })
+ }
+ return items
+}
+
func hermesCandidates(home string) []candidate {
return []candidate{{runtime: "hermes", path: filepath.Join(home, ".hermes", "config.yaml"), scope: ScopeUser, format: formatYAML, kind: KindNativeConfig}}
}
@@ -856,6 +887,10 @@ func beaconManaged(item candidate, data []byte) bool {
// is attributed to the runtime that actually loads it rather than to whichever case ran first.
case "omp":
return strings.Contains(text, hooks.OmpManagedExtensionMarker)
+ // The plugin entry's marker, read from the installer's own constant for the reason the Pi case
+ // gives. The manifests beside it carry no marker because they are identical for every install.
+ case "openclaw_gateway":
+ return strings.Contains(text, hooks.OpenClawManagedPluginMarker)
case "grok":
return strings.Contains(text, "beacon-managed-grok-hooks:v1")
// Matched on the hook command rather than on a marker, because Beacon merges into Qwen's own
diff --git a/cli/beacon/internal/endpoint/inventory/inventory_test.go b/cli/beacon/internal/endpoint/inventory/inventory_test.go
index 416c2139..ed2de075 100644
--- a/cli/beacon/internal/endpoint/inventory/inventory_test.go
+++ b/cli/beacon/internal/endpoint/inventory/inventory_test.go
@@ -353,6 +353,12 @@ func TestScanIncludesAllSupportedCurrentUserAndProjectConfigs(t *testing.T) {
// project -- but under its own `.omp` root, because the two runtimes install separately.
{runtime: "omp", path: filepath.Join(home, ".omp", "agent", "extensions", "beacon.ts"), scope: ScopeUser, format: formatMetadataOnly, kind: KindPlugin},
{runtime: "omp", path: filepath.Join(work, ".omp", "extensions", "beacon.ts"), scope: ScopeProject, format: formatMetadataOnly, kind: KindPlugin},
+ // OpenClaw's candidate is the plugin entry rather than its directory, because the entry is
+ // what carries Beacon's marker -- the two manifests beside it are byte-identical for every
+ // install and identify nothing. Both scopes are reported: OpenClaw discovers a workspace
+ // plugin root and a global one, and a gateway can be running with either.
+ {runtime: "openclaw_gateway", path: filepath.Join(home, ".openclaw", "extensions", "beacon-endpoint", "beacon.js"), scope: ScopeUser, format: formatMetadataOnly, kind: KindPlugin},
+ {runtime: "openclaw_gateway", path: filepath.Join(work, ".openclaw", "extensions", "beacon-endpoint", "beacon.js"), scope: ScopeProject, format: formatMetadataOnly, kind: KindPlugin},
{runtime: "hermes", path: filepath.Join(home, ".hermes", "config.yaml"), scope: ScopeUser, format: formatYAML, kind: KindNativeConfig},
{runtime: "devin-cli", path: filepath.Join(home, ".config", "devin", "config.json"), scope: ScopeUser, format: formatJSON, kind: KindNativeConfig},
{runtime: "devin-cli", path: filepath.Join(work, ".devin", "hooks.v1.json"), scope: ScopeProject, format: formatJSON, kind: KindHookConfig},
diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
index 8e32b37e..5a928186 100644
--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
@@ -1048,6 +1048,13 @@ func configureHarnesses(cfg endpointconfig.Config) ([]string, error) {
return paths, fmt.Errorf("Pi telemetry is installed with `beacon endpoint hooks install --harness pi`, not endpoint install")
case "omp", "oh_my_pi", "oh-my-pi":
return paths, fmt.Errorf("Oh My Pi telemetry is installed with `beacon endpoint hooks install --harness omp`, not endpoint install")
+ // OpenClaw has an OTLP surface, and it is still not one `endpoint install` can configure:
+ // it lives in OpenClaw's own config behind its diagnostics-otel plugin, so Beacon prints
+ // the settings rather than writing them. The agent-activity path is the managed plugin.
+ // Both commands are named, because an operator who reached for --harness openclaw wants
+ // one of them and cannot tell from here which.
+ case "openclaw", "openclaw_gateway", "openclaw-gateway":
+ return paths, fmt.Errorf("OpenClaw agent telemetry is installed with `beacon endpoint hooks install --harness openclaw`, and its gateway OTLP export is set up with `beacon endpoint integrations openclaw print-config`, not endpoint install")
// Qwen Code has no OpenTelemetry export to point at the local collector, so `endpoint
// install --harness qwen` has nothing to configure. Saying so beats the generic
// "unsupported harness", which reads as "Beacon does not support Qwen Code" when the
diff --git a/cli/beacon/internal/tokens/coverage.go b/cli/beacon/internal/tokens/coverage.go
index 5ba07e37..b16b184c 100644
--- a/cli/beacon/internal/tokens/coverage.go
+++ b/cli/beacon/internal/tokens/coverage.go
@@ -67,23 +67,28 @@ var usageExpectation = map[string]struct {
expect string
reason string
}{
- "claude_code": {ExpectReported, "OTLP token and cost telemetry"},
- "codex_cli": {ExpectReported, "per-turn usage trace; Codex emits no cost"},
- "codex_desktop": {ExpectReported, "per-turn usage trace; Codex emits no cost"},
- "claude_cowork": {ExpectReported, "OTLP token and cost telemetry"},
- "cline": {ExpectReported, "plugin reports usage once per task"},
- "opencode": {ExpectReported, "plugin reports usage per assistant message"},
- "pi_cli": {ExpectReported, "extension reports usage and cost"},
- "omp": {ExpectReported, "extension reports usage and cost"},
+ "claude_code": {ExpectReported, "OTLP token and cost telemetry"},
+ "codex_cli": {ExpectReported, "per-turn usage trace; Codex emits no cost"},
+ "codex_desktop": {ExpectReported, "per-turn usage trace; Codex emits no cost"},
+ "claude_cowork": {ExpectReported, "OTLP token and cost telemetry"},
+ "cline": {ExpectReported, "plugin reports usage once per task"},
+ "opencode": {ExpectReported, "plugin reports usage per assistant message"},
+ "pi_cli": {ExpectReported, "extension reports usage and cost"},
+ "omp": {ExpectReported, "extension reports usage and cost"},
+ // Reported by the managed plugin's `llm_output` hook, which is the only OpenClaw surface that
+ // carries usage. It is a conversation hook, so OpenClaw withholds it from a non-bundled plugin
+ // until `plugins.entries.beacon-endpoint.hooks.allowConversationAccess` is set -- which is why
+ // an OpenClaw endpoint can be collecting everything else and reporting no tokens at all.
+ // `beacon endpoint hooks status --harness openclaw` is where that gap is surfaced.
+ "openclaw_gateway": {ExpectReported, "plugin reports usage per model response when conversation access is granted"},
"vercel_fx": {ExpectReported, "session store carries cumulative usage and cost"},
"asymptote_observe": {ExpectReported, "SDK spans carry semconv usage"},
- "gemini_cli": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
- "copilot_cli": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
- "vscode_copilot": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
- "factory": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
- "factory_droid": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
- "openclaw_gateway": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
+ "gemini_cli": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
+ "copilot_cli": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
+ "vscode_copilot": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
+ "factory": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
+ "factory_droid": {ExpectGenericOTLP, "only if it emits OTel GenAI semconv usage"},
// Grok Bot runs on a Cursor-hosted cloud computer and reaches Beacon only through Cursor's
// server-side OpenTelemetry export, so whether usage arrives depends on whether that export
// carries the semconv names -- the generic-OTLP case exactly, not a runtime Beacon reads.