docs: add advanced runtime/security setup guides, update README TOC and bridge docs

rookiestar28 · rookiestar28 · commit f7b2c42cdbac · 2026-02-15T17:40:07.000+08:00
diff --git a/README.md b/README.md
@@ -152,7 +152,6 @@ This project is intentionally **not** a general-purpose assistant platform with
 
 - [Installation](#installation)
 - [Quick Start (Minimal)](#quick-start-minimal)
-  - [Sprint A Reliability Highlights](#sprint-a-reliability-highlights)
   - [Configure an LLM key](#1-configure-an-llm-key-for-plannerrefinervision-helpers)
   - [Configure webhook auth](#2-configure-webhook-auth-required-for-webhook)
   - [Set an Admin Token](#3-optional-recommended-set-an-admin-token)
@@ -170,11 +169,15 @@ This project is intentionally **not** a general-purpose assistant platform with
 - [Templates](#templates)
 - [Execution Budgets](#execution-budgets)
 - [LLM Failover](#llm-failover)
+- [Advanced Security and Runtime Setup](#advanced-security-and-runtime-setup)
+  - [Runtime hardening and startup gates](#runtime-hardening-and-startup-gates)
+  - [Remote registry sync and constrained transforms](#remote-registry-sync-and-constrained-transforms)
+  - [Connector command authorization policy](#connector-command-authorization-policy)
 - [State Directory & Logs](#state-directory--logs)
 - [Troubleshooting](#troubleshooting)
 - [Tests](#tests)
 - [Updating](#updating)
-- [Remote Control (Connector)](#-remote-control-connector)
+- [Remote Control (Connector)](#remote-control-connector)
 - [Security](#security)
 
 ---
@@ -194,17 +197,7 @@ If the UI loads but endpoints return 404, ComfyUI likely did not load the Python
 
 ## Quick Start (Minimal)
 
-### Sprint A Reliability Highlights
-
-Sprint A closes the M1 release gate with stronger config behavior and safer local convenience mode:
-
-- `R53`: config save/apply semantics are explicit in `PUT /openclaw/config` responses
-- `R54`: frontend guards for stale/partial settings states reduce accidental overwrite risk
-- `R57`: provider/model precedence is deterministic and stable across save/test/chat paths
-- `S27`: `/openclaw/llm/chat` enforces same-origin checks in localhost convenience mode
-- `R60`: `/openclaw/llm/models` uses bounded in-memory caching (TTL + max entries)
-
-### 1) Configure an LLM key (for Planner/Refiner/vision helpers)
+### 1 Configure an LLM key (for Planner/Refiner/vision helpers)
 
 Set at least one of:
 
@@ -334,12 +327,12 @@ Notes:
 - `POST /openclaw/webhook/validate` -dry-run render (no queue submission; includes render budgets + warnings)
 - `POST /openclaw/webhook/submit` -full pipeline: auth -normalize -idempotency -render -submit to queue
 
-**Payload Mapping (F40)**:
+**Payload mapping**:
 
 - Submit arbitrary payloads (GitHub, Discord, etc.) by adding `X-Webhook-Mapping-Profile: github_push` (or `discord_message`).
 - The internal engine maps fields to the canonical schema before validation.
 
-**Job Events (R71)**:
+**Job events**:
 
 - `GET /openclaw/events/stream` -SSE endpoint for real-time job lifecycle events (queued, running, completed, failed).
 - `GET /openclaw/events` -JSON polling fallback.
@@ -428,6 +421,7 @@ Bridge route groups:
   - `GET /bridge/health`
   - `POST /bridge/submit`
   - `POST /bridge/deliver`
+  - `POST /bridge/handshake` (protocol compatibility check during sidecar startup)
 - Worker bridge routes:
   - `GET /bridge/worker/poll`
   - `POST /bridge/worker/result/{job_id}`
@@ -454,6 +448,35 @@ Standalone worker runtime:
 - Current implementation note:
   - worker queue/result/heartbeat persistence is in-memory (MVP); use persistent backing for production durability.
 
+## Advanced Security and Runtime Setup
+
+### Runtime hardening and startup gates
+
+- Runtime profile resolution, startup security enforcement, module startup boundaries, and bridge protocol compatibility are documented in:
+  - `docs/runtime_hardening_and_startup.md`
+- Key settings:
+  - `OPENCLAW_RUNTIME_PROFILE` (`minimal` or `hardened`)
+  - `OPENCLAW_BRIDGE_ENABLED`
+  - `OPENCLAW_BRIDGE_DEVICE_TOKEN`, `OPENCLAW_BRIDGE_ALLOWED_DEVICE_IDS`
+
+### Remote registry sync and constrained transforms
+
+- Optional remote registry sync and constrained transform execution are documented in:
+  - `docs/advanced_registry_and_transforms.md`
+- Key settings:
+  - `OPENCLAW_ENABLE_REGISTRY_SYNC`, `OPENCLAW_REGISTRY_POLICY`
+  - `OPENCLAW_ENABLE_TRANSFORMS`, `OPENCLAW_TRANSFORM_*`
+
+### Connector command authorization policy
+
+- Connector command authorization and allow-from policies are documented in:
+  - `docs/connector.md#command-authorization-policy`
+- Key settings:
+  - `OPENCLAW_COMMAND_OVERRIDES`
+  - `OPENCLAW_COMMAND_ALLOW_FROM_PUBLIC`
+  - `OPENCLAW_COMMAND_ALLOW_FROM_RUN`
+  - `OPENCLAW_COMMAND_ALLOW_FROM_ADMIN`
+
 ## Templates
 
 Templates live in `data/templates/`.
@@ -558,7 +581,7 @@ Notes:
 - If your pack folder name is not `comfyui-openclaw`, the smoke script may need `OPENCLAW_PACK_IMPORT_NAME=your-folder-name`.
 - If imports fail with a `services.*` module error, check for name collisions with other custom nodes and prefer package-relative imports.
 
-### Operator Doctor (R72)
+### Operator Doctor
 
 Run the built-in diagnostic tool to verify environment readiness (libraries, permissions, contract files):
 
@@ -592,7 +615,7 @@ python3 -m unittest discover -s tests -p "test_*.py"
 - Git install: `git pull` inside `custom_nodes/comfyui-openclaw/`, then restart ComfyUI.
 - ComfyUI-Manager install: update from Manager UI, then restart ComfyUI.
 
-## ? Remote Control (Connector)
+## Remote Control (Connector)
 
 OpenClaw includes a standalone **Connector** process that allows you to control your local instance securely via **Telegram**, **Discord**, **LINE**, **WhatsApp**, **WeChat**, and **KakaoTalk**.
 
@@ -603,7 +626,7 @@ OpenClaw includes a standalone **Connector** process that allows you to control
 - **WeChat encrypted mode**: Official Account encrypted webhook mode is supported when AES settings are configured.
 - **KakaoTalk response safety**: QuickReply limits and safe fallback handling are enforced for reliable payload behavior.
 
-[- **See Setup Guide (docs/connector.md)**](docs/connector.md)
+- [See Setup Guide (`docs/connector.md`)](docs/connector.md)
 
 ## Security
 
diff --git a/docs/advanced_registry_and_transforms.md b/docs/advanced_registry_and_transforms.md
@@ -0,0 +1,80 @@
+# Advanced Registry Sync and Constrained Transforms
+
+This guide covers optional, high-control features that are disabled by default.
+
+## Overview
+
+- Remote registry sync uses quarantine and trust policy controls.
+- Constrained transforms execute trusted Python modules with strict runtime limits.
+- Both features are fail-closed when disabled.
+
+## Remote registry sync
+
+Enable remote registry sync:
+
+```bash
+OPENCLAW_ENABLE_REGISTRY_SYNC=1
+```
+
+Trust policy:
+
+- `OPENCLAW_REGISTRY_POLICY=audit` (default): records signature/provenance issues for review
+- `OPENCLAW_REGISTRY_POLICY=strict`: rejects non-compliant artifacts
+
+Behavior highlights:
+
+- Quarantine lifecycle is persisted under the state directory:
+  - `registry/quarantine/index.json`
+- Entries are tracked with audit trail records.
+- Anti-abuse controls include bounded dedupe windows and rate limiting.
+- Integrity and policy checks are enforced before activation paths.
+
+If registry sync is not enabled, registry operations fail closed.
+
+## Constrained transforms
+
+Enable constrained transforms:
+
+```bash
+OPENCLAW_ENABLE_TRANSFORMS=1
+```
+
+Runtime limits:
+
+- `OPENCLAW_TRANSFORM_TIMEOUT` (seconds, default `5`)
+- `OPENCLAW_TRANSFORM_MAX_OUTPUT` (bytes, default `65536`)
+- `OPENCLAW_TRANSFORM_MAX_PER_REQUEST` (default `5`)
+
+Trusted module paths:
+
+- Default trusted directory: `data/transforms`
+- Add extra trusted directories with `OPENCLAW_TRANSFORM_TRUSTED_DIRS`
+  - Use OS path separator (`;` on Windows, `:` on Linux/macOS)
+
+Security controls:
+
+- Only `.py` modules are allowed
+- Module size is capped
+- Module hash is pinned at registration time
+- Integrity is re-checked before execution
+- Execution is bounded by timeout and output budget
+
+If transforms are disabled, transform execution is denied and mapping-only behavior continues.
+
+## Example hardened operator profile
+
+```bash
+OPENCLAW_ENABLE_REGISTRY_SYNC=1
+OPENCLAW_REGISTRY_POLICY=strict
+OPENCLAW_ENABLE_TRANSFORMS=1
+OPENCLAW_TRANSFORM_TIMEOUT=3
+OPENCLAW_TRANSFORM_MAX_OUTPUT=32768
+OPENCLAW_TRANSFORM_MAX_PER_REQUEST=3
+```
+
+## Rollout notes
+
+1. Enable one feature at a time in a non-production environment.
+2. Review logs and operator diagnostics after startup.
+3. Keep strict policies for public or multi-tenant deployments.
+4. Treat trusted transform directories as code deployment boundaries.
diff --git a/docs/connector.md b/docs/connector.md
@@ -109,7 +109,7 @@ Set the following environment variables (or put them in a `.env` file if you use
 - `OPENCLAW_CONNECTOR_KAKAO_PORT`: Port (default `8096`).
 - `OPENCLAW_CONNECTOR_KAKAO_PATH`: Webhook path (default `/kakao/webhook`).
 
-**Image Delivery (F33):**
+**Image Delivery:**
 
 - `OPENCLAW_CONNECTOR_PUBLIC_BASE_URL`: Public HTTPS URL of your connector (e.g. `https://your-tunnel.example.com`). Required for sending images.
 - `OPENCLAW_CONNECTOR_MEDIA_PATH`: URL path for serving temporary media (default `/media`).
@@ -122,6 +122,42 @@ Set the following environment variables (or put them in a `.env` file if you use
 > WeChat currently supports text-first control. Image/media upload delivery is not implemented in phase 1.
 > Kakao currently supports text-first control and quick replies. Rich media delivery is not enabled in the default Kakao webhook flow.
 
+### Command authorization policy
+
+Connector commands are evaluated through a centralized authorization policy with three command classes:
+
+- `public`: low-risk status/help style commands
+- `run`: execution commands such as `/run` (still subject to trust/approval behavior)
+- `admin`: sensitive commands such as `/trace`, `/approvals`, `/approve`, `/reject`, and schedule controls
+
+Default behavior:
+
+- If no explicit allow-from list is configured for a command class, class-level defaults apply.
+- `admin` commands require the sender to be in `OPENCLAW_CONNECTOR_ADMIN_USERS`.
+- `public` and `run` commands still pass through each platform adapter's trust/allowlist checks.
+
+Optional policy controls:
+
+- `OPENCLAW_COMMAND_OVERRIDES`: JSON object mapping command name to class (`public`, `run`, `admin`).
+- `OPENCLAW_COMMAND_ALLOW_FROM_PUBLIC`: comma-separated sender IDs.
+- `OPENCLAW_COMMAND_ALLOW_FROM_RUN`: comma-separated sender IDs.
+- `OPENCLAW_COMMAND_ALLOW_FROM_ADMIN`: comma-separated sender IDs.
+
+Normalization rules:
+
+- Command keys in `OPENCLAW_COMMAND_OVERRIDES` are normalized to lowercase.
+- Missing leading `/` is added automatically.
+
+Example:
+
+```bash
+OPENCLAW_COMMAND_OVERRIDES='{"run":"admin","/status":"public"}'
+OPENCLAW_COMMAND_ALLOW_FROM_ADMIN=alice_id,bob_id
+OPENCLAW_COMMAND_ALLOW_FROM_RUN=alice_id,ops_bot_id
+```
+
+If a class-level `OPENCLAW_COMMAND_ALLOW_FROM_*` list is set and non-empty, only listed IDs can run that class.
+
 ### 3. Usage
 
 #### Running the Connector
diff --git a/docs/release/ci_regression_policy.md b/docs/release/ci_regression_policy.md
@@ -1,4 +1,4 @@
-# CI Regression Policy (R52)
+# CI Regression Policy
 
 To ensure stability and prevent regressions, all Pull Requests (PRs) must pass the following checks before merge.
 
@@ -32,5 +32,5 @@ They must pass even when internal implementation details change.
 If a change breaks a contract test:
 
 1. **Verify**: Is the breakage intentional?
-2. **Deprecate**: If yes, follow the Deprecation Policy (R51).
+2. **Deprecate**: If yes, follow the Deprecation Policy.
 3. **Update**: Update the contract test to reflect the new behavior.
diff --git a/docs/release/compatibility_matrix.md b/docs/release/compatibility_matrix.md
@@ -1,4 +1,4 @@
-# Compatibility Matrix (R51)
+# Compatibility Matrix
 
 This document outlines the validated environments for ComfyUI-OpenClaw `v0.2.1` (M1 Release).
 
diff --git a/docs/release/support_policy.md b/docs/release/support_policy.md
@@ -1,4 +1,4 @@
-# Support Policy (R51)
+# Support Policy
 
 ## Support Tiers
 
diff --git a/docs/runtime_hardening_and_startup.md b/docs/runtime_hardening_and_startup.md
@@ -0,0 +1,90 @@
+# Runtime Hardening and Startup
+
+This guide explains the startup security model and bridge compatibility behavior.
+
+## What this covers
+
+- Runtime profile selection
+- Hardened startup enforcement behavior
+- Module startup boundaries
+- Bridge protocol handshake compatibility
+
+## Runtime profile
+
+Use `OPENCLAW_RUNTIME_PROFILE` to select startup posture:
+
+- `minimal` (default): compatibility-first
+- `hardened`: strict fail-closed startup checks
+
+If the value is unknown, startup falls back to `minimal` with a warning.
+
+You can verify the active profile through:
+
+- `GET /openclaw/capabilities`
+- `GET /moltbot/capabilities`
+
+The response includes `runtime_profile`.
+
+## Hardened startup enforcement
+
+When `OPENCLAW_RUNTIME_PROFILE=hardened`, startup enforces mandatory controls and aborts on failure.
+
+Current mandatory checks:
+
+- Authentication is configured for privileged actions
+- Unsafe egress bypass is not enabled:
+  - `OPENCLAW_ALLOW_ANY_PUBLIC_LLM_HOST` must not bypass policy
+  - `OPENCLAW_ALLOW_INSECURE_BASE_URL` must not bypass policy
+- If webhook module is active, webhook auth mode must be configured
+- Redaction service must be available
+
+In `minimal` mode, the same checks emit warnings but do not block startup.
+
+## Module startup boundaries
+
+Module enablement is decided during startup and then locked.
+
+Current boundary behavior:
+
+- Core, security, observability, scheduler, webhook, and connector modules are initialized at startup
+- Bridge module initialization is conditional on `OPENCLAW_BRIDGE_ENABLED`
+- If bridge is disabled, bridge route registration is skipped
+
+## Bridge protocol handshake
+
+Sidecar startup performs protocol compatibility negotiation with:
+
+- `POST /bridge/handshake`
+
+Request body:
+
+```json
+{ "version": 1 }
+```
+
+Response behavior:
+
+- `200` when compatible
+- `409` when incompatible (too old or too new)
+- Includes compatibility metadata such as server version and minimum supported version
+
+The sidecar bridge client executes this handshake during startup before worker polling.
+
+## Recommended startup baseline
+
+Use this as a starting point for hardened deployments:
+
+```bash
+OPENCLAW_RUNTIME_PROFILE=hardened
+OPENCLAW_ADMIN_TOKEN=replace-with-strong-token
+OPENCLAW_WEBHOOK_AUTH_MODE=hmac
+OPENCLAW_WEBHOOK_HMAC_SECRET=replace-with-strong-secret
+OPENCLAW_BRIDGE_ENABLED=1
+OPENCLAW_BRIDGE_DEVICE_TOKEN=replace-with-bridge-device-token
+```
+
+Then validate:
+
+1. Restart ComfyUI and check startup logs for security gate result.
+2. Call `GET /openclaw/capabilities` and confirm `runtime_profile`.
+3. If sidecar is used, verify handshake succeeds before worker polling begins.
diff --git a/docs/sidecar.md b/docs/sidecar.md
@@ -42,7 +42,7 @@ The **OpenClaw Gateway** (sidecar) is a separate process that:
     stored here           (authenticated)          (no secrets)
 ```
 
-## Bridge API (R13 Contract)
+## Bridge API Contract
 
 The sidecar communicates with ComfyUI-OpenClaw via the Bridge API:
 
@@ -77,6 +77,6 @@ All mutating operations require an `idempotency_key` to prevent duplicate proces
 
 ## Next Steps
 
-1. ~~**F10**~~ ✅ Implemented: bridge endpoints in ComfyUI-OpenClaw
-2. ~~**F13**~~ ✅ Implemented: delivery adapter contract in ComfyUI-OpenClaw
-3. **F46**: Implement standalone sidecar process/runtime (external deployable service)
+1. Bridge endpoints in ComfyUI-OpenClaw are implemented.
+2. Delivery adapter contract in ComfyUI-OpenClaw is implemented.
+3. Implement standalone sidecar process/runtime (external deployable service).

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Compatibility Matrix (R51)`
	`1`	`+# Compatibility Matrix`
`2`	`2`
`3`	`3`	This document outlines the validated environments for ComfyUI-OpenClaw `v0.2.1` (M1 Release).
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Support Policy (R51)`
	`1`	`+# Support Policy`
`2`	`2`
`3`	`3`	`## Support Tiers`
`4`	`4`