fix: repair skill and run lifecycle config

HemantSudarshan · HemantSudarshan · commit 705723b9d0e1 · 2026-05-09T22:45:46.000+05:30
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -170,6 +170,10 @@ Docs: https://docs.openclaw.ai
 ### Fixes
 
 - Memory: close temp SQLite handles before failed atomic reindex cleanup and retry Windows EBUSY/EPERM/EACCES temp file removals, so `memory index --force` does not abort or leave temp sidecars on locked filesystems. Fixes #79708. Thanks @LobsterFarmerAmp and @hclsys.
+- Skills CLI: normalize object-shaped `metadata.openclaw.requires.config` entries by their `path` so skill info/status no longer renders `[object Object]` or blocks valid config requirements. Fixes #79488. Thanks @sebrinass.
+- Agents/subagents: honor `OPENCLAW_SPAWN_ALLOWLIST` and `SPAWN_ALLOWLIST` as fallback target-agent allowlists for `sessions_spawn` when no config allowlist is set. Fixes #79490. Thanks @baptisterou.
+- Control UI/WebChat: map backend agent run ids back to the originating chat run so context-overflow lifecycle errors clear the active run instead of leaving Stop and queued `/new` stuck. Fixes #79525. Thanks @dmak.
+- CLI/status: prefer systemd `is-active` when `systemctl show` returns a stale failed state, so active Gateway user services report as running. Fixes #79515. Thanks @holgergruenhagen.
 - Agents/CLI: add an explicit `reseedFromRawTranscriptWhenUncompacted` backend opt-in so safe invalidated CLI sessions can reseed from a bounded raw OpenClaw transcript tail before compaction while auth-boundary resets remain no-raw. Fixes #79713. (#79764) Thanks @hclsys.
 - Agents/CLI: handle resumed CLI JSONL output and bound supervisor output buffering so resumed runs stay readable without letting noisy child output grow unbounded.
 - Codex app-server: honor per-call `timeoutMs`, configured `image_generate` timeouts, and media image-understanding timeouts for dynamic tool calls, capped at 600000 ms, so slow image generation and image analysis no longer fail at the 30s bridge default. Fixes #79810. Thanks @omarshahine.
diff --git a/docs/gateway/config-tools.md b/docs/gateway/config-tools.md
@@ -379,7 +379,7 @@ Experimental built-in tool flags. Default off unless a strict-agentic GPT-5 auto
 ```
 
 - `model`: default model for spawned sub-agents. If omitted, sub-agents inherit the caller's model.
-- `allowAgents`: default allowlist of target agent ids for `sessions_spawn` when the requester agent does not set its own `subagents.allowAgents` (`["*"]` = any; default: same agent only).
+- `allowAgents`: default allowlist of target agent ids for `sessions_spawn` when the requester agent does not set its own `subagents.allowAgents` (`["*"]` = any; default: same agent only). If neither config path is set, `OPENCLAW_SPAWN_ALLOWLIST` or `SPAWN_ALLOWLIST` can provide a fallback (`*`, comma-separated ids, or a JSON array).
 - `runTimeoutSeconds`: default timeout (seconds) for `sessions_spawn` when the tool call omits `runTimeoutSeconds`. `0` means no timeout.
 - Per-subagent tool policy: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
 
diff --git a/docs/tools/creating-skills.md b/docs/tools/creating-skills.md
@@ -86,13 +86,13 @@ For how skills are loaded and prioritized, see [Skills](/tools/skills).
 
 The YAML frontmatter supports these fields:
 
-| Field                               | Required | Description                                                    |
-| ----------------------------------- | -------- | -------------------------------------------------------------- |
-| `name`                              | Yes      | Unique identifier using lowercase letters, digits, and hyphens |
-| `description`                       | Yes      | One-line description shown to the agent                        |
-| `metadata.openclaw.os`              | No       | OS filter (`["darwin"]`, `["linux"]`, etc.)                    |
-| `metadata.openclaw.requires.bins`   | No       | Required binaries on PATH                                      |
-| `metadata.openclaw.requires.config` | No       | Required config keys                                           |
+| Field                               | Required | Description                                                                    |
+| ----------------------------------- | -------- | ------------------------------------------------------------------------------ |
+| `name`                              | Yes      | Unique identifier using lowercase letters, digits, and hyphens                 |
+| `description`                       | Yes      | One-line description shown to the agent                                        |
+| `metadata.openclaw.os`              | No       | OS filter (`["darwin"]`, `["linux"]`, etc.)                                    |
+| `metadata.openclaw.requires.bins`   | No       | Required binaries on PATH                                                      |
+| `metadata.openclaw.requires.config` | No       | Required config keys (`"path"` strings or `{ path, access, purpose }` objects) |
 
 ## Best practices
 
diff --git a/docs/tools/skills.md b/docs/tools/skills.md
@@ -244,8 +244,8 @@ Fields under `metadata.openclaw`:
 <ParamField path="requires.env" type="string[]">
   Env var must exist or be provided in config.
 </ParamField>
-<ParamField path="requires.config" type="string[]">
-  List of `openclaw.json` paths that must be truthy.
+<ParamField path="requires.config" type='Array<string | { path: string; access?: string; purpose?: string }>'>
+  List of `openclaw.json` paths that must be truthy. Object entries are accepted for descriptive metadata; OpenClaw uses their `path` value for eligibility checks.
 </ParamField>
 <ParamField path="primaryEnv" type="string">
   Env var name associated with `skills.entries.<name>.apiKey`.
diff --git a/docs/tools/subagents.md b/docs/tools/subagents.md
@@ -286,6 +286,9 @@ See [Configuration reference](/gateway/configuration-reference) and
 <ParamField path="agents.defaults.subagents.allowAgents" type="string[]">
   Default target-agent allowlist used when the requester agent does not set its own `subagents.allowAgents`.
 </ParamField>
+<ParamField path="SPAWN_ALLOWLIST" type="string">
+  Environment fallback used only when neither per-agent nor default config sets `allowAgents`. Accepts `*`, comma-separated agent ids, or a JSON string array. `OPENCLAW_SPAWN_ALLOWLIST` is also accepted and takes precedence.
+</ParamField>
 <ParamField path="agents.defaults.subagents.requireAgentId" type="boolean" default="false">
   Block `sessions_spawn` calls that omit `agentId` (forces explicit profile selection). Per-agent override: `agents.list[].subagents.requireAgentId`.
 </ParamField>
diff --git a/src/agents/acp-spawn.ts b/src/agents/acp-spawn.ts
@@ -82,7 +82,10 @@ import {
 } from "./subagent-capabilities.js";
 import { getSubagentDepthFromSessionStore } from "./subagent-depth.js";
 import { countActiveRunsForSession, getSubagentRunByChildSessionKey } from "./subagent-registry.js";
-import { resolveSubagentTargetPolicy } from "./subagent-target-policy.js";
+import {
+  resolveConfiguredSubagentAllowAgents,
+  resolveSubagentTargetPolicy,
+} from "./subagent-target-policy.js";
 import { resolveInternalSessionKey, resolveMainSessionAlias } from "./tools/sessions-helpers.js";
 
 const log = createSubsystemLogger("agents/acp-spawn");
@@ -793,9 +796,11 @@ function resolveAcpSubagentEnvelopeState(params: {
     requesterAgentId,
     targetAgentId: params.targetAgentId,
     requestedAgentId: params.requestedAgentId,
-    allowAgents:
-      resolveAgentConfig(params.cfg, requesterAgentId)?.subagents?.allowAgents ??
-      params.cfg.agents?.defaults?.subagents?.allowAgents,
+    allowAgents: resolveConfiguredSubagentAllowAgents({
+      agentAllowAgents: resolveAgentConfig(params.cfg, requesterAgentId)?.subagents?.allowAgents,
+      defaultAllowAgents: params.cfg.agents?.defaults?.subagents?.allowAgents,
+      env: process.env,
+    }),
   });
   if (!targetPolicy.ok) {
     return {
diff --git a/src/agents/openclaw-tools.subagents.sessions-spawn.allowlist.test.ts b/src/agents/openclaw-tools.subagents.sessions-spawn.allowlist.test.ts
@@ -1,4 +1,5 @@
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { withEnvAsync } from "../test-utils/env.js";
 import {
   createSubagentSpawnTestConfig,
   loadSubagentSpawnModuleForTest,
@@ -133,6 +134,21 @@ describe("subagent spawn allowlist + sandbox guards", () => {
     });
   });
 
+  it("falls back to SPAWN_ALLOWLIST when config omits allowAgents", async () => {
+    setConfig({
+      agents: {
+        list: [{ id: "main" }, { id: "beta" }],
+      },
+    });
+
+    const result = await withEnvAsync({ SPAWN_ALLOWLIST: "*" }, () => spawn({ agentId: "beta" }));
+
+    expect(result).toMatchObject({
+      status: "accepted",
+      childSessionKey: expect.stringMatching(/^agent:beta:subagent:/),
+    });
+  });
+
   it("allows any agent when allowlist contains *", async () => {
     setConfig({
       agents: {
diff --git a/src/agents/skills.buildworkspaceskillstatus.test.ts b/src/agents/skills.buildworkspaceskillstatus.test.ts
@@ -147,6 +147,28 @@ describe("buildWorkspaceSkillStatus", () => {
     expect(skill.install[0]?.bins).toEqual(["fakebin"]);
   });
 
+  it("normalizes object-shaped config requirements from skill metadata", async () => {
+    const workspaceDir = await createTempWorkspaceDir();
+    await writeSkill({
+      dir: path.join(workspaceDir, "skills", "object-config-skill"),
+      name: "object-config-skill",
+      description: "Object config metadata",
+      metadata:
+        '{"openclaw":{"requires":{"config":[{"path":"browser.enabled","access":"read","purpose":"Check browser config"}]}}}',
+    });
+
+    const report = buildWorkspaceSkillStatus(workspaceDir, {
+      managedSkillsDir: path.join(workspaceDir, ".managed"),
+      config: { browser: { enabled: true } },
+    });
+    const skill = requireReportedSkill(report, "object-config-skill");
+
+    expect(skill.eligible).toBe(true);
+    expect(skill.requirements.config).toEqual(["browser.enabled"]);
+    expect(skill.missing.config).toEqual([]);
+    expect(skill.configChecks).toEqual([{ path: "browser.enabled", satisfied: true }]);
+  });
+
   it("respects OS-gated skills", () => {
     const entry = makeEntry({
       name: "os-skill",
diff --git a/src/agents/subagent-spawn.ts b/src/agents/subagent-spawn.ts
@@ -29,7 +29,10 @@ import { getSubagentDepthFromSessionStore } from "./subagent-depth.js";
 import { buildSubagentInitialUserMessage } from "./subagent-initial-user-message.js";
 import { countActiveRunsForSession, registerSubagentRun } from "./subagent-registry.js";
 import { resolveSubagentSpawnAcceptedNote } from "./subagent-spawn-accepted-note.js";
-import { resolveSubagentTargetPolicy } from "./subagent-target-policy.js";
+import {
+  resolveConfiguredSubagentAllowAgents,
+  resolveSubagentTargetPolicy,
+} from "./subagent-target-policy.js";
 export {
   SUBAGENT_SPAWN_ACCEPTED_NOTE,
   SUBAGENT_SPAWN_SESSION_ACCEPTED_NOTE,
@@ -805,9 +808,11 @@ export async function spawnSubagentDirect(
     requesterAgentId,
     targetAgentId,
     requestedAgentId,
-    allowAgents:
-      resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents ??
-      cfg?.agents?.defaults?.subagents?.allowAgents,
+    allowAgents: resolveConfiguredSubagentAllowAgents({
+      agentAllowAgents: resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents,
+      defaultAllowAgents: cfg?.agents?.defaults?.subagents?.allowAgents,
+      env: process.env,
+    }),
   });
   if (!targetPolicy.ok) {
     return {
diff --git a/src/agents/subagent-target-policy.test.ts b/src/agents/subagent-target-policy.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import {
+  resolveConfiguredSubagentAllowAgents,
   resolveSubagentAllowedTargetIds,
   resolveSubagentTargetPolicy,
 } from "./subagent-target-policy.js";
@@ -64,4 +65,33 @@ describe("subagent target policy", () => {
       allowedIds: ["planner"],
     });
   });
+
+  it("uses SPAWN_ALLOWLIST as a fallback allowlist when config omits one", () => {
+    expect(
+      resolveConfiguredSubagentAllowAgents({
+        env: { SPAWN_ALLOWLIST: " planner, checker " },
+      }),
+    ).toEqual(["planner", "checker"]);
+    expect(
+      resolveConfiguredSubagentAllowAgents({
+        env: { OPENCLAW_SPAWN_ALLOWLIST: '["research", "*"]', SPAWN_ALLOWLIST: "ignored" },
+      }),
+    ).toEqual(["research", "*"]);
+  });
+
+  it("keeps explicit config ahead of SPAWN_ALLOWLIST", () => {
+    expect(
+      resolveConfiguredSubagentAllowAgents({
+        agentAllowAgents: ["agent-specific"],
+        defaultAllowAgents: ["default"],
+        env: { SPAWN_ALLOWLIST: "*" },
+      }),
+    ).toEqual(["agent-specific"]);
+    expect(
+      resolveConfiguredSubagentAllowAgents({
+        defaultAllowAgents: ["default"],
+        env: { SPAWN_ALLOWLIST: "*" },
+      }),
+    ).toEqual(["default"]);
+  });
 });
diff --git a/src/agents/subagent-target-policy.ts b/src/agents/subagent-target-policy.ts
@@ -1,7 +1,50 @@
 import { normalizeAgentId } from "../routing/session-key.js";
+import { normalizeStringEntries } from "../shared/string-normalization.js";
 
 type SubagentTargetPolicyResult = { ok: true } | { ok: false; allowedText: string; error: string };
 
+type SubagentAllowlistEnv = {
+  OPENCLAW_SPAWN_ALLOWLIST?: string;
+  SPAWN_ALLOWLIST?: string;
+};
+
+export function parseSubagentAllowlistEnv(raw: string | undefined): string[] | undefined {
+  const trimmed = raw?.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  if (trimmed.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (Array.isArray(parsed)) {
+        const normalized = normalizeStringEntries(parsed);
+        return normalized.length > 0 ? normalized : undefined;
+      }
+    } catch {
+      return undefined;
+    }
+  }
+  const normalized = normalizeStringEntries(trimmed.split(","));
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+export function resolveConfiguredSubagentAllowAgents(params: {
+  agentAllowAgents?: readonly string[];
+  defaultAllowAgents?: readonly string[];
+  env?: SubagentAllowlistEnv;
+}): readonly string[] | undefined {
+  if (params.agentAllowAgents !== undefined) {
+    return params.agentAllowAgents;
+  }
+  if (params.defaultAllowAgents !== undefined) {
+    return params.defaultAllowAgents;
+  }
+  return (
+    parseSubagentAllowlistEnv(params.env?.OPENCLAW_SPAWN_ALLOWLIST) ??
+    parseSubagentAllowlistEnv(params.env?.SPAWN_ALLOWLIST)
+  );
+}
+
 function normalizeAllowAgents(allowAgents: readonly string[] | undefined): {
   configured: boolean;
   allowAny: boolean;
diff --git a/src/agents/tools/agents-list-tool.test.ts b/src/agents/tools/agents-list-tool.test.ts
@@ -90,6 +90,27 @@ describe("agents_list tool", () => {
     expect(details.agents?.[0]?.configured).toBe(true);
   });
 
+  it("uses SPAWN_ALLOWLIST as the default allowed target set when config omits allowAgents", async () => {
+    vi.stubEnv("SPAWN_ALLOWLIST", "*");
+    loadConfigMock.mockReturnValue({
+      agents: {
+        list: [{ id: "main", default: true }, { id: "codex" }],
+      },
+    } satisfies OpenClawConfig);
+
+    const { createAgentsListTool } = await import("./agents-list-tool.js");
+    const result = await createAgentsListTool({ agentSessionKey: "agent:main:main" }).execute(
+      "call",
+      {},
+    );
+
+    expect(result.details).toMatchObject({
+      requester: "main",
+      allowAny: true,
+      agents: [{ id: "main" }, { id: "codex" }],
+    });
+  });
+
   it("ignores legacy env-forced plugin runtime selections", async () => {
     vi.stubEnv("OPENCLAW_AGENT_RUNTIME", "codex");
     loadConfigMock.mockReturnValue({
diff --git a/src/agents/tools/agents-list-tool.ts b/src/agents/tools/agents-list-tool.ts
@@ -8,7 +8,10 @@ import {
 import { resolveModelAgentRuntimeMetadata } from "../agent-runtime-metadata.js";
 import { resolveAgentConfig, resolveAgentEffectiveModelPrimary } from "../agent-scope.js";
 import { resolveDefaultModelForAgent } from "../model-selection.js";
-import { resolveSubagentAllowedTargetIds } from "../subagent-target-policy.js";
+import {
+  resolveConfiguredSubagentAllowAgents,
+  resolveSubagentAllowedTargetIds,
+} from "../subagent-target-policy.js";
 import type { AnyAgentTool } from "./common.js";
 import { jsonResult } from "./common.js";
 import { resolveInternalSessionKey, resolveMainSessionAlias } from "./sessions-helpers.js";
@@ -54,9 +57,11 @@ export function createAgentsListTool(opts?: {
           DEFAULT_AGENT_ID,
       );
 
-      const allowAgents =
-        resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents ??
-        cfg?.agents?.defaults?.subagents?.allowAgents;
+      const allowAgents = resolveConfiguredSubagentAllowAgents({
+        agentAllowAgents: resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents,
+        defaultAllowAgents: cfg?.agents?.defaults?.subagents?.allowAgents,
+        env: process.env,
+      });
 
       const configuredAgents = Array.isArray(cfg.agents?.list) ? cfg.agents?.list : [];
       const configuredIds = configuredAgents.map((entry) => normalizeAgentId(entry.id));
diff --git a/src/daemon/systemd.test.ts b/src/daemon/systemd.test.ts
@@ -23,6 +23,7 @@ import {
   isSystemdUnitActive,
   isSystemdUserServiceAvailable,
   parseSystemdShow,
+  readSystemdServiceRuntime,
   readSystemdServiceExecStart,
   restartSystemdService,
   resolveSystemdUserUnitPath,
@@ -466,6 +467,10 @@ describe("isNonFatalSystemdInstallProbeError", () => {
 });
 
 describe("systemd runtime parsing", () => {
+  beforeEach(() => {
+    execFileMock.mockReset();
+  });
+
   it("parses active state details", () => {
     const output = [
       "ActiveState=inactive",
@@ -496,6 +501,40 @@ describe("systemd runtime parsing", () => {
       execMainCode: "exited",
     });
   });
+
+  it("prefers is-active when show reports a stale failed state", async () => {
+    execFileMock
+      .mockImplementationOnce((_cmd, args, _opts, cb) => {
+        assertUserSystemctlArgs(args, "status");
+        cb(null, "", "");
+      })
+      .mockImplementationOnce((_cmd, args, _opts, cb) => {
+        assertUserSystemctlArgs(
+          args,
+          "show",
+          GATEWAY_SERVICE,
+          "--no-page",
+          "--property",
+          "ActiveState,SubState,MainPID,ExecMainStatus,ExecMainCode",
+        );
+        cb(
+          null,
+          ["ActiveState=failed", "SubState=failed", "MainPID=42", "ExecMainStatus=0"].join("\n"),
+          "",
+        );
+      })
+      .mockImplementationOnce((_cmd, args, _opts, cb) => {
+        assertUserSystemctlArgs(args, "is-active", "--quiet", GATEWAY_SERVICE);
+        cb(null, "", "");
+      });
+
+    await expect(readSystemdServiceRuntime({ HOME: TEST_MANAGED_HOME })).resolves.toMatchObject({
+      status: "running",
+      state: "active",
+      pid: 42,
+      lastExitStatus: 0,
+    });
+  });
 });
 
 describe("resolveSystemdUserUnitPath", () => {
diff --git a/src/daemon/systemd.ts b/src/daemon/systemd.ts
@@ -888,10 +888,12 @@ export async function readSystemdServiceRuntime(
   }
   const parsed = parseSystemdShow(res.stdout || "");
   const activeState = normalizeLowercaseStringOrEmpty(parsed.activeState);
-  const status = activeState === "active" ? "running" : activeState ? "stopped" : "unknown";
+  const activeByProbe =
+    activeState === "active" ? true : await isSystemdUnitActive(env, unitName).catch(() => false);
+  const status = activeByProbe ? "running" : activeState ? "stopped" : "unknown";
   return {
     status,
-    state: parsed.activeState,
+    state: activeByProbe ? "active" : parsed.activeState,
     subState: parsed.subState,
     pid: parsed.mainPid,
     lastExitStatus: parsed.execMainStatus,
diff --git a/src/gateway/server-methods/chat.directive-tags.test.ts b/src/gateway/server-methods/chat.directive-tags.test.ts
diff --git a/src/gateway/server-methods/chat.ts b/src/gateway/server-methods/chat.ts
diff --git a/src/shared/frontmatter.test.ts b/src/shared/frontmatter.test.ts
diff --git a/src/shared/frontmatter.ts b/src/shared/frontmatter.ts
