admin/ComfyUI-OpenClaw
1
0
Fork 0
mirror of https://github.com/rookiestar28/ComfyUI-OpenClaw.git synced 2026-08-14 00:48:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
rookiestar28
2026-02-15 17:40:07 +08:00
parent ca2552fe15
commit f7b2c42cdb
8 changed files with 256 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+41 -18
View File
@@ -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
docs/advanced_registry_and_transforms.md
+80
View File
@@ -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.
docs/connector.md
+37 -1
View File
@@ -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
docs/release/ci_regression_policy.md
+2 -2
View File
@@ -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.
docs/release/compatibility_matrix.md
+1 -1
View File
@@ -1,4 +1,4 @@
# Compatibility Matrix (R51)
# Compatibility Matrix
This document outlines the validated environments for ComfyUI-OpenClaw `v0.2.1` (M1 Release).
docs/release/support_policy.md
+1 -1
View File
@@ -1,4 +1,4 @@
# Support Policy (R51)
# Support Policy
## Support Tiers
docs/runtime_hardening_and_startup.md
+90
View File
@@ -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.
docs/sidecar.md
+4 -4
View File
@@ -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).