mirror of
https://github.com/rookiestar28/ComfyUI-OpenClaw.git
synced 2026-08-14 00:48:07 +00:00
docs: refresh public runtime and security documentation
This commit is contained in:
rookiestar28
@@ -70,7 +70,7 @@ This project is designed to make **ComfyUI a reliable automation target** with a
|
||||
- Secret handling stays server-side: browser storage is not used for secrets, local secret-manager integration is opt-in, and secrets-at-rest / token lifecycle controls are treated as operational boundaries.
|
||||
- Multi-tenant mode is isolation-first: tenant mismatches fail closed across config, secret sources, connector installations, approvals, visibility, and execution budgets.
|
||||
- Connector multi-workspace and multi-account bindings are secret-ref-only and fail-closed by design, so tenant/binding mismatches degrade to explicit rejection paths instead of silently reusing the wrong installation context.
|
||||
- Operator-facing payloads default to redaction for provider reasoning-like content, while audit trails, diagnostics, and runtime guardrails remain explicit and tamper-evident.
|
||||
- Operator-facing and audit payloads default to redaction for provider reasoning-like content and explicitly marked internal maintenance/helper prompt material, while diagnostics and runtime guardrails remain explicit and tamper-evident.
|
||||
- Verification is part of the security model: route drift checks, coverage governance, adversarial gates, and doctor/compatibility diagnostics are all wired into CI-parity workflows.
|
||||
|
||||
Deployment profiles and hardening references:
|
||||
@@ -79,7 +79,7 @@ Deployment profiles and hardening references:
|
||||
- [Security Checklist](docs/security_checklist.md)
|
||||
- [Runtime Hardening and Startup](docs/runtime_hardening_and_startup.md)
|
||||
- [Threat Model](docs/release/threat_model.md)
|
||||
- [R69 Frontend Migration Decision](docs/r69_ui_framework_migration_decision.md)
|
||||
- [Frontend Migration Decision](docs/r69_ui_framework_migration_decision.md)
|
||||
|
||||
</details>
|
||||
|
||||
@@ -89,6 +89,16 @@ Deployment profiles and hardening references:
|
||||
|
||||
<details>
|
||||
|
||||
<summary><strong>Startup lifecycle diagnostics, connector SecretRef service boundaries, and internal prompt isolation aligned with the current runtime</strong></summary>
|
||||
|
||||
- Health diagnostics now distinguish required startup readiness, optional warmup degradation, and fatal startup failures; optional warmups run after route registration and no longer block baseline API availability.
|
||||
- Connector/service launch planning now has a secret-blind env-backed SecretRef boundary that preserves supported connector credential references without expanding raw token values, while rejecting raw secrets, legacy marker strings, unsupported envs, and runtime-only auth tokens.
|
||||
- Operator-visible and audit payload sanitization now removes explicitly marked internal maintenance/helper prompt content before normal reasoning redaction, while leaving ordinary user text intact.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary><strong>Host compatibility anchors and inactive-branch preflight diagnostics aligned with current ComfyUI hosts</strong></summary>
|
||||
|
||||
- Refreshed the published compatibility matrix for current ComfyUI, standalone frontend, and desktop reference anchors, keeping desktop embedded-frontend lag explicit instead of assuming standalone-frontend parity.
|
||||
@@ -134,17 +144,6 @@ Deployment profiles and hardening references:
|
||||
|
||||
</details>
|
||||
|
||||
<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>
|
||||
|
||||
See full update history: [docs/release/recent_updates.md](docs/release/recent_updates.md)
|
||||
|
||||
</details>
|
||||
@@ -212,7 +211,7 @@ Notes:
|
||||
|
||||
- Recommended: set API keys via environment variables.
|
||||
- Optional: for single-user localhost setups, you can store a provider API key from the Settings tab (UI Key Store (Advanced)).
|
||||
- This writes to the server-side secret store (`{STATE_DIR}/secrets.json`).
|
||||
- This writes to the encrypted server-side secret store (`{STATE_DIR}/secrets.enc.json`).
|
||||
- Environment variables always take priority over stored keys.
|
||||
- Built-in local-provider defaults use loopback-only OpenAI-compatible URLs:
|
||||
- `Ollama (Local)` -> `http://127.0.0.1:11434/v1`
|
||||
@@ -469,7 +468,7 @@ Main API families:
|
||||
- Observability: health, capabilities, logs, traces, event feeds
|
||||
- Admin diagnostics: preflight inventory snapshot/status, doctor-facing readiness views
|
||||
- Config + LLM: effective config, provider tests, model lists, assist planner/refiner
|
||||
- Connector diagnostics: installation state, resolution, callback/tenant binding evidence, audit views, and extraction seam metadata
|
||||
- Connector diagnostics: installation state, resolution, callback/tenant binding evidence, audit views, extraction seam metadata, and static service-env SecretRef propagation policy
|
||||
- Webhooks + events: validate, submit, callback delivery, SSE/polling status
|
||||
- Admin operations: approvals, schedules, presets, rewrite recipes
|
||||
- Model Manager + Packs: search, download/import lifecycle, pack import/export
|
||||
@@ -485,10 +484,10 @@ Primary references:
|
||||
|
||||
Key operational notes:
|
||||
|
||||
- Observability remains token-gated for remote access and redacts provider reasoning-like content by default.
|
||||
- Observability remains token-gated for remote access and redacts provider reasoning-like content plus marked internal maintenance/helper content by default.
|
||||
- Event/model-download polling and preflight inventory are snapshot/cursor-driven contracts; clients should consume `snapshot_ts`, `scan_state`, `stale`, and cursor metadata instead of assuming full-refresh polling.
|
||||
- Output/history-facing consumers should keep using the bounded `/history` + `/view` contract; refs that only upstream asset services can resolve remain explicit `asset_api_required` compatibility states.
|
||||
- Connector diagnostics expose redacted token references only, and `/openclaw/connector/extraction-contract` is structural packaging metadata rather than a live installation-health feed.
|
||||
- Connector diagnostics expose redacted token references only, and `/openclaw/connector/extraction-contract` is structural packaging metadata and static SecretRef policy rather than a live installation-health, environment, or token-status feed.
|
||||
|
||||
## Advanced Security and Runtime Setup
|
||||
|
||||
@@ -676,7 +675,10 @@ The connector currently remains an **optional attached subsystem inside this rep
|
||||
- **Slack multi-workspace and interactive mode**: Workspace installs can be handled through connector-managed OAuth install/callback routes with per-workspace token binding, fail-closed health diagnostics, and signed interactive callback handling for action payloads.
|
||||
- **Feishu/Lark multi-account mode**: Connector-managed account/workspace bindings support tenant-aware installation resolution, interactive approval cards, and signed callback handling without exposing raw app secrets or widening command trust implicitly.
|
||||
- **Bounded connector numeric envs**: Delivery/media/time-budget settings, bind ports, rate limits, and command-length knobs now clamp or fall back to documented defaults with warnings instead of crashing connector startup on malformed values.
|
||||
- **Packaging diagnostics**: Admin operators/maintainers can inspect `/openclaw/connector/extraction-contract` for the current in-repo recommendation plus the minimum seam families required before any future split.
|
||||
- **Startup diagnostics**: `/openclaw/health` reports startup readiness, optional warmup degradation, and fatal startup details without making optional warmups block baseline API availability.
|
||||
- **SecretRef service boundaries**: Connector service-env planning preserves only supported env-backed credential references and rejects raw secrets, legacy marker strings, unsupported envs, and runtime-only auth tokens.
|
||||
- **Internal prompt isolation**: Operator-visible and audit payloads remove explicitly marked internal maintenance/helper prompt content before normal reasoning redaction.
|
||||
- **Packaging diagnostics**: Admin operators/maintainers can inspect `/openclaw/connector/extraction-contract` for the current in-repo recommendation, the static service-env SecretRef propagation policy, and the minimum seam families required before any future split.
|
||||
|
||||
- [See Setup Guide (`docs/connector.md`)](docs/connector.md)
|
||||
|
||||
|
||||
+14
-9
@@ -2,9 +2,9 @@
|
||||
|
||||
## Quick Links
|
||||
|
||||
- Deployment profiles and checklists: [Security Deployment Guide](docs/security_deployment_guide.md)
|
||||
- Runtime startup hardening behavior: [Runtime Hardening and Startup](docs/runtime_hardening_and_startup.md)
|
||||
- Pre-exposure checklist: [Security Checklist](docs/security_checklist.md)
|
||||
- Deployment profiles and checklists: [Security Deployment Guide](security_deployment_guide.md)
|
||||
- Runtime startup hardening behavior: [Runtime Hardening and Startup](runtime_hardening_and_startup.md)
|
||||
- Pre-exposure checklist: [Security Checklist](security_checklist.md)
|
||||
- Deployment self-check command:
|
||||
- `python scripts/check_deployment_profile.py --profile local|lan|public`
|
||||
|
||||
@@ -21,7 +21,7 @@ Only the latest version of ComfyUI-OpenClaw is supported for security updates.
|
||||
|
||||
Please report security vulnerabilities by creating a **private** issue on GitHub if possible, or contact the maintainers directly. Do not open public issues for sensitive security flaws.
|
||||
|
||||
### Disclosure Workflow and SLA (S48)
|
||||
### Disclosure Workflow and SLA
|
||||
|
||||
Private reporting workflow:
|
||||
1. Submit a private report with repro steps, affected version, and impact.
|
||||
@@ -103,15 +103,20 @@ export OPENCLAW_ADMIN_TOKEN="your-secure-random-admin-token-here"
|
||||
|
||||
Then configure your proxy or client to send the header `X-OpenClaw-Obs-Token: your-secure-random-token-here` (legacy: `X-Moltbot-Obs-Token`).
|
||||
|
||||
### 1.1 Reasoning Debug Reveal Boundary (Local-only)
|
||||
### 1.1 Reasoning and Internal Content Redaction Boundary
|
||||
|
||||
Operator-facing payloads strip provider reasoning / thinking traces by default across:
|
||||
Operator-facing payloads strip provider reasoning / thinking traces and explicitly marked internal maintenance/helper prompt content by default across:
|
||||
|
||||
- assist responses
|
||||
- event / SSE payloads
|
||||
- trace responses
|
||||
- callback payloads
|
||||
- connector trace/debug replies
|
||||
- audit event payload/meta fields
|
||||
|
||||
Internal maintenance/helper prompt content has no public or debug reveal path. Privileged reasoning reveal is limited to provider reasoning / thinking traces only.
|
||||
|
||||
### 1.2 Reasoning Debug Reveal Boundary (Local-only)
|
||||
|
||||
There is a privileged local-debug reveal path for troubleshooting, but it is fail-closed unless **all** of the following are true:
|
||||
|
||||
@@ -142,7 +147,7 @@ export OPENCLAW_TRUSTED_PROXIES="127.0.0.1,10.0.0.0/8"
|
||||
# export MOLTBOT_TRUSTED_PROXIES="127.0.0.1,10.0.0.0/8"
|
||||
```
|
||||
|
||||
### 3. Public Profile Boundary Acknowledgement (S69)
|
||||
### 3. Public Profile Boundary Acknowledgement
|
||||
|
||||
For public profile deployments, you must explicitly acknowledge that reverse-proxy path controls and network ACL boundaries are already enforced:
|
||||
|
||||
@@ -220,7 +225,7 @@ Operational note:
|
||||
|
||||
- this path remains backend-only; frontend surfaces stay secret-blind.
|
||||
|
||||
### 5. Startup Gate Behavior (R136 + S56)
|
||||
### 5. Startup Gate Behavior
|
||||
|
||||
Startup security gates are fail-closed. Fatal startup gate/bootstrap failures abort route/worker registration and do not continue in a partial state.
|
||||
|
||||
@@ -283,7 +288,7 @@ OpenClaw enforces internal rate limits:
|
||||
|
||||
### 8. Sidecar Bridge
|
||||
|
||||
OpenClaw supports a "Sidecar Bridge" (F10) for safe interaction with external bots (Discord/Slack).
|
||||
OpenClaw supports a "Sidecar Bridge" for safe interaction with external bots (Discord/Slack).
|
||||
|
||||
* **Default**: **DISABLED**.
|
||||
* **Enable**: Set `OPENCLAW_BRIDGE_ENABLED=1` (legacy `MOLTBOT_BRIDGE_ENABLED=1`).
|
||||
|
||||
@@ -45,6 +45,7 @@ Admin diagnostics APIs:
|
||||
Extraction diagnostics note:
|
||||
|
||||
- `/openclaw/connector/extraction-contract` is an admin-only structural metadata route for maintainers and operators. It returns the current packaging recommendation, candidate extraction options, seam families, and blockers, but it does **not** expose live token or installation-state details beyond the existing diagnostics routes above.
|
||||
- The extraction contract also includes the static service-env SecretRef propagation policy. It is not a live environment dump and does not expose token values.
|
||||
|
||||
Slack multi-workspace notes:
|
||||
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# OpenClaw API Contract (v1)
|
||||
|
||||
> **Status**: normative
|
||||
> **Version**: 1.0.8
|
||||
> **Date**: 2026-04-26
|
||||
> **Version**: 1.0.9
|
||||
> **Date**: 2026-04-28
|
||||
|
||||
This document defines the public API contract for OpenClaw. It serves as the authoritative baseline for client compatibility and breaking change policies.
|
||||
|
||||
## 0. Tenant Boundary Context (S49)
|
||||
## 0. Tenant Boundary Context
|
||||
|
||||
Default behavior remains single-tenant compatible (`tenant_id=default`).
|
||||
|
||||
@@ -51,7 +51,8 @@ All new integrations should use the `/openclaw/` prefix. Use of `/moltbot/` is d
|
||||
|
||||
Reasoning-content redaction contract:
|
||||
|
||||
- operator-visible trace and events payloads strip provider reasoning / thinking-like fields by default
|
||||
- operator-visible trace and events payloads strip provider reasoning / thinking-like fields and explicitly marked internal maintenance/helper content by default
|
||||
- audit event payload/meta fields follow the same internal-content and reasoning-like redaction boundary before retention
|
||||
- privileged reveal is opt-in only and requires:
|
||||
- request header `X-OpenClaw-Debug-Reveal-Reasoning: 1` or query `debug_reasoning=1`
|
||||
- server-side enablement via `OPENCLAW_DEBUG_REASONING_REVEAL=1`
|
||||
@@ -60,6 +61,7 @@ Reasoning-content redaction contract:
|
||||
- non-hardened runtime profile
|
||||
- deployment profile `local` or `lan`
|
||||
- clients MUST treat reveal behavior as debug-only and MUST NOT depend on reasoning payload presence in normal operation
|
||||
- explicitly marked internal maintenance/helper content has no public or debug reveal path
|
||||
|
||||
Inventory diagnostics contract:
|
||||
|
||||
@@ -98,8 +100,9 @@ Preflight workflow diagnostics contract:
|
||||
|
||||
Assist payload redaction contract:
|
||||
|
||||
- structured assist responses preserve final operator-visible answer fields but strip provider reasoning / chain-of-thought style fields by default
|
||||
- structured assist responses preserve final operator-visible answer fields but strip provider reasoning / chain-of-thought style fields and explicitly marked internal maintenance/helper content by default
|
||||
- when the privileged reveal gate is allowed, debug reasoning is exposed only in a separate debug payload and not merged back into the normal structured answer fields
|
||||
- explicitly marked internal maintenance/helper content is not exposed by the privileged reasoning reveal gate
|
||||
|
||||
### 1.3B Connector Installation Diagnostics
|
||||
|
||||
@@ -112,13 +115,13 @@ Assist payload redaction contract:
|
||||
| `GET` | `/connector/installations/{installation_id}` | `/moltbot/connector/installations/{installation_id}` | Admin | Get one redacted connector installation record. |
|
||||
| `GET` | `/connector/installations/resolve` | `/moltbot/connector/installations/resolve` | Admin | Run fail-closed workspace resolution diagnostics (`platform`, `workspace_id`). |
|
||||
| `GET` | `/connector/installations/audit` | `/moltbot/connector/installations/audit` | Admin | List installation lifecycle audit evidence (redacted). |
|
||||
| `GET` | `/connector/extraction-contract` | `/moltbot/connector/extraction-contract` | Admin | Get the machine-readable connector extraction recommendation, seam families, and current blockers. |
|
||||
| `GET` | `/connector/extraction-contract` | `/moltbot/connector/extraction-contract` | Admin | Get the machine-readable connector extraction recommendation, seam families, static service-env SecretRef propagation policy, and current blockers. |
|
||||
|
||||
Connector diagnostics contract notes:
|
||||
- installation records may expose operator-safe health metadata under `installation.metadata.health` (for example `ok`, `invalid_token`, `revoked`, `degraded`) without exposing token material
|
||||
- `/connector/installations` diagnostics may include aggregate `health_counts` in addition to lifecycle `status_counts`
|
||||
- `/connector/installations/resolve` may expose a stable `health_code` alongside the legacy `reject_reason` so clients can distinguish `workspace_unbound` vs token-health failures without parsing status text
|
||||
- `/connector/extraction-contract` is structural packaging metadata only; clients MUST NOT treat it as a live installation-health or token-status feed
|
||||
- `/connector/extraction-contract` is structural packaging metadata and static service-env SecretRef policy only; clients MUST NOT treat it as a live installation-health, live environment dump, or token-status feed
|
||||
|
||||
### 1.3C Model Management & Installations
|
||||
|
||||
@@ -260,7 +263,7 @@ Tenant-boundary error notes:
|
||||
- `error`
|
||||
- `keepalive`
|
||||
- Clients MUST treat `final` as the source of truth for structured assist results. `delta` preview text is best-effort and may be truncated or differ from the final parsed payload.
|
||||
- Event-stream and polling payloads redact provider reasoning / thinking traces by default; reveal is debug-only and gated by the same privileged local-debug contract used by trace/assist surfaces.
|
||||
- Event-stream and polling payloads redact provider reasoning / thinking traces and explicitly marked internal maintenance/helper content by default; reasoning reveal is debug-only and gated by the same privileged local-debug contract used by trace/assist surfaces.
|
||||
- Clients SHOULD gracefully fall back to non-streaming assist endpoints when streaming capability is absent or streaming transport fails.
|
||||
|
||||
### 2.4 Pagination & Scan Diagnostics (Management Query Contract)
|
||||
|
||||
@@ -31,7 +31,7 @@ Controls the core LLM client used by nodes (Planner, Refiner, etc.).
|
||||
| `OPENCLAW_LLM_BASE_URL` | No | Provider default | Override base URL (crucial for local/compatible providers). |
|
||||
| `OPENCLAW_LLM_TIMEOUT`| No | `120` | Request timeout in seconds. |
|
||||
|
||||
Optional local secret-manager path (S11, disabled by default):
|
||||
Optional local secret-manager path (disabled by default):
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
@@ -167,6 +167,7 @@ Connector posture rules:
|
||||
- Public deployment profile check surfaces this as `DP-PUBLIC-009`.
|
||||
- Slack multi-workspace installs persist only encrypted token refs in `connector_installations.json`; raw bot/app tokens remain in encrypted secret storage and must not appear in diagnostics or exported config surfaces.
|
||||
- Feishu/Lark bindings persist normalized installation identity plus secret references only; app secrets and callback signing material must stay in encrypted/local secret storage and must not appear in diagnostics or exported config surfaces.
|
||||
- Connector service-env propagation preserves only structured env-backed SecretRef metadata for supported connector credential variables. It reports secret-blind status/reason fields and rejects raw secrets, legacy marker strings, unsupported env names, missing envs, and runtime-only auth tokens such as admin, worker, and bridge tokens. Raw token values must not be written into diagnostics or service metadata.
|
||||
- Connector bind-port envs (`OPENCLAW_CONNECTOR_LINE_PORT`, `...WHATSAPP_PORT`, `...WECHAT_PORT`, `...KAKAO_PORT`, `...SLACK_PORT`, `...FEISHU_PORT`) must stay within `1..65535`; invalid or out-of-range values fall back to the documented platform defaults instead of crashing startup.
|
||||
|
||||
**Delivery & Media:**
|
||||
|
||||
@@ -7,6 +7,16 @@ Newest entries appear first.
|
||||
|
||||
<details>
|
||||
|
||||
<summary><strong>Startup lifecycle diagnostics, connector SecretRef service boundaries, and internal prompt isolation aligned with the current runtime</strong></summary>
|
||||
|
||||
- Health diagnostics now distinguish required startup readiness, optional warmup degradation, and fatal startup failures; optional warmups run after route registration and no longer block baseline API availability.
|
||||
- Connector/service launch planning now has a secret-blind env-backed SecretRef boundary that preserves supported connector credential references without expanding raw token values, while rejecting raw secrets, legacy marker strings, unsupported envs, and runtime-only auth tokens.
|
||||
- Operator-visible and audit payload sanitization now removes explicitly marked internal maintenance/helper prompt content before normal reasoning redaction, while leaving ordinary user text intact.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary><strong>Host compatibility anchors and inactive-branch preflight diagnostics aligned with current ComfyUI hosts</strong></summary>
|
||||
|
||||
- Refreshed the published compatibility matrix for current ComfyUI, standalone frontend, and desktop reference anchors, keeping desktop embedded-frontend lag explicit instead of assuming standalone-frontend parity.
|
||||
|
||||
@@ -18,7 +18,7 @@ Operators should use this to understand the risks of deployment.
|
||||
* **Access**: Read-only logs (`/openclaw/logs/tail`), config (`/openclaw/config`), health.
|
||||
* **Mechanism**: `OPENCLAW_OBSERVABILITY_TOKEN`.
|
||||
* **Redaction**: Logs/Config are redacted by default to prevent secret leakage.
|
||||
* **Reasoning-content posture**: provider reasoning / thinking traces are stripped by default from operator-visible assist responses, event streams, trace responses, callback payloads, and connector trace replies; privileged reveal is local-debug only, admin-gated, auditable, and fail-closed outside permissive local posture.
|
||||
* **Reasoning/internal-content posture**: provider reasoning / thinking traces and explicitly marked internal maintenance/helper prompt content are stripped by default from operator-visible assist responses, event streams, trace responses, callback payloads, connector trace replies, and audit event payload/meta fields. Privileged reasoning reveal is local-debug only, admin-gated, auditable, and fail-closed outside permissive local posture; internal maintenance/helper prompt content has no public or debug reveal path.
|
||||
|
||||
### 3. The "Connector" Boundary (ChatOps)
|
||||
|
||||
@@ -50,7 +50,7 @@ Operators should use this to understand the risks of deployment.
|
||||
* *Mitigation*: Known-host allowlist by default. Custom URLs need explicit opt-in + DNS validation.
|
||||
* **Callback Delivery**: `POST` results to webhook targets.
|
||||
* *Risk*: SSRF / Information Leakage.
|
||||
* *Mitigation*: DNS-safe validation (no private IPs) + operator-payload redaction, including reasoning-content stripping by default.
|
||||
* *Mitigation*: DNS-safe validation (no private IPs) + operator-payload redaction, including reasoning/internal-content stripping by default.
|
||||
* **Image Fetching**: `image_url` inputs.
|
||||
* *Mitigation*: SafeIO module (size limits, no file://).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user