mirror of
https://github.com/rookiestar28/ComfyUI-OpenClaw.git
synced 2026-08-14 00:48:07 +00:00
update docs
This commit is contained in:
@@ -6,6 +6,7 @@ ComfyUI-OpenClaw is a **security-first orchestration layer** for ComfyUI that co
|
||||
|
||||
- **LLM-assisted nodes** (planner/refiner/vision/batch variants)
|
||||
- **A built-in extension UI** (`OpenClaw` panel)
|
||||
- **A standalone Remote Admin Console** (`/openclaw/admin`) for mobile/remote browser operations
|
||||
- **A secure-by-default HTTP API** for automation (webhooks, triggers, schedules, approvals, presets)
|
||||
- **Public-ready control-plane split architecture** (embedded UX + externalized high-risk control surfaces)
|
||||
- **Verification-first hardening lanes** (route drift, real-backend E2E, adversarial fuzz/mutation gates)
|
||||
@@ -54,6 +55,35 @@ Deployment profiles and hardening checklists:
|
||||
|
||||
<details>
|
||||
|
||||
<summary><strong>Standalone remote admin mobile console for phone/desktop operations</strong></summary>
|
||||
|
||||
- Added an independent remote admin entry page at `/openclaw/admin` (legacy `/moltbot/admin`), separate from the ComfyUI side panel.
|
||||
- Added a mobile-first admin console layout for operational flows:
|
||||
- dashboard (health, provider/key state, scheduler/runs summary, recent error lines)
|
||||
- jobs/events (recent runs + SSE connect/poll fallback)
|
||||
- approvals (approve/reject)
|
||||
- schedules/triggers (toggle/run/fire)
|
||||
- config (read + guarded write)
|
||||
- doctor/diagnostics and quick actions (retry/model refresh/drill via existing policy gates)
|
||||
- Preserved backend security boundaries: remote write actions still require explicit admin-token and remote-admin policy conditions.
|
||||
- Completed full verification gate pass (detect-secrets, pre-commit, backend unit suites, and frontend Playwright E2E).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary><strong>Executor lane split and callback I/O isolation for better saturation resilience</strong></summary>
|
||||
|
||||
- Added dedicated executor lanes for LLM vs I/O workloads with bounded worker controls.
|
||||
- Migrated callback delivery and outbound HTTP callback paths to the I/O lane, reducing interference with LLM execution paths.
|
||||
- Added queue/saturation diagnostics and executor metrics exposure in health/stat telemetry.
|
||||
- Added targeted regression coverage for lane split behavior and callback I/O lane migration.
|
||||
- Completed full verification gate pass (detect-secrets, pre-commit, backend unit suites, and frontend Playwright E2E).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary><strong>Runtime lifecycle consistency, structured logging opt-in, and generated OpenAPI spec</strong></summary>
|
||||
|
||||
- Completed a focused runtime operability and contract maturity batch with full SOP verification:
|
||||
@@ -353,6 +383,11 @@ Deployment profiles and hardening checklists:
|
||||
- [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)
|
||||
- [Remote Admin Console (Mobile UI)](#remote-admin-console-mobile-ui)
|
||||
- [Environment variables for remote admin](#environment-variables-for-remote-admin)
|
||||
- [Connection from phone or other devices](#connection-from-phone-or-other-devices)
|
||||
- [Basic operations](#basic-operations)
|
||||
- [Reverse proxy and exposure notes](#reverse-proxy-and-exposure-notes)
|
||||
- [Nodes](#nodes)
|
||||
- [Extension UI](#extension-ui)
|
||||
- [Sidebar Modules](#sidebar-modules)
|
||||
@@ -447,6 +482,72 @@ Remote admin actions are denied by default. If you understand the risk and need
|
||||
- Portable `.bat` launchers: add `set OPENCLAW_LLM_API_KEY=...` / `set OPENCLAW_ADMIN_TOKEN=...` before launching ComfyUI.
|
||||
- ComfyUI Desktop: if env vars are not passed through reliably, prefer the Settings UI key store for localhost-only convenience, or set system-wide env vars.
|
||||
|
||||
## Remote Admin Console (Mobile UI)
|
||||
|
||||
The project now includes a standalone admin UI endpoint for mobile/remote operations:
|
||||
|
||||
- primary: `/openclaw/admin`
|
||||
- legacy alias: `/moltbot/admin`
|
||||
|
||||
This page is independent from the embedded ComfyUI side panel and is intended for phone/desktop browsers.
|
||||
|
||||
### Environment variables for remote admin
|
||||
|
||||
Recommended baseline before enabling remote administration:
|
||||
|
||||
- `OPENCLAW_ADMIN_TOKEN=<strong-secret>`
|
||||
- required for authenticated write/admin operations from remote devices
|
||||
- `OPENCLAW_ALLOW_REMOTE_ADMIN=1`
|
||||
- explicit opt-in for remote admin write paths
|
||||
- `OPENCLAW_OBSERVABILITY_TOKEN=<strong-secret>` (recommended)
|
||||
- tokenized read access for observability routes in non-localhost scenarios
|
||||
|
||||
Optional but commonly used with planner/refiner workflows:
|
||||
|
||||
- `OPENCLAW_LLM_API_KEY=<provider-key>` (or provider-specific key vars)
|
||||
|
||||
### Connection from phone or other devices
|
||||
|
||||
1. Start ComfyUI with external listen enabled (example):
|
||||
- `python main.py --listen 0.0.0.0 --port 8200`
|
||||
2. Use your host LAN IP (for example `192.168.x.x`) and open:
|
||||
- `http://<HOST_LAN_IP>:<PORT>/openclaw/admin`
|
||||
3. Enter the admin token in the page input and click `Save`.
|
||||
4. Click `Refresh All` to verify health and API reachability.
|
||||
|
||||
Notes:
|
||||
|
||||
- On Windows, if a port fails with bind errors (for example WinError 10013), choose a different port outside excluded ranges.
|
||||
- If write actions are denied remotely, verify both `OPENCLAW_ADMIN_TOKEN` and `OPENCLAW_ALLOW_REMOTE_ADMIN=1`.
|
||||
|
||||
### Basic operations
|
||||
|
||||
After token save, typical flow is:
|
||||
|
||||
- `Dashboard`: confirm provider/model/key status and recent errors
|
||||
- `Jobs / Events`: refresh runs, connect SSE stream, verify event updates
|
||||
- `Approvals`: approve/reject pending items
|
||||
- `Schedules / Triggers`: toggle schedules, run now, or fire manual trigger
|
||||
- `Config`: reload and safely update provider/model/base URL/retry/timeout
|
||||
- `Doctor / Diagnostics`: inspect security doctor + preflight inventory output
|
||||
- `Quick Actions`: retry failed schedule, refresh model list, or run drill (subject to existing policy/tool availability)
|
||||
|
||||
### Reverse proxy and exposure notes
|
||||
|
||||
Do **not** expose ComfyUI/OpenClaw admin endpoints directly to the public internet without a hardened edge.
|
||||
|
||||
Minimum recommendations:
|
||||
|
||||
- terminate TLS at reverse proxy (HTTPS only)
|
||||
- add authentication at edge (in addition to OpenClaw admin token)
|
||||
- restrict source IP ranges when possible
|
||||
- apply request-rate limits and connection limits
|
||||
- keep server and node package on current patched versions
|
||||
|
||||
For internet-facing deployment templates and hardening checklist, follow:
|
||||
|
||||
- `docs/security_deployment_guide.md`
|
||||
|
||||
## Nodes
|
||||
|
||||
Nodes are exported as `Moltbot*` class names for compatibility, but appear as `openclaw:*` display names in ComfyUI:
|
||||
@@ -545,6 +646,7 @@ Use `/api/...` from browsers and extension JS.
|
||||
Machine-readable API spec:
|
||||
|
||||
- Generated OpenAPI spec: `docs/openapi.yaml` (derived from `docs/release/api_contract.md`; regenerate with `python scripts/generate_openapi_spec.py`)
|
||||
- UI entry route: `GET /openclaw/admin` (legacy `GET /moltbot/admin`) serves the standalone remote admin console HTML shell; backend write actions still enforce admin-token and remote-admin policy.
|
||||
|
||||
### Observability (read-only)
|
||||
|
||||
|
||||
+7
-3
@@ -35,6 +35,9 @@ Set these Environment Variables:
|
||||
# Require a token for admin actions (Stop/Approve)
|
||||
OPENCLAW_ADMIN_TOKEN=your-strong-secret-token
|
||||
|
||||
# Explicitly allow admin write actions from non-loopback LAN clients
|
||||
OPENCLAW_ALLOW_REMOTE_ADMIN=1
|
||||
|
||||
# Require a token for Logs/Config viewing
|
||||
OPENCLAW_OBSERVABILITY_TOKEN=observability-secret
|
||||
```
|
||||
@@ -65,6 +68,7 @@ sudo ufw allow from 192.168.1.0/24 to any port 8188
|
||||
## Testing
|
||||
|
||||
1. Find your host IP (e.g., `192.168.1.10`).
|
||||
2. From another device on WiFi, visit `http://192.168.1.10:8188`.
|
||||
3. Open OpenClaw Settings.
|
||||
4. Try to view logs. It should challenge you for the `OPENCLAW_OBSERVABILITY_TOKEN` or deny access.
|
||||
2. From another device on WiFi, open the remote admin page: `http://192.168.1.10:8188/openclaw/admin`.
|
||||
3. Enter `X-OpenClaw-Admin-Token` in the page and click **Save**.
|
||||
4. Verify admin write actions (for example refresh runs, approval actions) are no longer denied by remote policy.
|
||||
5. Open OpenClaw Settings in ComfyUI and try to view logs. It should challenge you for the `OPENCLAW_OBSERVABILITY_TOKEN` or deny access when missing.
|
||||
|
||||
@@ -8,6 +8,7 @@ This adds limits, TLS, and header management.
|
||||
1. **Block Sensitive Paths**: Prevent external access to admin/debug endpoints if not needed.
|
||||
- Block `/openclaw/logs/*`
|
||||
- Block `/openclaw/config`
|
||||
- Block `/openclaw/admin` and legacy `/moltbot/admin` when remote admin UI is not required
|
||||
2. **Timeouts**: ComfyUI generation can take time. Increase timeouts.
|
||||
- `proxy_read_timeout 600s;` (Nginx)
|
||||
3. **Websockets**: ComfyUI requires WS support.
|
||||
@@ -25,7 +26,7 @@ comfyui.local {
|
||||
}
|
||||
|
||||
# Security: Block sensitive OpenClaw paths from external access
|
||||
@sensitive path /openclaw/logs* /openclaw/config
|
||||
@sensitive path /openclaw/logs* /openclaw/config /openclaw/admin /moltbot/admin
|
||||
respond @sensitive 403
|
||||
}
|
||||
```
|
||||
@@ -56,5 +57,31 @@ server {
|
||||
location /openclaw/logs {
|
||||
deny all;
|
||||
}
|
||||
|
||||
location = /openclaw/admin {
|
||||
deny all;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## If You Intentionally Expose Remote Admin Console
|
||||
|
||||
Only do this on trusted/private access planes and keep backend protection enabled:
|
||||
|
||||
- `OPENCLAW_ADMIN_TOKEN=<strong-secret>`
|
||||
- `OPENCLAW_ALLOW_REMOTE_ADMIN=1`
|
||||
|
||||
Use one more auth boundary at proxy layer (IP allowlist, SSO, or basic auth), for example:
|
||||
|
||||
```nginx
|
||||
location = /openclaw/admin {
|
||||
allow 10.0.0.0/8;
|
||||
allow 192.168.0.0/16;
|
||||
deny all;
|
||||
|
||||
auth_basic "Restricted";
|
||||
auth_basic_user_file /etc/nginx/.htpasswd;
|
||||
|
||||
proxy_pass http://127.0.0.1:8188/openclaw/admin;
|
||||
}
|
||||
```
|
||||
|
||||
@@ -12,6 +12,7 @@ To set OpenClaw security tokens in the portable version, edit your `run_nvidia_g
|
||||
@echo off
|
||||
:: Security Tokens
|
||||
set OPENCLAW_ADMIN_TOKEN=my-secret-token
|
||||
set OPENCLAW_ALLOW_REMOTE_ADMIN=1
|
||||
set OPENCLAW_OBSERVABILITY_TOKEN=observability-token
|
||||
|
||||
:: Run ComfyUI
|
||||
@@ -23,9 +24,32 @@ pause
|
||||
|
||||
```powershell
|
||||
$env:OPENCLAW_ADMIN_TOKEN="my-secret-token"
|
||||
$env:OPENCLAW_ALLOW_REMOTE_ADMIN="1"
|
||||
./python_embeded/python.exe -s ComfyUI/main.py
|
||||
```
|
||||
|
||||
## LAN / Mobile Remote Admin Startup
|
||||
|
||||
If you want to open the standalone remote admin page from another device in your LAN:
|
||||
|
||||
```powershell
|
||||
$env:OPENCLAW_ADMIN_TOKEN="my-secret-token"
|
||||
$env:OPENCLAW_ALLOW_REMOTE_ADMIN="1"
|
||||
./python_embeded/python.exe -s ComfyUI/main.py --listen 0.0.0.0 --port 8188
|
||||
```
|
||||
|
||||
Then open from phone/tablet browser:
|
||||
|
||||
```text
|
||||
http://<WINDOWS_LAN_IP>:8188/openclaw/admin
|
||||
```
|
||||
|
||||
Find your LAN IP:
|
||||
|
||||
```powershell
|
||||
ipconfig
|
||||
```
|
||||
|
||||
## Service Mode (NSSM)
|
||||
|
||||
If you want to run ComfyUI as a background service, use **NSSM** (Non-Sucking Service Manager).
|
||||
@@ -40,3 +64,28 @@ If you want to run ComfyUI as a background service, use **NSSM** (Non-Sucking Se
|
||||
|
||||
- **Permissions**: Services run as `SYSTEM` by default. It is safer to create a dedicated user and set the service to Log On as that user.
|
||||
- **GPU Access**: Ensure the user running the service has access to the GPU driver context (usually fine for logged-in users, tricky for headless services).
|
||||
|
||||
## Common Startup Failure: WinError 10013
|
||||
|
||||
Symptom:
|
||||
|
||||
```text
|
||||
PermissionError: [WinError 10013] ... bind on address ('0.0.0.0', 8188)
|
||||
```
|
||||
|
||||
Typical causes:
|
||||
|
||||
- Port is already occupied by another process.
|
||||
- Firewall/security policy blocks this bind.
|
||||
- Reserved/excluded port range on Windows.
|
||||
|
||||
Deterministic remediation:
|
||||
|
||||
1. Retry with another port (for example `--port 8200`).
|
||||
2. Ensure no duplicate ComfyUI instance is already listening.
|
||||
3. Verify inbound firewall rule allows the selected port for `LocalSubnet`.
|
||||
4. If still failing, check excluded ranges and avoid those ports:
|
||||
|
||||
```powershell
|
||||
netsh int ipv4 show excludedportrange protocol=tcp
|
||||
```
|
||||
|
||||
@@ -25,6 +25,29 @@ This document summarizes the current OpenClaw sidebar UI structure and how to ve
|
||||
If capabilities are unavailable, the full tab set is registered to surface actionable errors (instead of “missing tabs”).
|
||||
If `assist_streaming` is unavailable or the stream transport degrades, Planner/Refiner automatically fall back to the existing non-stream request path.
|
||||
|
||||
## Standalone Remote Admin Console
|
||||
|
||||
- Entry route: `GET /openclaw/admin` (legacy `GET /moltbot/admin` still works).
|
||||
- HTML shell: `web/admin_console.html`
|
||||
- Purpose: mobile-friendly standalone operations UI for non-sidebar workflows.
|
||||
- Security model:
|
||||
- The page itself is a static shell and can render without authentication.
|
||||
- All write APIs still enforce backend admin policy (`X-OpenClaw-Admin-Token` and remote policy such as `OPENCLAW_ALLOW_REMOTE_ADMIN`).
|
||||
- Runtime behaviors:
|
||||
- Dashboard summary + health/config snapshots
|
||||
- Jobs/Events polling + SSE stream connect/fallback
|
||||
- Approvals/Schedules/Triggers control actions
|
||||
- Config read/partial write and diagnostics access
|
||||
- Quick Actions (retry/refresh/drill) remain backend-authorized
|
||||
|
||||
## Remote Console Manual Checks
|
||||
|
||||
1. Open `http://<host>:<port>/openclaw/admin` from desktop and phone browsers.
|
||||
2. Save an admin token via the console and verify protected actions succeed.
|
||||
3. Clear token and verify write actions fail with explicit auth/policy errors.
|
||||
4. Connect SSE, then trigger a run; verify event stream updates and fallback polling still works.
|
||||
5. Confirm there is no blank/overflow breakage on narrow mobile widths.
|
||||
|
||||
## Quick Manual Checks
|
||||
|
||||
1. Open ComfyUI and confirm OpenClaw appears in the sidebar.
|
||||
|
||||
+98
-35
@@ -1,8 +1,8 @@
|
||||
openapi: "3.0.3"
|
||||
info:
|
||||
title: "ComfyUI-OpenClaw API"
|
||||
version: "1.0.0"
|
||||
description: "Generated from docs/release/api_contract.md (R66 baseline)."
|
||||
version: "1.0.2"
|
||||
description: "Generated from docs/release/api_contract.md (v1.0.2 baseline)."
|
||||
servers:
|
||||
- url: "/openclaw"
|
||||
description: "Direct OpenClaw prefix"
|
||||
@@ -31,6 +31,17 @@ paths:
|
||||
x-openclaw-section: "1.1 Core Observability & System"
|
||||
x-openclaw-legacy-path: "/moltbot/capabilities"
|
||||
x-openclaw-auth-tier: "none"
|
||||
/admin:
|
||||
get:
|
||||
operationId: "get_admin_console"
|
||||
summary: "Standalone remote admin console HTML shell (mobile-friendly)."
|
||||
responses:
|
||||
200:
|
||||
description: "OK"
|
||||
x-openclaw-auth: "None*"
|
||||
x-openclaw-section: "1.0 UI Entry Points"
|
||||
x-openclaw-legacy-path: "/moltbot/admin"
|
||||
x-openclaw-auth-tier: "none"
|
||||
/logs/tail:
|
||||
get:
|
||||
operationId: "get_logs_tail"
|
||||
@@ -249,7 +260,7 @@ paths:
|
||||
- OpenClawAdminToken:
|
||||
[]
|
||||
x-openclaw-streaming: true
|
||||
/chat:
|
||||
/llm/chat:
|
||||
post:
|
||||
operationId: "post_chat"
|
||||
summary: "Unified chat interface for assistant interactions."
|
||||
@@ -263,7 +274,7 @@ paths:
|
||||
security:
|
||||
- OpenClawAdminToken:
|
||||
[]
|
||||
/test:
|
||||
/llm/test:
|
||||
post:
|
||||
operationId: "post_test"
|
||||
summary: "Test LLM connectivity and configuration."
|
||||
@@ -277,7 +288,7 @@ paths:
|
||||
security:
|
||||
- OpenClawAdminToken:
|
||||
[]
|
||||
/models:
|
||||
/llm/models:
|
||||
get:
|
||||
operationId: "get_models"
|
||||
summary: "List available models from configured provider."
|
||||
@@ -426,32 +437,44 @@ paths:
|
||||
security:
|
||||
- OpenClawAdminToken:
|
||||
[]
|
||||
/openclaw/schedules:
|
||||
/schedules:
|
||||
get:
|
||||
operationId: "get_openclaw_schedules"
|
||||
operationId: "get_schedules"
|
||||
summary: "List all schedules."
|
||||
responses:
|
||||
200:
|
||||
description: "OK"
|
||||
x-openclaw-auth: "Unknown"
|
||||
x-openclaw-auth: "Admin"
|
||||
x-openclaw-section: "1.5 Schedules & Approvals"
|
||||
x-openclaw-auth-tier: "admin"
|
||||
security:
|
||||
- OpenClawAdminToken:
|
||||
[]
|
||||
post:
|
||||
operationId: "post_openclaw_schedules"
|
||||
operationId: "post_schedules"
|
||||
summary: "Create a new schedule."
|
||||
responses:
|
||||
200:
|
||||
description: "OK"
|
||||
x-openclaw-auth: "Unknown"
|
||||
x-openclaw-auth: "Admin"
|
||||
x-openclaw-section: "1.5 Schedules & Approvals"
|
||||
/openclaw/schedules/{id}:
|
||||
x-openclaw-auth-tier: "admin"
|
||||
security:
|
||||
- OpenClawAdminToken:
|
||||
[]
|
||||
/schedules/{id}:
|
||||
get:
|
||||
operationId: "get_openclaw_schedules_id"
|
||||
operationId: "get_schedules_id"
|
||||
summary: "Get schedule details."
|
||||
responses:
|
||||
200:
|
||||
description: "OK"
|
||||
x-openclaw-auth: "Unknown"
|
||||
x-openclaw-auth: "Admin"
|
||||
x-openclaw-section: "1.5 Schedules & Approvals"
|
||||
x-openclaw-auth-tier: "admin"
|
||||
security:
|
||||
- OpenClawAdminToken:
|
||||
[]
|
||||
parameters:
|
||||
- name: "id"
|
||||
in: "path"
|
||||
@@ -459,13 +482,17 @@ paths:
|
||||
schema:
|
||||
type: "string"
|
||||
put:
|
||||
operationId: "put_openclaw_schedules_id"
|
||||
operationId: "put_schedules_id"
|
||||
summary: "Update a schedule."
|
||||
responses:
|
||||
200:
|
||||
description: "OK"
|
||||
x-openclaw-auth: "Unknown"
|
||||
x-openclaw-auth: "Admin"
|
||||
x-openclaw-section: "1.5 Schedules & Approvals"
|
||||
x-openclaw-auth-tier: "admin"
|
||||
security:
|
||||
- OpenClawAdminToken:
|
||||
[]
|
||||
parameters:
|
||||
- name: "id"
|
||||
in: "path"
|
||||
@@ -473,82 +500,106 @@ paths:
|
||||
schema:
|
||||
type: "string"
|
||||
delete:
|
||||
operationId: "delete_openclaw_schedules_id"
|
||||
operationId: "delete_schedules_id"
|
||||
summary: "Delete a schedule."
|
||||
responses:
|
||||
200:
|
||||
description: "OK"
|
||||
x-openclaw-auth: "Unknown"
|
||||
x-openclaw-auth: "Admin"
|
||||
x-openclaw-section: "1.5 Schedules & Approvals"
|
||||
x-openclaw-auth-tier: "admin"
|
||||
security:
|
||||
- OpenClawAdminToken:
|
||||
[]
|
||||
parameters:
|
||||
- name: "id"
|
||||
in: "path"
|
||||
required: true
|
||||
schema:
|
||||
type: "string"
|
||||
/openclaw/schedules/{id}/run:
|
||||
/schedules/{id}/run:
|
||||
post:
|
||||
operationId: "post_openclaw_schedules_id_run"
|
||||
operationId: "post_schedules_id_run"
|
||||
summary: "Manually trigger a schedule."
|
||||
responses:
|
||||
200:
|
||||
description: "OK"
|
||||
x-openclaw-auth: "Unknown"
|
||||
x-openclaw-auth: "Admin"
|
||||
x-openclaw-section: "1.5 Schedules & Approvals"
|
||||
x-openclaw-auth-tier: "admin"
|
||||
security:
|
||||
- OpenClawAdminToken:
|
||||
[]
|
||||
parameters:
|
||||
- name: "id"
|
||||
in: "path"
|
||||
required: true
|
||||
schema:
|
||||
type: "string"
|
||||
/openclaw/schedules/{id}/runs:
|
||||
/schedules/{id}/runs:
|
||||
get:
|
||||
operationId: "get_openclaw_schedules_id_runs"
|
||||
operationId: "get_schedules_id_runs"
|
||||
summary: "Get run history for a schedule."
|
||||
responses:
|
||||
200:
|
||||
description: "OK"
|
||||
x-openclaw-auth: "Unknown"
|
||||
x-openclaw-auth: "Admin"
|
||||
x-openclaw-section: "1.5 Schedules & Approvals"
|
||||
x-openclaw-auth-tier: "admin"
|
||||
security:
|
||||
- OpenClawAdminToken:
|
||||
[]
|
||||
parameters:
|
||||
- name: "id"
|
||||
in: "path"
|
||||
required: true
|
||||
schema:
|
||||
type: "string"
|
||||
/openclaw/approvals:
|
||||
/approvals:
|
||||
get:
|
||||
operationId: "get_openclaw_approvals"
|
||||
operationId: "get_approvals"
|
||||
summary: "List pending approvals (includes pagination/scan diagnostics; bounded serialization scan on malformed records)."
|
||||
responses:
|
||||
200:
|
||||
description: "OK"
|
||||
x-openclaw-auth: "Unknown"
|
||||
x-openclaw-auth: "Admin"
|
||||
x-openclaw-section: "1.5 Schedules & Approvals"
|
||||
/openclaw/approvals/{id}/approve:
|
||||
x-openclaw-auth-tier: "admin"
|
||||
security:
|
||||
- OpenClawAdminToken:
|
||||
[]
|
||||
/approvals/{id}/approve:
|
||||
post:
|
||||
operationId: "post_openclaw_approvals_id_approve"
|
||||
operationId: "post_approvals_id_approve"
|
||||
summary: "Approve a pending request."
|
||||
responses:
|
||||
200:
|
||||
description: "OK"
|
||||
x-openclaw-auth: "Unknown"
|
||||
x-openclaw-auth: "Admin"
|
||||
x-openclaw-section: "1.5 Schedules & Approvals"
|
||||
x-openclaw-auth-tier: "admin"
|
||||
security:
|
||||
- OpenClawAdminToken:
|
||||
[]
|
||||
parameters:
|
||||
- name: "id"
|
||||
in: "path"
|
||||
required: true
|
||||
schema:
|
||||
type: "string"
|
||||
/openclaw/approvals/{id}/reject:
|
||||
/approvals/{id}/reject:
|
||||
post:
|
||||
operationId: "post_openclaw_approvals_id_reject"
|
||||
operationId: "post_approvals_id_reject"
|
||||
summary: "Reject a pending request."
|
||||
responses:
|
||||
200:
|
||||
description: "OK"
|
||||
x-openclaw-auth: "Unknown"
|
||||
x-openclaw-auth: "Admin"
|
||||
x-openclaw-section: "1.5 Schedules & Approvals"
|
||||
x-openclaw-auth-tier: "admin"
|
||||
security:
|
||||
- OpenClawAdminToken:
|
||||
[]
|
||||
parameters:
|
||||
- name: "id"
|
||||
in: "path"
|
||||
@@ -562,8 +613,12 @@ paths:
|
||||
responses:
|
||||
200:
|
||||
description: "OK"
|
||||
x-openclaw-auth: "Unknown"
|
||||
x-openclaw-auth: "Bridge Auth (Device Check)"
|
||||
x-openclaw-section: "1.6 Bridge (Sidecar)"
|
||||
x-openclaw-auth-tier: "bridge"
|
||||
security:
|
||||
- OpenClawBridgeAuth:
|
||||
[]
|
||||
/bridge/submit:
|
||||
post:
|
||||
operationId: "post_bridge_submit"
|
||||
@@ -571,8 +626,12 @@ paths:
|
||||
responses:
|
||||
200:
|
||||
description: "OK"
|
||||
x-openclaw-auth: "Unknown"
|
||||
x-openclaw-auth: "Bridge Auth (Device Check)"
|
||||
x-openclaw-section: "1.6 Bridge (Sidecar)"
|
||||
x-openclaw-auth-tier: "bridge"
|
||||
security:
|
||||
- OpenClawBridgeAuth:
|
||||
[]
|
||||
/bridge/deliver:
|
||||
post:
|
||||
operationId: "post_bridge_deliver"
|
||||
@@ -580,8 +639,12 @@ paths:
|
||||
responses:
|
||||
200:
|
||||
description: "OK"
|
||||
x-openclaw-auth: "Unknown"
|
||||
x-openclaw-auth: "Bridge Auth (Device Check)"
|
||||
x-openclaw-section: "1.6 Bridge (Sidecar)"
|
||||
x-openclaw-auth-tier: "bridge"
|
||||
security:
|
||||
- OpenClawBridgeAuth:
|
||||
[]
|
||||
components:
|
||||
securitySchemes:
|
||||
OpenClawAdminToken:
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# OpenClaw API Contract (v1)
|
||||
|
||||
> **Status**: normative
|
||||
> **Version**: 1.0.1
|
||||
> **Date**: 2026-02-26
|
||||
> **Version**: 1.0.2
|
||||
> **Date**: 2026-02-28
|
||||
|
||||
This document defines the public API contract for OpenClaw. It serves as the authoritative baseline for client compatibility and breaking change policies.
|
||||
|
||||
@@ -10,6 +10,16 @@ This document defines the public API contract for OpenClaw. It serves as the aut
|
||||
|
||||
All new integrations should use the `/openclaw/` prefix. Use of `/moltbot/` is deprecated.
|
||||
|
||||
### 1.0 UI Entry Points
|
||||
|
||||
**Base Path**: `/openclaw/`
|
||||
|
||||
| Method | Path | Legacy Path | Auth | Description |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| `GET` | `/admin` | `/moltbot/admin` | None* | Standalone remote admin console HTML shell (mobile-friendly). |
|
||||
|
||||
`*` The page shell can be loaded directly, but all backend write operations from the console still enforce Admin token and remote-admin policy.
|
||||
|
||||
### 1.1 Core Observability & System
|
||||
|
||||
**Base Path**: `/openclaw/`
|
||||
|
||||
@@ -19,7 +19,7 @@ Users should audit these flags before deploying to a public or untrusted network
|
||||
| Flag | Default | Risk | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `OPENCLAW_CONNECTOR_ADMIN_TOKEN` | *None* | **Medium** | Required for admin commands (stop/approve/trace) if server auth is enabled. If missing, admin commands fail safe. |
|
||||
| `OPENCLAW_ALLOW_REMOTE_ADMIN` | `0` | **High** | Be careful! Allows admin actions from non-loopback IPs if token is present. Default is loopback-only for admin. |
|
||||
| `OPENCLAW_ALLOW_REMOTE_ADMIN` | `0` | **High** | Be careful! Allows admin actions from non-loopback IPs if token is present (including writes from `/openclaw/admin` remote console). Default is loopback-only for admin. |
|
||||
| `OPENCLAW_BRIDGE_ENABLED` | `0` | **High** | Enables the sidecar bridge for remote orchestration. Requires `OPENCLAW_BRIDGE_DEVICE_TOKEN` (and in public posture also mTLS + device allowlist controls). |
|
||||
| `OPENCLAW_ALLOW_ANY_PUBLIC_LLM_HOST` | `0` | **High** | Bypasses the known-host allowlist for LLM `base_url`. Allows SSRF to public IPs. |
|
||||
| `OPENCLAW_ALLOW_INSECURE_BASE_URL` | `0` | **Critical** | Allows HTTP (non-HTTPS) or private IP `base_url` for LLM. Risk of internal network scanning (SSRF). |
|
||||
|
||||
@@ -118,6 +118,7 @@ OPENCLAW_SECURITY_DANGEROUS_BIND_OVERRIDE=0
|
||||
- `python scripts/check_deployment_profile.py --profile lan`
|
||||
5. Run the security diagnostics endpoint before production use:
|
||||
- `GET /openclaw/security/doctor` (admin boundary).
|
||||
6. If using mobile/remote admin UI, expose `/openclaw/admin` only inside trusted LAN/VPN boundaries.
|
||||
|
||||
## 5. Public (Internet + Reverse Proxy)
|
||||
|
||||
@@ -170,6 +171,7 @@ OPENCLAW_SECURITY_DANGEROUS_BIND_OVERRIDE=0
|
||||
7. Validate with project test and release gates before rollout:
|
||||
- `tests/TEST_SOP.md`
|
||||
- `RELEASE_CHECKLIST.md`
|
||||
8. Ensure `/openclaw/admin` is blocked at public edge unless a separately hardened private admin plane is in place.
|
||||
|
||||
## 6. Bridge in Public Profile (only when absolutely required)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user