From ba8eb4af388fc04879d67deca7c28a09cb6c16ee Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 20:35:01 +0100 Subject: [PATCH] docs: refresh config schema output refs --- docs/cli/config.md | 8 ++++++++ docs/cli/index.md | 2 +- docs/gateway/configuration.md | 10 +++++++++- docs/gateway/protocol.md | 14 +++++++++++--- 4 files changed, 29 insertions(+), 5 deletions(-) diff --git a/docs/cli/config.md b/docs/cli/config.md index 60b64cd6fb3..2057525696d 100644 --- a/docs/cli/config.md +++ b/docs/cli/config.md @@ -54,9 +54,17 @@ What it includes: - The current root config schema, plus a root `$schema` string field for editor tooling - Field `title` and `description` metadata derived from the same labels/help used by the Control UI +- Nested object, wildcard (`*`), and array-item (`[]`) nodes inherit the same field docs when labels/help exist - Best-effort live plugin + channel schema metadata when runtime manifests can be loaded - A clean fallback schema even when the current config is invalid +Related runtime RPC: + +- `config.schema.lookup` returns one normalized config path with a shallow + schema node (`title`, `description`, `type`, `enum`, `const`, common bounds), + matched UI hint metadata, and immediate child summaries. Use it for + path-scoped drill-down in Control UI or custom clients. + ```bash openclaw config schema ``` diff --git a/docs/cli/index.md b/docs/cli/index.md index 81c1d56590f..b569ba16844 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -1460,7 +1460,7 @@ Notes: Common RPCs: -- `config.schema.lookup` (inspect one config subtree with field docs) +- `config.schema.lookup` (inspect one config subtree with shallow schema fields, docs, and immediate child summaries) - `config.get` (read current config snapshot + hash) - `config.set` (validate + write full config; use `baseHash` for optimistic concurrency) - `config.apply` (validate + write config + restart + wake) diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 5508602b669..186abe530ca 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -53,7 +53,9 @@ See the [full reference](/gateway/configuration-reference) for every available f Open [http://127.0.0.1:18789](http://127.0.0.1:18789) and use the **Config** tab. The Control UI renders a form from the live config schema, including field labels/help plus plugin and channel schemas when available, with a **Raw - JSON** editor as an escape hatch. + JSON** editor as an escape hatch. For drill-down UIs and other tooling, the + gateway also exposes `config.schema.lookup` to fetch one path-scoped schema + node plus immediate child summaries. Edit `~/.openclaw/openclaw.json` directly. The Gateway watches the file and applies changes automatically (see [hot reload](#config-hot-reload)). @@ -72,6 +74,12 @@ Schema tooling notes: and config validation. - Field `title` and `description` values are carried into the schema output for editor and form tooling. +- Nested object, wildcard (`*`), and array-item (`[]`) entries inherit the same + docs metadata where schema labels/help exist. +- `config.schema.lookup` returns one normalized config path with a shallow + schema node (`title`, `description`, `type`, `enum`, `const`, common bounds, + and similar validation fields), matched UI hint metadata, and immediate child + summaries for drill-down tooling. - Runtime plugin/channel schemas are merged in when the gateway can load the current manifest registry. diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md index 9a5cd16df92..9d2d07ad5f9 100644 --- a/docs/gateway/protocol.md +++ b/docs/gateway/protocol.md @@ -277,10 +277,18 @@ Gateway exposes today. - `config.apply` validates + replaces the full config payload. - `config.schema` returns the live config schema payload used by Control UI and CLI tooling: schema, `uiHints`, version, and generation metadata, including - plugin + channel schema metadata when the runtime can load it. + plugin + channel schema metadata when the runtime can load it. The schema + includes field `title` / `description` metadata derived from the same labels + and help text used by the UI. - `config.schema.lookup` returns a path-scoped lookup payload for one config - path: normalized path, a shallow schema node with field docs, matched hint + - `hintPath`, and immediate child summaries for UI/CLI drill-down. + path: normalized path, a shallow schema node, matched hint + `hintPath`, and + immediate child summaries for UI/CLI drill-down. + - Lookup schema nodes keep the user-facing docs and common validation fields: + `title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, + numeric/string/array/object bounds, and boolean flags like + `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`. + - Child summaries expose `key`, normalized `path`, `type`, `required`, + `hasChildren`, plus the matched `hint` / `hintPath`. - `update.run` runs the gateway update flow and schedules a restart only when the update itself succeeded. - `wizard.start`, `wizard.next`, `wizard.status`, and `wizard.cancel` expose the