openclaw - 💡(How to fix) Fix RFC: standardize --json envelope shape across list-style subcommands (agents/sessions/models/cron/nodes/skills) [1 comments, 2 participants]

Version

openclaw 2026.4.20 (115f05d), also matches behavior described in the 2026.5.4 CHANGELOG.

Problem

Different --json subcommands return different envelope shapes for "list things":

(The bottom three are inferred from defensive duck-typing in our consumer code; the top three I just verified live on 2026.4.20.)

This forces every JSON consumer to write something like:

const items = Array.isArray(data) ? data : (data.items ?? data.agents ?? data.sessions ?? data.jobs ?? data.cron ?? []);

which both ages poorly and silently swallows real errors.

Proposal

Standardize --json list output on a versioned envelope, e.g.:

{
  "$schema": "https://openclaw.ai/schemas/list-v1.json",
  "version": "1",
  "kind": "agents",
  "count": 42,
  "items": [ {} ],
  "meta": { "//": "command-specific extras like sessions.path, sessions.activeMinutes" }
}

Migration path:

• One release ships both shapes; new shape is opt-in via --json-envelope=v1.
• One release flips the default; old shape stays available via --json-envelope=legacy.
• One release removes legacy.

Why this matters

We ship a desktop frontend (Crystal: https://github.com/jvpflum/Crystal) on top of OpenClaw with ~30 views that consume these subcommands. We currently maintain ~12 different defensive shape-coercion blocks. This is a paper-cut for every frontend / CI / SDK author that wraps the CLI.

Happy to draft the schema + back-compat flag if the design lands.

Related

Closed #73077 ("parent CLI commands exit 1 when invoked without a subcommand") and the ongoing CLI-stabilization theme suggest this is in scope.