Skip to content

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

Detect an OpenClaw gateway by its state directory, not its plugin root

Claude9a25d4932d79
diff --git a/cli/beacon/internal/endpoint/harness/openclaw.go b/cli/beacon/internal/endpoint/harness/openclaw.go
index 7145cdcb..7a644638 100644
--- a/cli/beacon/internal/endpoint/harness/openclaw.go
+++ b/cli/beacon/internal/endpoint/harness/openclaw.go
@@ -39,11 +39,21 @@ func DiscoverOpenClaw() Harness {
// 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
+ // The directory checked is OpenClaw's *state* directory, asked for by name rather than derived
+ // by walking up from the plugin path. Those are not the same place: the plugin path ends in a
+ // directory of its own, so walking up two levels lands on `extensions` -- which does not exist
+ // until something installs a plugin. A gateway with no plugins yet is exactly the case this
+ // fallback is for, and testing `extensions` would report it as not detected. Asking
+ // hooks.OpenClawStateDir also keeps an OPENCLAW_STATE_DIR override detected where it actually
+ // is rather than missed at the default location.
+ if !h.Detected {
+ home, err := os.UserHomeDir()
+ if err != nil {
+ home = ""
+ }
+ if stateDir, err := hooks.OpenClawStateDir(home); err == nil && dirExists(stateDir) {
+ h.Detected = true
+ }
}
h.TelemetryStatus, h.Message = openClawStatus(entryPath)
diff --git a/cli/beacon/internal/endpoint/harness/openclaw_test.go b/cli/beacon/internal/endpoint/harness/openclaw_test.go
new file mode 100644
index 00000000..c287a62d
--- /dev/null
+++ b/cli/beacon/internal/endpoint/harness/openclaw_test.go
@@ -0,0 +1,143 @@
+package harness
+
+import (
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks"
+)
+
+// openClawHome points discovery at a temporary home with no OpenClaw executable on PATH, which is
+// the situation the state-directory fallback exists for.
+func openClawHome(t *testing.T) string {
+ t.Helper()
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv("OPENCLAW_STATE_DIR", "")
+ t.Setenv("PATH", t.TempDir())
+ return home
+}
+
+// A gateway that has run but installed no plugins has `~/.openclaw` and no `~/.openclaw/extensions`.
+// That is the common case for a daemonized gateway whose PATH this process did not inherit, and it
+// is precisely what the fallback is for -- so detection must not depend on a directory that only
+// appears once a plugin is installed.
+func TestDiscoverOpenClawDetectsAGatewayWithNoPluginsInstalled(t *testing.T) {
+ home := openClawHome(t)
+ if err := os.MkdirAll(filepath.Join(home, ".openclaw"), 0755); err != nil {
+ t.Fatal(err)
+ }
+
+ h := DiscoverOpenClaw()
+ if !h.Detected {
+ t.Fatal("a gateway with a state directory and no plugins was reported as not detected")
+ }
+ if h.TelemetryStatus != TelemetryMissing {
+ t.Fatalf("telemetry status = %q, want %q", h.TelemetryStatus, TelemetryMissing)
+ }
+}
+
+// Nothing on disk and nothing on PATH is genuinely not detected.
+func TestDiscoverOpenClawReportsAbsent(t *testing.T) {
+ openClawHome(t)
+
+ h := DiscoverOpenClaw()
+ if h.Detected {
+ t.Fatal("OpenClaw reported as detected with no state directory and no executable")
+ }
+}
+
+// OPENCLAW_STATE_DIR moves the state directory, and OpenClaw reads it itself, so discovery has to
+// follow it rather than looking under the home directory.
+func TestDiscoverOpenClawFollowsTheStateDirOverride(t *testing.T) {
+ openClawHome(t)
+ state := filepath.Join(t.TempDir(), "gateway-state")
+ if err := os.MkdirAll(state, 0755); err != nil {
+ t.Fatal(err)
+ }
+ t.Setenv("OPENCLAW_STATE_DIR", state)
+
+ h := DiscoverOpenClaw()
+ if !h.Detected {
+ t.Fatalf("OPENCLAW_STATE_DIR install was not detected at %s", state)
+ }
+ want := filepath.Join(state, "extensions", "beacon-endpoint", "beacon.js")
+ if h.ConfigPath != want {
+ t.Fatalf("ConfigPath = %q, want %q", h.ConfigPath, want)
+ }
+}
+
+// A plugin directory missing a manifest is one OpenClaw skips during discovery without reporting
+// anything, so it must read as disabled rather than enabled.
+func TestDiscoverOpenClawReportsAnIncompletePluginAsDisabled(t *testing.T) {
+ home := openClawHome(t)
+ dir := filepath.Join(home, ".openclaw", "extensions", "beacon-endpoint")
+ if err := os.MkdirAll(dir, 0755); err != nil {
+ t.Fatal(err)
+ }
+ entry := "// " + hooks.OpenClawManagedPluginMarker + "\nexport default {}\n"
+ if err := os.WriteFile(filepath.Join(dir, "beacon.js"), []byte(entry), 0644); err != nil {
+ t.Fatal(err)
+ }
+
+ h := DiscoverOpenClaw()
+ if h.TelemetryStatus != TelemetryDisabled {
+ t.Fatalf("telemetry status = %q, want %q", h.TelemetryStatus, TelemetryDisabled)
+ }
+}
+
+// An entry without Beacon's marker is somebody else's plugin occupying the id. Reporting it as
+// enabled would claim telemetry Beacon is not collecting.
+func TestDiscoverOpenClawReportsAnUnmanagedPluginAsDisabled(t *testing.T) {
+ home := openClawHome(t)
+ dir := filepath.Join(home, ".openclaw", "extensions", "beacon-endpoint")
+ if err := os.MkdirAll(dir, 0755); err != nil {
+ t.Fatal(err)
+ }
+ for name, body := range map[string]string{
+ "beacon.js": "export default { id: 'beacon-endpoint', register() {} }\n",
+ "package.json": "{}\n",
+ "openclaw.plugin.json": "{}\n",
+ } {
+ if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0644); err != nil {
+ t.Fatal(err)
+ }
+ }
+
+ h := DiscoverOpenClaw()
+ if h.TelemetryStatus != TelemetryDisabled {
+ t.Fatalf("telemetry status = %q, want %q", h.TelemetryStatus, TelemetryDisabled)
+ }
+}
+
+// A complete, Beacon-written plugin directory is the enabled case.
+func TestDiscoverOpenClawReportsACompletePluginAsEnabled(t *testing.T) {
+ home := openClawHome(t)
+ dir := filepath.Join(home, ".openclaw", "extensions", "beacon-endpoint")
+ if err := os.MkdirAll(dir, 0755); err != nil {
+ t.Fatal(err)
+ }
+ entry := "// " + hooks.OpenClawManagedPluginMarker + "\nexport default {}\n"
+ for name, body := range map[string]string{
+ "beacon.js": entry,
+ "package.json": "{}\n",
+ "openclaw.plugin.json": "{}\n",
+ } {
+ if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0644); err != nil {
+ t.Fatal(err)
+ }
+ }
+
+ h := DiscoverOpenClaw()
+ if !h.Detected {
+ t.Fatal("an installed plugin did not mark the gateway as detected")
+ }
+ if h.TelemetryStatus != TelemetryEnabled {
+ t.Fatalf("telemetry status = %q, want %q", h.TelemetryStatus, TelemetryEnabled)
+ }
+ if h.Capability != "plugin" {
+ t.Fatalf("capability = %q, want plugin", h.Capability)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/hooks/openclaw.go b/cli/beacon/internal/endpoint/hooks/openclaw.go
index 8e7f6fa9..4d7e91cd 100644
--- a/cli/beacon/internal/endpoint/hooks/openclaw.go
+++ b/cli/beacon/internal/endpoint/hooks/openclaw.go
@@ -321,13 +321,11 @@ func OpenClawEntryPathForHome(home string, level Level) (string, error) {
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")
+ stateDir, err := OpenClawStateDir(home)
+ if err != nil {
+ return "", err
}
- return filepath.Join(home, openClawStateDirName, "extensions", openClawPluginID), nil
+ return filepath.Join(stateDir, "extensions", openClawPluginID), nil
case LevelProject:
cwd, err := os.Getwd()
if err != nil {
@@ -339,6 +337,29 @@ func openClawPluginDir(home string, level Level) (string, error) {
}
}
+// OpenClawStateDir returns the directory OpenClaw keeps its own state in for a caller-supplied
+// home directory.
+//
+// Exported because discovery needs it as evidence in its own right, not just as a prefix of the
+// plugin path. A gateway is commonly daemonized under an account whose PATH this process did not
+// inherit, so an absent `openclaw` executable is not absence of OpenClaw -- and the directory
+// OpenClaw creates on first run is what says otherwise. That directory is this one; the
+// `extensions` directory beneath it does not exist until something installs a plugin, which on a
+// fresh gateway may be never.
+//
+// Deriving this by walking up from the plugin path is what made that distinction easy to get
+// wrong: the plugin path has a directory segment of its own, so "two levels up" lands on
+// `extensions` here where it lands on the state root for the runtimes this was modelled on.
+func OpenClawStateDir(home string) (string, error) {
+ if stateDir := strings.TrimSpace(os.Getenv(openClawStateDirEnv)); stateDir != "" {
+ return stateDir, nil
+ }
+ if home == "" {
+ return "", fmt.Errorf("home directory is required to resolve the OpenClaw state directory")
+ }
+ return filepath.Join(home, openClawStateDirName), nil
+}
+
// 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
@@ -414,14 +435,16 @@ 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 {
+ // Only matters when OPENCLAW_STATE_DIR is unset; OpenClawStateDir reports that itself.
+ home = ""
+ }
+ stateDir, err := OpenClawStateDir(home)
if err != nil {
return ""
}
- return filepath.Join(home, openClawStateDirName, openClawConfigFileName)
+ return filepath.Join(stateDir, openClawConfigFileName)
}
func openClawEmbeddedPluginSourcePath() string {