From 88ff416aaf6fcbc2844e3d0252b3faa9c55578fc Mon Sep 17 00:00:00 2001
From: "openclaw-docs-sync[bot]"
 <openclaw-docs-sync[bot]@users.noreply.github.com>
Date: Sat, 11 Apr 2026 12:33:33 +0000
Subject: [PATCH] chore(sync): mirror docs from
 openclaw/openclaw@cc5c691f0069f1d23ce0cde6cd258f5027d40957

---
 .openclaw-sync/source.json              |  4 +-
 docs/gateway/configuration-reference.md |  2 +
 docs/reference/rich-output-protocol.md  | 50 +++++++++++++++++++++++++
 docs/web/control-ui.md                  | 32 ++++++++++++++++
 4 files changed, 86 insertions(+), 2 deletions(-)
 create mode 100644 docs/reference/rich-output-protocol.md

diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index 1040a9b46..d9dc2bce7 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "79c3dbecd12833ffa35b31c77d1caf10e5e065d5",
-  "syncedAt": "2026-04-11T11:36:38.835Z"
+  "sha": "cc5c691f0069f1d23ce0cde6cd258f5027d40957",
+  "syncedAt": "2026-04-11T12:33:32.898Z"
 }
diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md
index 239684475..71ca3a97a 100644
--- a/docs/gateway/configuration-reference.md
+++ b/docs/gateway/configuration-reference.md
@@ -2895,6 +2895,8 @@ See [Plugins](/tools/plugin).
       enabled: true,
       basePath: "/openclaw",
       // root: "dist/control-ui",
+      // embedSandbox: "scripts", // strict | scripts | trusted
+      // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs
       // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
       // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
       // allowInsecureAuth: false,
diff --git a/docs/reference/rich-output-protocol.md b/docs/reference/rich-output-protocol.md
new file mode 100644
index 000000000..c1547d586
--- /dev/null
+++ b/docs/reference/rich-output-protocol.md
@@ -0,0 +1,50 @@
+# Rich Output Protocol
+
+Assistant output can carry a small set of delivery/render directives:
+
+- `MEDIA:` for attachment delivery
+- `[[audio_as_voice]]` for audio presentation hints
+- `[[reply_to_current]]` / `[[reply_to:<id>]]` for reply metadata
+- `[embed ...]` for Control UI rich rendering
+
+These directives are separate. `MEDIA:` and reply/voice tags remain delivery metadata; `[embed ...]` is the web-only rich render path.
+
+## `[embed ...]`
+
+`[embed ...]` is the only agent-facing rich render syntax for the Control UI.
+
+Self-closing example:
+
+```text
+[embed ref="cv_123" title="Status" /]
+```
+
+Rules:
+
+- `[view ...]` is no longer valid for new output.
+- Embed shortcodes render in the assistant message surface only.
+- Only URL-backed embeds are rendered. Use `ref="..."` or `url="..."`.
+- Block-form inline HTML embed shortcodes are not rendered.
+- The web UI strips the shortcode from visible text and renders the embed inline.
+- `MEDIA:` is not an embed alias and should not be used for rich embed rendering.
+
+## Stored Rendering Shape
+
+The normalized/stored assistant content block is a structured `canvas` item:
+
+```json
+{
+  "type": "canvas",
+  "preview": {
+    "kind": "canvas",
+    "surface": "assistant_message",
+    "render": "url",
+    "viewId": "cv_123",
+    "url": "/__openclaw__/canvas/documents/cv_123/index.html",
+    "title": "Status",
+    "preferredHeight": 320
+  }
+}
+```
+
+Stored/rendered rich blocks use this `canvas` shape directly. `present_view` is not recognized.
diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index cdd3f6cba..b88c4310e 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -138,6 +138,38 @@ Cron jobs panel notes:
   - Gateway persists aborted partial assistant text into transcript history when buffered output exists
   - Persisted entries include abort metadata so transcript consumers can tell abort partials from normal completion output
 
+## Hosted embeds
+
+Assistant messages can render hosted web content inline with the `[embed ...]`
+shortcode. The iframe sandbox policy is controlled by
+`gateway.controlUi.embedSandbox`:
+
+- `strict`: disables script execution inside hosted embeds
+- `scripts`: allows interactive embeds while keeping origin isolation; this is
+  the default and is usually enough for self-contained browser games/widgets
+- `trusted`: adds `allow-same-origin` on top of `allow-scripts` for same-site
+  documents that intentionally need stronger privileges
+
+Example:
+
+```json5
+{
+  gateway: {
+    controlUi: {
+      embedSandbox: "scripts",
+    },
+  },
+}
+```
+
+Use `trusted` only when the embedded document genuinely needs same-origin
+behavior. For most agent-generated games and interactive canvases, `scripts` is
+the safer choice.
+
+Absolute external `http(s)` embed URLs stay blocked by default. If you
+intentionally want `[embed url="https://..."]` to load third-party pages, set
+`gateway.controlUi.allowExternalEmbedUrls: true`.
+
 ## Tailnet access (recommended)
 
 ### Integrated Tailscale Serve (preferred)