mirror of
https://github.com/rookiestar28/ComfyUI-OpenClaw.git
synced 2026-08-14 00:48:07 +00:00
docs(readme): sync public docs with current runtime behavior
This commit is contained in:
rookiestar28
@@ -77,6 +77,17 @@ Deployment profiles and hardening references:
|
||||
|
||||
<details>
|
||||
|
||||
<summary><strong>Output contract, outbound egress handling, Security Doctor structure, and audit verification tooling aligned with the current runtime</strong></summary>
|
||||
|
||||
- Kept `/history` + `/view` as the supported runtime output contract for current operator flows, and made asset-service-only refs stay explicit as a bounded fallback state instead of silently guessing a direct `/api/assets` fetch path.
|
||||
- Consolidated outbound safe HTTP execution behind one shared `safe_io` executor seam so local-provider checks, connector callbacks, and redirect handling now follow the same SSRF-safe validation, pinning, and redirect re-check rules.
|
||||
- Split Security Doctor internals into focused endpoint, runtime, connector, report, and remediation modules while keeping the operator-facing doctor API and remediation workflow unchanged.
|
||||
- Added retained audit-chain verification tooling, including a persisted `audit.log.key` sidecar when no environment key is provided, so operators can verify the current audit log plus retained rotations after restart or log rotation.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary><strong>Provider URL parity and CI harness resilience tightened for local LLM defaults and Playwright bootstrap stability</strong></summary>
|
||||
|
||||
- Fixed the built-in `Ollama (Local)` provider default so OpenClaw's OpenAI-compatible requests now target the correct `/v1` surface by default, and existing loopback-root overrides are normalized onto the same bounded path instead of failing on `/models` or `/chat/completions` at the daemon root.
|
||||
@@ -738,6 +749,7 @@ Deployment profiles and hardening references:
|
||||
- [LLM Failover](#llm-failover)
|
||||
- [Advanced Security and Runtime Setup](#advanced-security-and-runtime-setup)
|
||||
- [State Directory & Logs](#state-directory--logs)
|
||||
- [Audit Chain Verification](#audit-chain-verification)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Tests](#tests)
|
||||
- [Updating](#updating)
|
||||
@@ -934,7 +946,7 @@ The OpenClaw sidebar includes these built-in tabs. Some tabs are capability-gate
|
||||
| Tab | What it does | Related docs |
|
||||
| --- | --- | --- |
|
||||
| `Settings` | Health/config/log visibility, provider/model setup, model connectivity checks, and optional localhost key storage. | [Quick Start](#quick-start-minimal), [LLM config](#llm-config-non-secret), [Troubleshooting](#troubleshooting) |
|
||||
| `Jobs` | Tracks prompt IDs, consumes deterministic event/task cursor metadata for polling, and shows output previews for recent jobs across classic history refs and asset-backed output refs through the same `/view` contract. | [Observability](#observability-read-only), [Remote Control (Connector)](#remote-control-connector) |
|
||||
| `Jobs` | Tracks prompt IDs, consumes deterministic event/task cursor metadata for polling, and shows output previews for recent jobs across classic history refs and asset-backed output refs through the same `/view` contract; refs that only expose asset-service identifiers stay explicit as an operator-visible fallback state instead of silently upgrading to `/api/assets`. | [Observability](#observability-read-only), [Remote Control (Connector)](#remote-control-connector) |
|
||||
| `Planner` | Uses assist endpoint to generate structured prompt plans (positive/negative/params). | [Configure an LLM key](#1-configure-an-llm-key-for-plannerrefinervision-helpers), [Nodes](#nodes) |
|
||||
| `Refiner` | Refines existing prompts with optional image context and issue/goal input. | [Configure an LLM key](#1-configure-an-llm-key-for-plannerrefinervision-helpers), [Nodes](#nodes) |
|
||||
| `Variants` | Local helper for generating batch variant parameter JSON (seed/range-style sweeps). | [Nodes](#nodes), [Operator UX Features](#operator-ux-features) |
|
||||
@@ -1038,6 +1050,7 @@ Operational notes:
|
||||
- Event and managed-download polling now expose deterministic cursor metadata so reconnect/backfill behavior can stay incremental instead of falling back to full-list refreshes on every poll.
|
||||
- Preflight inventory is snapshot-first: clients should treat `snapshot_ts`, `scan_state`, `stale`, and `last_error` as part of the normal operator-diagnostics contract.
|
||||
- Config/assist/model-management paths inherit the unified config precedence contract and SSRF-safe outbound policy.
|
||||
- Output/history-facing consumers should keep using the bounded `/history` + `/view` contract for supported preview flows; refs that are only representable through upstream asset APIs are surfaced explicitly as `asset_api_required` instead of being auto-fetched.
|
||||
- Connector installation diagnostics expose redacted token references only, never raw token material.
|
||||
- Webhook and rate-limit error paths expose machine-readable diagnostics; client integrations should consume codes and structured fields instead of free-form text.
|
||||
|
||||
@@ -1144,11 +1157,33 @@ Override:
|
||||
Logs:
|
||||
|
||||
- `openclaw.log` (legacy `moltbot.log` is still supported)
|
||||
- `audit.log` for append-only audit events, plus retained rotated audit segments when log retention is enabled
|
||||
- `audit.log.key` when OpenClaw generates and persists the local audit chain key instead of receiving one from environment/config
|
||||
- Optional startup truncation: set `OPENCLAW_LOG_TRUNCATE_ON_START=1` to clear the active log file once at process startup (useful to avoid stale-history noise in UI log views).
|
||||
- Optional structured JSON logs for selected core paths:
|
||||
- set `OPENCLAW_LOG_FORMAT=json` (or `OPENCLAW_STRUCTURED_LOGS=1`) before startup
|
||||
- default behavior remains plain text logs (no structured log emission unless opt-in)
|
||||
|
||||
## Audit Chain Verification
|
||||
|
||||
Operators can verify retained audit-log continuity with:
|
||||
|
||||
```bash
|
||||
python scripts/verify_audit_chain.py
|
||||
```
|
||||
|
||||
Machine-readable output:
|
||||
|
||||
```bash
|
||||
python scripts/verify_audit_chain.py --json
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- The verifier checks the current `audit.log` and any retained rotated audit segments in the state directory.
|
||||
- When OpenClaw is not given an audit chain key explicitly, it persists a local `audit.log.key` sidecar so retained-chain verification still works across restart and rotation.
|
||||
- A failed verification should be treated as an operator-facing integrity incident and investigated before assuming the retained audit trail is trustworthy.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Common operator issues now live in a dedicated troubleshooting guide:
|
||||
@@ -1159,6 +1194,8 @@ Quick jumps:
|
||||
|
||||
- backend not loaded / route 404 startup failures
|
||||
- Operator Doctor usage
|
||||
- Jobs preview fallback for asset-api-only output refs
|
||||
- audit chain verification after restart or rotation
|
||||
- webhook auth not configured
|
||||
- loopback LLM SSRF validation errors
|
||||
- Remote Admin vs private-LAN LLM target behavior
|
||||
|
||||
+18
-1
@@ -235,7 +235,7 @@ python scripts/check_deployment_profile.py --profile public --strict-warnings
|
||||
OpenClaw validates custom LLM `base_url` settings to prevent Server-Side Request Forgery (SSRF).
|
||||
|
||||
* **Default**: known providers and localhost-safe paths are allowed.
|
||||
* **Pinned connect contract**: on supported CPython versions (current baseline: 3.10+), `safe_io` dials resolved IPs directly for HTTP/HTTPS and keeps TLS `server_hostname` on the original host; the no-skip `tests.test_s70_ssrf_pinning_regression` lane is intended to fail loudly if stdlib connect behavior drifts.
|
||||
* **Pinned connect contract**: on supported CPython versions (current baseline: 3.10+), the consolidated `safe_io` outbound executor dials resolved IPs directly for HTTP/HTTPS and keeps TLS `server_hostname` on the original host; the no-skip `tests.test_s70_ssrf_pinning_regression` lane is intended to fail loudly if stdlib connect behavior drifts.
|
||||
* **Custom base URL**:
|
||||
- requires explicit opt-in:
|
||||
|
||||
@@ -255,6 +255,22 @@ OpenClaw validates custom LLM `base_url` settings to prevent Server-Side Request
|
||||
- wildcard values such as `OPENCLAW_LLM_ALLOWED_HOSTS="*"` are not supported.
|
||||
- avoid broad bypass flags in production (`OPENCLAW_ALLOW_ANY_PUBLIC_LLM_HOST`, `OPENCLAW_ALLOW_INSECURE_BASE_URL`).
|
||||
|
||||
### 6.1 Audit Chain Verification
|
||||
|
||||
OpenClaw keeps append-only audit evidence verifiable across restart and retained-log rotation.
|
||||
|
||||
Recommended operator check:
|
||||
|
||||
```bash
|
||||
python scripts/verify_audit_chain.py --json
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- verification covers the active `audit.log` plus retained rotated segments in the state directory
|
||||
- when an audit chain key is not supplied externally, OpenClaw persists a local `audit.log.key` sidecar so the retained chain stays verifiable after restart
|
||||
- treat any verification failure as an integrity incident and investigate before trusting the retained audit trail
|
||||
|
||||
### 7. Rate Limiting
|
||||
|
||||
OpenClaw enforces internal rate limits:
|
||||
@@ -283,6 +299,7 @@ OpenClaw supports a "Sidecar Bridge" (F10) for safe interaction with external bo
|
||||
* [ ] **Public path deny rules**: block ComfyUI-native high-risk routes and `/api/*` equivalents unless explicitly required.
|
||||
* [ ] **Connector strict-posture allowlists**: if connector ingress is active in `public` or `hardened`, ensure platform allowlists are set before startup (`DP-PUBLIC-009` for public profile).
|
||||
* [ ] **Multi-tenant boundary (if enabled)**: enforce one canonical tenant header path through proxy/app, keep fallback toggles disabled unless a migration window is actively in progress.
|
||||
* [ ] **Audit integrity check**: run `python scripts/verify_audit_chain.py --json` after restart/rotation-sensitive maintenance and confirm retained audit logs still verify cleanly.
|
||||
* [ ] **1Password guardrails (if enabled)**: require command allowlist + vault/template validation; in multi-tenant mode, include `{tenant}` in item template.
|
||||
* [ ] **Startup gate preflight**: run `python scripts/check_deployment_profile.py --profile public --strict-warnings`.
|
||||
* [ ] **Runtime diagnostics**: review `GET /openclaw/security/doctor` before exposure.
|
||||
|
||||
@@ -14,7 +14,7 @@ This document summarizes the current OpenClaw sidebar UI structure and how to ve
|
||||
- Tabs: `web/openclaw_tabs.js` manages tab registration, rendering, and remount safety.
|
||||
- API: `web/openclaw_api.js` provides a normalized fetch wrapper and OpenClaw endpoints (legacy Moltbot endpoints still work).
|
||||
- Host surface: `web/openclaw_host_surface.js` resolves the active frontend host surface and stamps explicit metadata so standalone frontend vs desktop-embedded behavior stays testable.
|
||||
- Output refs: `web/openclaw_asset_refs.js` normalizes classic history refs and newer asset-backed output refs onto the same bounded `/view` preview contract.
|
||||
- Output refs: `web/openclaw_asset_refs.js` normalizes classic history refs and newer asset-backed output refs onto the same bounded `/view` preview contract, while keeping asset-service-only refs explicit as a fallback state instead of silently auto-fetching `/api/assets`.
|
||||
- Styles: `web/openclaw.css` provides shared design tokens and component classes.
|
||||
- Errors and compatibility helpers: `web/openclaw_utils.js` provides `showError()` / `clearError()` plus runtime legacy-class alias helpers used to keep canonical `openclaw-*` markup compatible with existing `moltbot-*` selectors.
|
||||
|
||||
@@ -23,7 +23,7 @@ Refactor note:
|
||||
- New shell behaviors should prefer the extracted action/queue modules unless they truly belong to top-level shell assembly.
|
||||
- New tab markup should use canonical `openclaw-*` classes; legacy `moltbot-*` aliases are generated centrally at runtime instead of being duplicated in each template.
|
||||
- Host-sensitive behaviors should consume the shared host-surface helper rather than inferring desktop vs standalone frontend from ad-hoc globals.
|
||||
- Output preview flows should consume the shared asset-ref normalizer rather than assembling `/view` URLs independently in each tab.
|
||||
- Output preview flows should consume the shared asset-ref normalizer rather than assembling `/view` URLs independently in each tab or silently widening runtime behavior to direct `/api/assets` fetches.
|
||||
- Explorer/preflight consumers should treat inventory diagnostics as snapshot-first and surface `snapshot_ts`, `scan_state`, `stale`, and `last_error` instead of blocking the UI on full rescans.
|
||||
|
||||
## Feature Gating (Capabilities)
|
||||
@@ -81,7 +81,7 @@ If `assist_streaming` is unavailable or the stream transport degrades, Planner/R
|
||||
3. Confirm the sidebar host-surface metadata resolves correctly for the current environment instead of defaulting silently.
|
||||
4. Planner: click **Plan Generation** with minimal input and confirm either live preview/stage updates appear (when streaming is supported) or a readable fallback result/error appears.
|
||||
5. Refiner: click **Refine Prompts** (with or without image) and confirm either live preview/stage updates appear (when streaming is supported) or a readable fallback result/error appears.
|
||||
6. Jobs: verify output previews still resolve for both classic history refs and any asset-backed refs surfaced by callback/history payloads, and that repeated polls do not duplicate rows after reconnect/resume.
|
||||
6. Jobs: verify output previews still resolve for both classic history refs and any asset-backed refs surfaced by callback/history payloads, that asset-service-only refs stay explicit as a bounded fallback state, and that repeated polls do not duplicate rows after reconnect/resume.
|
||||
7. Explorer: verify preflight inventory can show `refreshing` / `stale` / `error` state without freezing the tab while deep scan work continues.
|
||||
8. Library/Approvals: if backend endpoints are not enabled, confirm the UI shows a clear error state (no crashes).
|
||||
9. If you simulate/fake a stream failure in dev tools, confirm Planner/Refiner retry through the classic non-stream path without duplicate submits or broken loading state.
|
||||
|
||||
@@ -44,6 +44,7 @@
|
||||
- [ ] For `OPENCLAW_DEPLOYMENT_PROFILE=public`, set `OPENCLAW_PUBLIC_SHARED_SURFACE_BOUNDARY_ACK=1` only after reverse-proxy path allowlist + network ACL explicitly block ComfyUI-native high-risk routes.
|
||||
- [ ] For `OPENCLAW_DEPLOYMENT_PROFILE=public`, if any connector platform token/enable flag is set, confirm corresponding allowlist coverage before startup (`DP-PUBLIC-009`).
|
||||
- [ ] Run `GET /openclaw/security/doctor` and verify no `csrf_no_origin_override` warning before exposure.
|
||||
- [ ] Run `python scripts/verify_audit_chain.py --json` after restart/rotation-sensitive maintenance and confirm retained audit logs still verify cleanly.
|
||||
|
||||
### 6. Debug Mode
|
||||
|
||||
|
||||
@@ -44,6 +44,38 @@ Explorer / inventory note:
|
||||
- A response showing `scan_state=refreshing` or `stale=true` does not necessarily mean the inventory path is broken; it can mean the cached snapshot was returned quickly while a deeper model scan continues in the background.
|
||||
- Treat `last_error` as the primary signal that the background scan actually failed.
|
||||
|
||||
## Jobs preview shows an explicit asset fallback state instead of an image preview
|
||||
|
||||
Current OpenClaw builds keep `/history` + `/view` as the supported runtime preview contract for job results.
|
||||
|
||||
If a result ref only exposes an upstream asset-service identifier and cannot be represented through `/view`, OpenClaw keeps that ref explicit instead of silently guessing a direct `/api/assets` fetch.
|
||||
|
||||
What this means:
|
||||
|
||||
- `asset_api_required` is a bounded compatibility state, not a generic parser failure.
|
||||
- Classic history refs and hash-backed refs that still map onto `/view` should continue to preview normally.
|
||||
- If an operator workflow starts depending on direct asset-service identifiers, treat that as a contract gap and review [`docs/r167_asset_api_adoption_decision.md`](r167_asset_api_adoption_decision.md) before widening the runtime dependency.
|
||||
|
||||
## Verify audit-chain continuity after restart or rotation
|
||||
|
||||
Use the retained-chain verifier:
|
||||
|
||||
```bash
|
||||
python scripts/verify_audit_chain.py
|
||||
```
|
||||
|
||||
JSON output:
|
||||
|
||||
```bash
|
||||
python scripts/verify_audit_chain.py --json
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- The verifier checks the current `audit.log` and any retained rotated audit segments in the state directory.
|
||||
- When no audit chain key is supplied from environment/config, OpenClaw persists `audit.log.key` so verification still works across restart and rotation.
|
||||
- Treat verification failure as an audit-integrity incident until proven otherwise.
|
||||
|
||||
## Webhooks return `403 auth_not_configured`
|
||||
|
||||
Set webhook auth environment variables as described in the README quick-start section, then restart ComfyUI.
|
||||
|
||||
Reference in New Issue
Block a user