mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 14:10:51 +00:00
Merge remote-tracking branch 'origin/main' into release/2026.4.25
# Conflicts: # CHANGELOG.md
This commit is contained in:
Peter Steinberger
@@ -194,6 +194,12 @@ openclaw plugins list --json
|
||||
`plugins list` reads the persisted local plugin registry first, with a manifest-only derived fallback when the registry is missing or invalid. It is useful for checking whether a plugin is installed, enabled, and visible to cold startup planning, but it is not a live runtime probe of an already-running Gateway process. After changing plugin code, enablement, hook policy, or `plugins.load.paths`, restart the Gateway that serves the channel before expecting new `register(api)` code or hooks to run. For remote/container deployments, verify you are restarting the actual `openclaw gateway run` child, not only a wrapper process.
|
||||
</Note>
|
||||
|
||||
For bundled plugin work inside a packaged Docker image, bind-mount the plugin
|
||||
source directory over the matching packaged source path, such as
|
||||
`/app/extensions/synology-chat`. OpenClaw will discover that mounted source
|
||||
overlay before `/app/dist/extensions/synology-chat`; a plain copied source
|
||||
directory remains inert so normal packaged installs still use compiled dist.
|
||||
|
||||
For runtime hook debugging:
|
||||
|
||||
- `openclaw plugins inspect <id> --json` shows registered hooks and diagnostics from a module-loaded inspection pass.
|
||||
@@ -226,7 +232,7 @@ openclaw plugins uninstall <id> --dry-run
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
```
|
||||
|
||||
`uninstall` removes plugin records from `plugins.entries`, the persisted plugin index, the plugin allowlist, and linked `plugins.load.paths` entries when applicable. Unless `--keep-files` is set, uninstall also removes the tracked managed install directory when it is inside OpenClaw's plugin extensions root. For active memory plugins, the memory slot resets to `memory-core`.
|
||||
`uninstall` removes plugin records from `plugins.entries`, the persisted plugin index, plugin allow/deny list entries, and linked `plugins.load.paths` entries when applicable. Unless `--keep-files` is set, uninstall also removes the tracked managed install directory when it is inside OpenClaw's plugin extensions root. For active memory plugins, the memory slot resets to `memory-core`.
|
||||
|
||||
<Note>
|
||||
`--keep-config` is supported as a deprecated alias for `--keep-files`.
|
||||
|
||||
@@ -39,7 +39,7 @@ openclaw --update
|
||||
- `--json`: print machine-readable `UpdateRunResult` JSON, including
|
||||
`postUpdate.plugins.integrityDrifts` when npm plugin artifact drift is
|
||||
detected during post-update plugin sync.
|
||||
- `--timeout <seconds>`: per-step timeout (default is 1200s).
|
||||
- `--timeout <seconds>`: per-step timeout (default is 1800s).
|
||||
- `--yes`: skip confirmation prompts (for example downgrade confirmation)
|
||||
|
||||
Note: downgrades require confirmation because older versions can break configuration.
|
||||
@@ -67,7 +67,7 @@ offers to create one.
|
||||
|
||||
Options:
|
||||
|
||||
- `--timeout <seconds>`: timeout for each update step (default `1200`)
|
||||
- `--timeout <seconds>`: timeout for each update step (default `1800`)
|
||||
|
||||
## What it does
|
||||
|
||||
|
||||
@@ -253,6 +253,10 @@ A no-op `compact()` is unsafe for an active non-owning engine because it disable
|
||||
The slot is exclusive at run time — only one registered context engine is resolved for a given run or compaction operation. Other enabled `kind: "context-engine"` plugins can still load and run their registration code; `plugins.slots.contextEngine` only selects which registered engine id OpenClaw resolves when it needs a context engine.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
**Plugin uninstall:** when you uninstall the plugin currently selected as `plugins.slots.contextEngine`, OpenClaw resets the slot back to the default (`legacy`). The same reset behavior applies to `plugins.slots.memory`. No manual config edit is required.
|
||||
</Note>
|
||||
|
||||
## Relationship to compaction and memory
|
||||
|
||||
<AccordionGroup>
|
||||
|
||||
@@ -1442,6 +1442,7 @@
|
||||
"gateway/doctor",
|
||||
"logging",
|
||||
"gateway/opentelemetry",
|
||||
"gateway/prometheus",
|
||||
"gateway/logging",
|
||||
"gateway/diagnostics",
|
||||
"gateway/troubleshooting"
|
||||
|
||||
209
docs/gateway/prometheus.md
Normal file
209
docs/gateway/prometheus.md
Normal file
@@ -0,0 +1,209 @@
|
||||
---
|
||||
summary: "Expose OpenClaw diagnostics as Prometheus text metrics through the diagnostics-prometheus plugin"
|
||||
title: "Prometheus metrics"
|
||||
sidebarTitle: "Prometheus"
|
||||
read_when:
|
||||
- You want Prometheus, Grafana, VictoriaMetrics, or another scraper to collect OpenClaw Gateway metrics
|
||||
- You need the Prometheus metric names and label policy for dashboards or alerts
|
||||
- You want metrics without running an OpenTelemetry collector
|
||||
---
|
||||
|
||||
OpenClaw can expose diagnostics metrics through the bundled `diagnostics-prometheus` plugin. It listens to trusted internal diagnostics and renders a Prometheus text endpoint at:
|
||||
|
||||
```text
|
||||
GET /api/diagnostics/prometheus
|
||||
```
|
||||
|
||||
Content type is `text/plain; version=0.0.4; charset=utf-8`, the standard Prometheus exposition format.
|
||||
|
||||
<Warning>
|
||||
The route uses Gateway authentication (operator scope). Do not expose it as a public unauthenticated `/metrics` endpoint. Scrape it through the same auth path you use for other operator APIs.
|
||||
</Warning>
|
||||
|
||||
For traces, logs, OTLP push, and OpenTelemetry GenAI semantic attributes, see [OpenTelemetry export](/gateway/opentelemetry).
|
||||
|
||||
## Quick start
|
||||
|
||||
<Steps>
|
||||
<Step title="Enable the plugin">
|
||||
<Tabs>
|
||||
<Tab title="Config">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
allow: ["diagnostics-prometheus"],
|
||||
entries: {
|
||||
"diagnostics-prometheus": { enabled: true },
|
||||
},
|
||||
},
|
||||
diagnostics: {
|
||||
enabled: true,
|
||||
},
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="CLI">
|
||||
```bash
|
||||
openclaw plugins enable diagnostics-prometheus
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
</Step>
|
||||
<Step title="Restart the Gateway">
|
||||
The HTTP route is registered at plugin startup, so reload after enabling.
|
||||
</Step>
|
||||
<Step title="Scrape the protected route">
|
||||
Send the same gateway auth your operator clients use:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
|
||||
http://127.0.0.1:18789/api/diagnostics/prometheus
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Wire Prometheus">
|
||||
```yaml
|
||||
# prometheus.yml
|
||||
scrape_configs:
|
||||
- job_name: openclaw
|
||||
scrape_interval: 30s
|
||||
metrics_path: /api/diagnostics/prometheus
|
||||
authorization:
|
||||
credentials_file: /etc/prometheus/openclaw-gateway-token
|
||||
static_configs:
|
||||
- targets: ["openclaw-gateway:18789"]
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
`diagnostics.enabled: true` is required. Without it, the plugin still registers the HTTP route but no diagnostic events flow into the exporter, so the response is empty.
|
||||
</Note>
|
||||
|
||||
## Metrics exported
|
||||
|
||||
| Metric | Type | Labels |
|
||||
| --------------------------------------------- | --------- | ----------------------------------------------------------------------------------------- |
|
||||
| `openclaw_run_completed_total` | counter | `channel`, `model`, `outcome`, `provider`, `trigger` |
|
||||
| `openclaw_run_duration_seconds` | histogram | `channel`, `model`, `outcome`, `provider`, `trigger` |
|
||||
| `openclaw_model_call_total` | counter | `api`, `error_category`, `model`, `outcome`, `provider`, `transport` |
|
||||
| `openclaw_model_call_duration_seconds` | histogram | `api`, `error_category`, `model`, `outcome`, `provider`, `transport` |
|
||||
| `openclaw_model_tokens_total` | counter | `agent`, `channel`, `model`, `provider`, `token_type` |
|
||||
| `openclaw_gen_ai_client_token_usage` | histogram | `model`, `provider`, `token_type` |
|
||||
| `openclaw_model_cost_usd_total` | counter | `agent`, `channel`, `model`, `provider` |
|
||||
| `openclaw_tool_execution_total` | counter | `error_category`, `outcome`, `params_kind`, `tool` |
|
||||
| `openclaw_tool_execution_duration_seconds` | histogram | `error_category`, `outcome`, `params_kind`, `tool` |
|
||||
| `openclaw_harness_run_total` | counter | `channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider` |
|
||||
| `openclaw_harness_run_duration_seconds` | histogram | `channel`, `error_category`, `harness`, `model`, `outcome`, `phase`, `plugin`, `provider` |
|
||||
| `openclaw_message_processed_total` | counter | `channel`, `outcome`, `reason` |
|
||||
| `openclaw_message_processed_duration_seconds` | histogram | `channel`, `outcome`, `reason` |
|
||||
| `openclaw_message_delivery_total` | counter | `channel`, `delivery_kind`, `error_category`, `outcome` |
|
||||
| `openclaw_message_delivery_duration_seconds` | histogram | `channel`, `delivery_kind`, `error_category`, `outcome` |
|
||||
| `openclaw_queue_lane_size` | gauge | `lane` |
|
||||
| `openclaw_queue_lane_wait_seconds` | histogram | `lane` |
|
||||
| `openclaw_session_state_total` | counter | `reason`, `state` |
|
||||
| `openclaw_session_queue_depth` | gauge | `state` |
|
||||
| `openclaw_memory_bytes` | gauge | `kind` |
|
||||
| `openclaw_memory_rss_bytes` | histogram | none |
|
||||
| `openclaw_memory_pressure_total` | counter | `level`, `reason` |
|
||||
| `openclaw_telemetry_exporter_total` | counter | `exporter`, `reason`, `signal`, `status` |
|
||||
| `openclaw_prometheus_series_dropped_total` | counter | none |
|
||||
|
||||
## Label policy
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Bounded, low-cardinality labels">
|
||||
Prometheus labels stay bounded and low-cardinality. The exporter does not emit raw diagnostic identifiers such as `runId`, `sessionKey`, `sessionId`, `callId`, `toolCallId`, message IDs, chat IDs, or provider request IDs.
|
||||
|
||||
Label values are redacted and must match OpenClaw's low-cardinality character policy. Values that fail the policy are replaced with `unknown`, `other`, or `none`, depending on the metric.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Series cap and overflow accounting">
|
||||
The exporter caps retained time series in memory at **2048** series across counters, gauges, and histograms combined. New series beyond that cap are dropped, and `openclaw_prometheus_series_dropped_total` increments by one each time.
|
||||
|
||||
Watch this counter as a hard signal that an attribute upstream is leaking high-cardinality values. The exporter never lifts the cap automatically; if it climbs, fix the source rather than disabling the cap.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="What never appears in Prometheus output">
|
||||
- prompt text, response text, tool inputs, tool outputs, system prompts
|
||||
- raw provider request IDs (only bounded hashes, where applicable, on spans — never on metrics)
|
||||
- session keys and session IDs
|
||||
- hostnames, file paths, secret values
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## PromQL recipes
|
||||
|
||||
```promql
|
||||
# Tokens per minute, split by provider
|
||||
sum by (provider) (rate(openclaw_model_tokens_total[1m]))
|
||||
|
||||
# Spend (USD) over the last hour, by model
|
||||
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))
|
||||
|
||||
# 95th percentile model run duration
|
||||
histogram_quantile(
|
||||
0.95,
|
||||
sum by (le, provider, model)
|
||||
(rate(openclaw_run_duration_seconds_bucket[5m]))
|
||||
)
|
||||
|
||||
# Queue wait time SLO (95p under 2s)
|
||||
histogram_quantile(
|
||||
0.95,
|
||||
sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
|
||||
) < 2
|
||||
|
||||
# Dropped Prometheus series (cardinality alarm)
|
||||
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
|
||||
```
|
||||
|
||||
<Tip>
|
||||
Prefer `gen_ai_client_token_usage` for cross-provider dashboards: it follows the OpenTelemetry GenAI semantic conventions and is consistent with metrics from non-OpenClaw GenAI services.
|
||||
</Tip>
|
||||
|
||||
## Choosing between Prometheus and OpenTelemetry export
|
||||
|
||||
OpenClaw supports both surfaces independently. You can run either, both, or neither.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="diagnostics-prometheus">
|
||||
- **Pull** model: Prometheus scrapes `/api/diagnostics/prometheus`.
|
||||
- No external collector required.
|
||||
- Authenticated through normal Gateway auth.
|
||||
- Surface is metrics only (no traces or logs).
|
||||
- Best for stacks already standardized on Prometheus + Grafana.
|
||||
</Tab>
|
||||
<Tab title="diagnostics-otel">
|
||||
- **Push** model: OpenClaw sends OTLP/HTTP to a collector or OTLP-compatible backend.
|
||||
- Surface includes metrics, traces, and logs.
|
||||
- Bridges to Prometheus through an OpenTelemetry Collector (`prometheus` or `prometheusremotewrite` exporter) when you need both.
|
||||
- See [OpenTelemetry export](/gateway/opentelemetry) for the full catalog.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Empty response body">
|
||||
- Check `diagnostics.enabled: true` in config.
|
||||
- Confirm the plugin is enabled and loaded with `openclaw plugins list --enabled`.
|
||||
- Generate some traffic; counters and histograms only emit lines after at least one event.
|
||||
</Accordion>
|
||||
<Accordion title="401 / unauthorized">
|
||||
The endpoint requires the Gateway operator scope (`auth: "gateway"` with `gatewayRuntimeScopeSurface: "trusted-operator"`). Use the same token or password Prometheus uses for any other Gateway operator route. There is no public unauthenticated mode.
|
||||
</Accordion>
|
||||
<Accordion title="`openclaw_prometheus_series_dropped_total` is climbing">
|
||||
A new attribute is exceeding the **2048**-series cap. Inspect recent metrics for an unexpectedly high-cardinality label and fix it at the source. The exporter intentionally drops new series instead of silently rewriting labels.
|
||||
</Accordion>
|
||||
<Accordion title="Prometheus shows stale series after a restart">
|
||||
The plugin keeps state in memory only. After a Gateway restart, counters reset to zero and gauges restart at their next reported value. Use PromQL `rate()` and `increase()` to handle resets cleanly.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Related
|
||||
|
||||
- [Diagnostics export](/gateway/diagnostics) — local diagnostics zip for support bundles
|
||||
- [Health and readiness](/gateway/health) — `/healthz` and `/readyz` probes
|
||||
- [Logging](/logging) — file-based logging
|
||||
- [OpenTelemetry export](/gateway/opentelemetry) — OTLP push for traces, metrics, and logs
|
||||
@@ -172,6 +172,10 @@ runs the same lanes before release approval.
|
||||
- Use `--platform macos`, `--platform windows`, or `--platform linux` while
|
||||
iterating on one guest. Use `--json` for the summary artifact path and
|
||||
per-lane status.
|
||||
- The OpenAI lane uses `openai/gpt-5.5` for the live agent-turn proof by
|
||||
default. Pass `--model <provider/model>` or set
|
||||
`OPENCLAW_PARALLELS_OPENAI_MODEL` when deliberately validating another
|
||||
OpenAI model.
|
||||
- Wrap long local runs in a host timeout so Parallels transport stalls cannot
|
||||
consume the rest of the testing window:
|
||||
|
||||
@@ -603,7 +607,7 @@ These Docker runners split into two buckets:
|
||||
`OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Override those env vars when you
|
||||
explicitly want the larger exhaustive scan.
|
||||
- `test:docker:all` builds the live Docker image once via `test:docker:live-build`, then reuses it for the live Docker lanes. It also builds one shared `scripts/e2e/Dockerfile` image via `test:docker:e2e-build` and reuses it for the E2E container smoke runners that exercise the built app. The aggregate uses a weighted local scheduler: `OPENCLAW_DOCKER_ALL_PARALLELISM` controls process slots, while resource caps keep heavy live, npm-install, and multi-service lanes from all starting at once. Defaults are 10 slots, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=8`, and `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; tune `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` or `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` only when the Docker host has more headroom. The runner performs a Docker preflight by default, removes stale OpenClaw E2E containers, prints status every 30 seconds, stores successful lane timings in `.artifacts/docker-tests/lane-timings.json`, and uses those timings to start longer lanes first on later runs. Use `OPENCLAW_DOCKER_ALL_DRY_RUN=1` to print the weighted lane manifest without building or running Docker.
|
||||
- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update`, and `test:docker:config-reload` boot one or more real containers and verify higher-level integration paths.
|
||||
- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update`, and `test:docker:config-reload` boot one or more real containers and verify higher-level integration paths.
|
||||
|
||||
The live-model Docker runners also bind-mount only the needed CLI auth homes (or all supported ones when the run is not narrowed), then copy them into the container home before the run so external-CLI OAuth can refresh tokens without mutating the host auth store:
|
||||
|
||||
@@ -615,6 +619,7 @@ The live-model Docker runners also bind-mount only the needed CLI auth homes (or
|
||||
- Open WebUI live smoke: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`)
|
||||
- Onboarding wizard (TTY, full scaffolding): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`)
|
||||
- Npm tarball onboarding/channel/agent smoke: `pnpm test:docker:npm-onboard-channel-agent` installs the packed OpenClaw tarball globally in Docker, configures OpenAI via env-ref onboarding plus Telegram by default, verifies doctor repairs activated plugin runtime deps, and runs one mocked OpenAI agent turn. Reuse a prebuilt tarball with `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, skip the host rebuild with `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, or switch channel with `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`.
|
||||
- Update channel switch smoke: `pnpm test:docker:update-channel-switch` installs the packed OpenClaw tarball globally in Docker, switches from package `stable` to git `dev`, verifies the persisted channel and plugin post-update work, then switches back to package `stable` and checks update status.
|
||||
- Session runtime context smoke: `pnpm test:docker:session-runtime-context` verifies hidden runtime context transcript persistence plus doctor repair of affected duplicated prompt-rewrite branches.
|
||||
- Bun global install smoke: `bash scripts/e2e/bun-global-install-smoke.sh` packs the current tree, installs it with `bun install -g` in an isolated home, and verifies `openclaw infer image providers --json` returns bundled image providers instead of hanging. Reuse a prebuilt tarball with `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, skip the host build with `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0`, or copy `dist/` from a built Docker image with `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`.
|
||||
- Installer Docker smoke: `bash scripts/test-install-sh-docker.sh` shares one npm cache across its root, update, and direct-npm containers. Update smoke defaults to npm `latest` as the stable baseline before upgrading to the candidate tarball. Non-root installer checks keep an isolated npm cache so root-owned cache entries do not mask user-local install behavior. Set `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` to reuse the root/update/direct-npm cache across local reruns.
|
||||
@@ -626,7 +631,8 @@ The live-model Docker runners also bind-mount only the needed CLI auth homes (or
|
||||
- MCP channel bridge (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`)
|
||||
- Pi bundle MCP tools (real stdio MCP server + embedded Pi profile allow/deny smoke): `pnpm test:docker:pi-bundle-mcp-tools` (script: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`)
|
||||
- Cron/subagent MCP cleanup (real Gateway + stdio MCP child teardown after isolated cron and one-shot subagent runs): `pnpm test:docker:cron-mcp-cleanup` (script: `scripts/e2e/cron-mcp-cleanup-docker.sh`)
|
||||
- Plugins (install smoke + `/plugin` alias + Claude-bundle restart semantics): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`)
|
||||
- Plugins (install smoke, ClawHub install/uninstall, marketplace updates, and Claude-bundle enable/inspect): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`)
|
||||
Set `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` to skip the live ClawHub block, or override the default package with `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` and `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`.
|
||||
- Plugin update unchanged smoke: `pnpm test:docker:plugin-update` (script: `scripts/e2e/plugin-update-unchanged-docker.sh`)
|
||||
- Config reload metadata smoke: `pnpm test:docker:config-reload` (script: `scripts/e2e/config-reload-source-docker.sh`)
|
||||
- Bundled plugin runtime deps: `pnpm test:docker:bundled-channel-deps` builds a small Docker runner image by default, builds and packs OpenClaw once on the host, then mounts that tarball into each Linux install scenario. Reuse the image with `OPENCLAW_SKIP_DOCKER_BUILD=1`, skip the host rebuild after a fresh local build with `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`, or point at an existing tarball with `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. The full Docker aggregate pre-packs this tarball once, then shards bundled channel checks into independent lanes, including separate update lanes for Telegram, Discord, Slack, Feishu, memory-lancedb, and ACPX. Use `OPENCLAW_BUNDLED_CHANNELS=telegram,slack` to narrow the channel matrix when running the bundled lane directly, or `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx` to narrow the update scenario. The lane also verifies that `channels.<id>.enabled=false` and `plugins.entries.<id>.enabled=false` suppress doctor/runtime-dependency repair.
|
||||
|
||||
@@ -122,16 +122,61 @@ and setup-time config writes through `openclaw-gateway` with
|
||||
|
||||
The setup script accepts these optional environment variables:
|
||||
|
||||
| Variable | Purpose |
|
||||
| ------------------------------ | --------------------------------------------------------------- |
|
||||
| `OPENCLAW_IMAGE` | Use a remote image instead of building locally |
|
||||
| `OPENCLAW_DOCKER_APT_PACKAGES` | Install extra apt packages during build (space-separated) |
|
||||
| `OPENCLAW_EXTENSIONS` | Pre-install plugin deps at build time (space-separated names) |
|
||||
| `OPENCLAW_EXTRA_MOUNTS` | Extra host bind mounts (comma-separated `source:target[:opts]`) |
|
||||
| `OPENCLAW_HOME_VOLUME` | Persist `/home/node` in a named Docker volume |
|
||||
| `OPENCLAW_SANDBOX` | Opt in to sandbox bootstrap (`1`, `true`, `yes`, `on`) |
|
||||
| `OPENCLAW_DOCKER_SOCKET` | Override Docker socket path |
|
||||
| `OPENCLAW_DISABLE_BONJOUR` | Disable Bonjour/mDNS advertising (defaults to `1` for Docker) |
|
||||
| Variable | Purpose |
|
||||
| ------------------------------------------ | --------------------------------------------------------------- |
|
||||
| `OPENCLAW_IMAGE` | Use a remote image instead of building locally |
|
||||
| `OPENCLAW_DOCKER_APT_PACKAGES` | Install extra apt packages during build (space-separated) |
|
||||
| `OPENCLAW_EXTENSIONS` | Pre-install plugin deps at build time (space-separated names) |
|
||||
| `OPENCLAW_EXTRA_MOUNTS` | Extra host bind mounts (comma-separated `source:target[:opts]`) |
|
||||
| `OPENCLAW_HOME_VOLUME` | Persist `/home/node` in a named Docker volume |
|
||||
| `OPENCLAW_SANDBOX` | Opt in to sandbox bootstrap (`1`, `true`, `yes`, `on`) |
|
||||
| `OPENCLAW_DOCKER_SOCKET` | Override Docker socket path |
|
||||
| `OPENCLAW_DISABLE_BONJOUR` | Disable Bonjour/mDNS advertising (defaults to `1` for Docker) |
|
||||
| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | Disable bundled plugin source bind-mount overlays |
|
||||
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Shared OTLP/HTTP collector endpoint for OpenTelemetry export |
|
||||
| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | Signal-specific OTLP endpoints for traces, metrics, or logs |
|
||||
| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP protocol override. Only `http/protobuf` is supported today |
|
||||
| `OTEL_SERVICE_NAME` | Service name used for OpenTelemetry resources |
|
||||
| `OTEL_SEMCONV_STABILITY_OPT_IN` | Opt in to latest experimental GenAI semantic attributes |
|
||||
| `OPENCLAW_OTEL_PRELOADED` | Skip starting a second OpenTelemetry SDK when one is preloaded |
|
||||
|
||||
Maintainers can test bundled plugin source against a packaged image by mounting
|
||||
one plugin source directory over its packaged source path, for example
|
||||
`OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro`.
|
||||
That mounted source directory overrides the matching compiled
|
||||
`/app/dist/extensions/synology-chat` bundle for the same plugin id.
|
||||
|
||||
### Observability
|
||||
|
||||
OpenTelemetry export is outbound from the Gateway container to your OTLP
|
||||
collector. It does not require a published Docker port. If you build the image
|
||||
locally and want the bundled OpenTelemetry exporter available inside the image,
|
||||
include its runtime dependencies:
|
||||
|
||||
```bash
|
||||
export OPENCLAW_EXTENSIONS="diagnostics-otel"
|
||||
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"
|
||||
export OTEL_SERVICE_NAME="openclaw-gateway"
|
||||
./scripts/docker/setup.sh
|
||||
```
|
||||
|
||||
The official OpenClaw Docker release image includes `diagnostics-otel`
|
||||
dependencies. To enable export, allow and enable the `diagnostics-otel` plugin
|
||||
in config, then set `diagnostics.otel.enabled=true` or use the config example in
|
||||
[OpenTelemetry export](/gateway/opentelemetry). Collector auth headers are
|
||||
configured through `diagnostics.otel.headers`, not through Docker environment
|
||||
variables.
|
||||
|
||||
Prometheus metrics use the already-published Gateway port. Enable the
|
||||
`diagnostics-prometheus` plugin, then scrape:
|
||||
|
||||
```text
|
||||
http://<gateway-host>:18789/api/diagnostics/prometheus
|
||||
```
|
||||
|
||||
The route is protected by Gateway authentication. Do not expose a separate
|
||||
public `/metrics` port or unauthenticated reverse-proxy path. See
|
||||
[Prometheus metrics](/gateway/prometheus).
|
||||
|
||||
### Health checks
|
||||
|
||||
|
||||
@@ -73,6 +73,12 @@ the installer, pass `--install-method git --no-onboard` or
|
||||
npm i -g openclaw@latest
|
||||
```
|
||||
|
||||
When `openclaw update` manages a global npm install, it first runs the normal
|
||||
global install command. If that command fails, OpenClaw retries once with
|
||||
`--omit=optional`. That retry helps hosts where native optional dependencies
|
||||
cannot compile, while keeping the original failure visible if the fallback also
|
||||
fails.
|
||||
|
||||
```bash
|
||||
pnpm add -g openclaw@latest
|
||||
```
|
||||
|
||||
@@ -71,7 +71,10 @@ The migration sequence is:
|
||||
7. Remove only with explicit breaking-release approval.
|
||||
|
||||
Deprecated records must include a warning start date, replacement, docs link,
|
||||
and target removal date when known.
|
||||
and final removal date no more than three months after the warning starts. Do
|
||||
not add a deprecated compatibility path with an open-ended removal window unless
|
||||
maintainers explicitly decide it is permanent compatibility and mark it `active`
|
||||
instead.
|
||||
|
||||
## Current compatibility areas
|
||||
|
||||
@@ -79,15 +82,36 @@ Current compatibility records include:
|
||||
|
||||
- legacy broad SDK imports such as `openclaw/plugin-sdk/compat`
|
||||
- legacy hook-only plugin shapes and `before_agent_start`
|
||||
- legacy `activate(api)` plugin entrypoints while plugins migrate to
|
||||
`register(api)`
|
||||
- legacy SDK aliases such as `openclaw/extension-api`,
|
||||
`openclaw/plugin-sdk/channel-runtime`, `openclaw/plugin-sdk/command-auth`
|
||||
status builders, `openclaw/plugin-sdk/test-utils`, and the `ClawdbotConfig`
|
||||
type alias
|
||||
- bundled plugin allowlist and enablement behavior
|
||||
- legacy provider/channel env-var manifest metadata
|
||||
- legacy provider plugin hooks and type aliases while providers move to
|
||||
explicit catalog, auth, thinking, replay, and transport hooks
|
||||
- legacy runtime aliases such as `api.runtime.taskFlow`,
|
||||
`api.runtime.subagent.getSession`, and `api.runtime.stt`
|
||||
- legacy memory-plugin split registration while memory plugins move to
|
||||
`registerMemoryCapability`
|
||||
- legacy channel SDK helpers for native message schemas, mention gating,
|
||||
inbound envelope formatting, and approval capability nesting
|
||||
- activation hints that are being replaced by manifest contribution ownership
|
||||
- `setup-api` runtime fallback while setup descriptors move to cold
|
||||
`setup.requiresRuntime: false` metadata
|
||||
- provider `discovery` hooks while provider catalog hooks move to
|
||||
`catalog.run(...)`
|
||||
- channel `showConfigured` / `showInSetup` metadata while channel packages move
|
||||
to `openclaw.channel.exposure`
|
||||
- legacy runtime-policy config keys while doctor migrates operators to
|
||||
`agentRuntime`
|
||||
- generated bundled channel config metadata fallback while registry-first
|
||||
`channelConfigs` metadata lands
|
||||
- the persisted plugin registry disable env while repair flows migrate operators
|
||||
to `openclaw plugins registry --refresh` and `openclaw doctor --fix`
|
||||
- persisted plugin registry disable and install-migration env flags while
|
||||
repair flows migrate operators to `openclaw plugins registry --refresh` and
|
||||
`openclaw doctor --fix`
|
||||
|
||||
New plugin code should prefer the replacement listed in the registry and in the
|
||||
specific migration guide. Existing plugins can keep using a compatibility path
|
||||
|
||||
@@ -420,8 +420,9 @@ The same rule applies to other bundled-helper families such as:
|
||||
`plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`,
|
||||
`plugin-sdk/twitch`,
|
||||
`plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`,
|
||||
`plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`,
|
||||
`plugin-sdk/thread-ownership`, and `plugin-sdk/voice-call`
|
||||
`plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`,
|
||||
`plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`,
|
||||
and `plugin-sdk/voice-call`
|
||||
|
||||
`plugin-sdk/github-copilot-token` currently exposes the narrow token-helper
|
||||
surface `DEFAULT_COPILOT_API_BASE_URL`,
|
||||
|
||||
@@ -271,7 +271,7 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview)
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Bundled LINE helper/runtime surface |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Bundled IRC helper surface |
|
||||
| Channel-specific helpers | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Bundled channel compatibility/helper seams |
|
||||
| Auth/plugin-specific helpers | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Bundled feature/plugin helper seams; `plugin-sdk/github-copilot-token` currently exports `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, and `resolveCopilotApiToken` |
|
||||
| Auth/plugin-specific helpers | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Bundled feature/plugin helper seams; `plugin-sdk/github-copilot-token` currently exports `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, and `resolveCopilotApiToken` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
|
||||
@@ -11,12 +11,13 @@ title: "Tests"
|
||||
- `pnpm test:coverage`: Runs the unit suite with V8 coverage (via `vitest.unit.config.ts`). This is a loaded-file unit coverage gate, not whole-repo all-file coverage. Thresholds are 70% lines/functions/statements and 55% branches. Because `coverage.all` is false, the gate measures files loaded by the unit coverage suite instead of treating every split-lane source file as uncovered.
|
||||
- `pnpm test:coverage:changed`: Runs unit coverage only for files changed since `origin/main`.
|
||||
- `pnpm test:changed`: expands changed git paths into scoped Vitest lanes when the diff only touches routable source/test files. Config/setup changes still fall back to the native root projects run so wiring edits rerun broadly when needed.
|
||||
- `pnpm test:changed:focused`: inner-loop changed test run. It only runs precise targets from direct test edits, sibling `*.test.ts` files, explicit source mappings, and the local import graph. Broad/config/package changes are skipped instead of expanding to the full changed-test fallback.
|
||||
- `pnpm changed:lanes`: shows the architectural lanes triggered by the diff against `origin/main`.
|
||||
- `pnpm check:changed`: runs the smart changed gate for the diff against `origin/main`. It runs core work with core test lanes, extension work with extension test lanes, test-only work with test typecheck/tests only, expands public Plugin SDK or plugin-contract changes to one extension validation pass, and keeps release metadata-only version bumps on targeted version/config/root-dependency checks.
|
||||
- `pnpm test`: routes explicit file/directory targets through scoped Vitest lanes. Untargeted runs use fixed shard groups and expand to leaf configs for local parallel execution; the extension group always expands to the per-extension shard configs instead of one giant root-project process.
|
||||
- Full, extension, and include-pattern shard runs update local timing data in `.artifacts/vitest-shard-timings.json`; later whole-config runs use those timings to balance slow and fast shards. Include-pattern CI shards append the shard name to the timing key, which keeps filtered shard timings visible without replacing whole-config timing data. Set `OPENCLAW_TEST_PROJECTS_TIMINGS=0` to ignore the local timing artifact.
|
||||
- Selected `plugin-sdk` and `commands` test files now route through dedicated light lanes that keep only `test/setup.ts`, leaving runtime-heavy cases on their existing lanes.
|
||||
- Selected `plugin-sdk` and `commands` helper source files also map `pnpm test:changed` to explicit sibling tests in those light lanes, so small helper edits avoid rerunning the heavy runtime-backed suites.
|
||||
- Source files with sibling tests map to that sibling before falling back to wider directory globs. Helper edits under `test/helpers/channels` and `test/helpers/plugins` use a local import graph to run importing tests instead of broad-running every shard when the dependency path is precise.
|
||||
- `auto-reply` now also splits into three dedicated configs (`core`, `top-level`, `reply`) so the reply harness does not dominate the lighter top-level status/token/helper tests.
|
||||
- Base Vitest config now defaults to `pool: "threads"` and `isolate: false`, with the shared non-isolated runner enabled across the repo configs.
|
||||
- `pnpm test:channels` runs `vitest.channels.config.ts`.
|
||||
|
||||
@@ -1,177 +1,176 @@
|
||||
---
|
||||
summary: “Per-agent sandbox + tool restrictions, precedence, and examples”
|
||||
title: Multi-agent sandbox & tools
|
||||
read_when: “You want per-agent sandboxing or per-agent tool allow/deny policies in a multi-agent gateway.”
|
||||
summary: "Per-agent sandbox + tool restrictions, precedence, and examples"
|
||||
title: "Multi-agent sandbox and tools"
|
||||
sidebarTitle: "Multi-agent sandbox and tools"
|
||||
read_when: "You want per-agent sandboxing or per-agent tool allow/deny policies in a multi-agent gateway."
|
||||
status: active
|
||||
---
|
||||
|
||||
# Multi-Agent Sandbox & Tools Configuration
|
||||
Each agent in a multi-agent setup can override the global sandbox and tool policy. This page covers per-agent configuration, precedence rules, and examples.
|
||||
|
||||
Each agent in a multi-agent setup can override the global sandbox and tool
|
||||
policy. This page covers per-agent configuration, precedence rules, and
|
||||
examples.
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Sandboxing" href="/gateway/sandboxing">
|
||||
Backends and modes — full sandbox reference.
|
||||
</Card>
|
||||
<Card title="Sandbox vs tool policy vs elevated" href="/gateway/sandbox-vs-tool-policy-vs-elevated">
|
||||
Debug "why is this blocked?"
|
||||
</Card>
|
||||
<Card title="Elevated mode" href="/tools/elevated">
|
||||
Elevated exec for trusted senders.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
- **Sandbox backends and modes**: see [Sandboxing](/gateway/sandboxing).
|
||||
- **Debugging blocked tools**: see [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) and `openclaw sandbox explain`.
|
||||
- **Elevated exec**: see [Elevated Mode](/tools/elevated).
|
||||
|
||||
Auth is per-agent: each agent reads from its own `agentDir` auth store at
|
||||
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`.
|
||||
Credentials are **not** shared between agents. Never reuse `agentDir` across agents.
|
||||
If you want to share creds, copy `auth-profiles.json` into the other agent's `agentDir`.
|
||||
<Warning>
|
||||
Auth is per-agent: each agent reads from its own `agentDir` auth store at `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`. Credentials are **not** shared between agents. Never reuse `agentDir` across agents. If you want to share creds, copy `auth-profiles.json` into the other agent's `agentDir`.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Configuration Examples
|
||||
## Configuration examples
|
||||
|
||||
### Example 1: Personal + Restricted Family Agent
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"list": [
|
||||
{
|
||||
"id": "main",
|
||||
"default": true,
|
||||
"name": "Personal Assistant",
|
||||
"workspace": "~/.openclaw/workspace",
|
||||
"sandbox": { "mode": "off" }
|
||||
},
|
||||
{
|
||||
"id": "family",
|
||||
"name": "Family Bot",
|
||||
"workspace": "~/.openclaw/workspace-family",
|
||||
"sandbox": {
|
||||
"mode": "all",
|
||||
"scope": "agent"
|
||||
},
|
||||
"tools": {
|
||||
"allow": ["read"],
|
||||
"deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"bindings": [
|
||||
<AccordionGroup>
|
||||
<Accordion title="Example 1: Personal + restricted family agent">
|
||||
```json
|
||||
{
|
||||
"agentId": "family",
|
||||
"match": {
|
||||
"provider": "whatsapp",
|
||||
"accountId": "*",
|
||||
"peer": {
|
||||
"kind": "group",
|
||||
"id": "120363424282127706@g.us"
|
||||
"agents": {
|
||||
"list": [
|
||||
{
|
||||
"id": "main",
|
||||
"default": true,
|
||||
"name": "Personal Assistant",
|
||||
"workspace": "~/.openclaw/workspace",
|
||||
"sandbox": { "mode": "off" }
|
||||
},
|
||||
{
|
||||
"id": "family",
|
||||
"name": "Family Bot",
|
||||
"workspace": "~/.openclaw/workspace-family",
|
||||
"sandbox": {
|
||||
"mode": "all",
|
||||
"scope": "agent"
|
||||
},
|
||||
"tools": {
|
||||
"allow": ["read"],
|
||||
"deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"bindings": [
|
||||
{
|
||||
"agentId": "family",
|
||||
"match": {
|
||||
"provider": "whatsapp",
|
||||
"accountId": "*",
|
||||
"peer": {
|
||||
"kind": "group",
|
||||
"id": "120363424282127706@g.us"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Result:**
|
||||
|
||||
- `main` agent: runs on host, full tool access.
|
||||
- `family` agent: runs in Docker (one container per agent), only `read` tool.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Example 2: Work agent with shared sandbox">
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"list": [
|
||||
{
|
||||
"id": "personal",
|
||||
"workspace": "~/.openclaw/workspace-personal",
|
||||
"sandbox": { "mode": "off" }
|
||||
},
|
||||
{
|
||||
"id": "work",
|
||||
"workspace": "~/.openclaw/workspace-work",
|
||||
"sandbox": {
|
||||
"mode": "all",
|
||||
"scope": "shared",
|
||||
"workspaceRoot": "/tmp/work-sandboxes"
|
||||
},
|
||||
"tools": {
|
||||
"allow": ["read", "write", "apply_patch", "exec"],
|
||||
"deny": ["browser", "gateway", "discord"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Example 2b: Global coding profile + messaging-only agent">
|
||||
```json
|
||||
{
|
||||
"tools": { "profile": "coding" },
|
||||
"agents": {
|
||||
"list": [
|
||||
{
|
||||
"id": "support",
|
||||
"tools": { "profile": "messaging", "allow": ["slack"] }
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Result:**
|
||||
**Result:**
|
||||
|
||||
- `main` agent: Runs on host, full tool access
|
||||
- `family` agent: Runs in Docker (one container per agent), only `read` tool
|
||||
- default agents get coding tools.
|
||||
- `support` agent is messaging-only (+ Slack tool).
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Work Agent with Shared Sandbox
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"list": [
|
||||
{
|
||||
"id": "personal",
|
||||
"workspace": "~/.openclaw/workspace-personal",
|
||||
"sandbox": { "mode": "off" }
|
||||
},
|
||||
{
|
||||
"id": "work",
|
||||
"workspace": "~/.openclaw/workspace-work",
|
||||
"sandbox": {
|
||||
"mode": "all",
|
||||
"scope": "shared",
|
||||
"workspaceRoot": "/tmp/work-sandboxes"
|
||||
</Accordion>
|
||||
<Accordion title="Example 3: Different sandbox modes per agent">
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"sandbox": {
|
||||
"mode": "non-main",
|
||||
"scope": "session"
|
||||
}
|
||||
},
|
||||
"tools": {
|
||||
"allow": ["read", "write", "apply_patch", "exec"],
|
||||
"deny": ["browser", "gateway", "discord"]
|
||||
}
|
||||
"list": [
|
||||
{
|
||||
"id": "main",
|
||||
"workspace": "~/.openclaw/workspace",
|
||||
"sandbox": {
|
||||
"mode": "off"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "public",
|
||||
"workspace": "~/.openclaw/workspace-public",
|
||||
"sandbox": {
|
||||
"mode": "all",
|
||||
"scope": "agent"
|
||||
},
|
||||
"tools": {
|
||||
"allow": ["read"],
|
||||
"deny": ["exec", "write", "edit", "apply_patch"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
}
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
---
|
||||
|
||||
### Example 2b: Global coding profile + messaging-only agent
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": { "profile": "coding" },
|
||||
"agents": {
|
||||
"list": [
|
||||
{
|
||||
"id": "support",
|
||||
"tools": { "profile": "messaging", "allow": ["slack"] }
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Result:**
|
||||
|
||||
- default agents get coding tools
|
||||
- `support` agent is messaging-only (+ Slack tool)
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Different Sandbox Modes per Agent
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"sandbox": {
|
||||
"mode": "non-main", // Global default
|
||||
"scope": "session"
|
||||
}
|
||||
},
|
||||
"list": [
|
||||
{
|
||||
"id": "main",
|
||||
"workspace": "~/.openclaw/workspace",
|
||||
"sandbox": {
|
||||
"mode": "off" // Override: main never sandboxed
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "public",
|
||||
"workspace": "~/.openclaw/workspace-public",
|
||||
"sandbox": {
|
||||
"mode": "all", // Override: public always sandboxed
|
||||
"scope": "agent"
|
||||
},
|
||||
"tools": {
|
||||
"allow": ["read"],
|
||||
"deny": ["exec", "write", "edit", "apply_patch"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Precedence
|
||||
## Configuration precedence
|
||||
|
||||
When both global (`agents.defaults.*`) and agent-specific (`agents.list[].*`) configs exist:
|
||||
|
||||
### Sandbox Config
|
||||
### Sandbox config
|
||||
|
||||
Agent-specific settings override global:
|
||||
|
||||
@@ -185,139 +184,154 @@ agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
|
||||
agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
<Note>
|
||||
`agents.list[].sandbox.{docker,browser,prune}.*` overrides `agents.defaults.sandbox.{docker,browser,prune}.*` for that agent (ignored when sandbox scope resolves to `"shared"`).
|
||||
</Note>
|
||||
|
||||
- `agents.list[].sandbox.{docker,browser,prune}.*` overrides `agents.defaults.sandbox.{docker,browser,prune}.*` for that agent (ignored when sandbox scope resolves to `"shared"`).
|
||||
|
||||
### Tool Restrictions
|
||||
### Tool restrictions
|
||||
|
||||
The filtering order is:
|
||||
|
||||
1. **Tool profile** (`tools.profile` or `agents.list[].tools.profile`)
|
||||
2. **Provider tool profile** (`tools.byProvider[provider].profile` or `agents.list[].tools.byProvider[provider].profile`)
|
||||
3. **Global tool policy** (`tools.allow` / `tools.deny`)
|
||||
4. **Provider tool policy** (`tools.byProvider[provider].allow/deny`)
|
||||
5. **Agent-specific tool policy** (`agents.list[].tools.allow/deny`)
|
||||
6. **Agent provider policy** (`agents.list[].tools.byProvider[provider].allow/deny`)
|
||||
7. **Sandbox tool policy** (`tools.sandbox.tools` or `agents.list[].tools.sandbox.tools`)
|
||||
8. **Subagent tool policy** (`tools.subagents.tools`, if applicable)
|
||||
<Steps>
|
||||
<Step title="Tool profile">
|
||||
`tools.profile` or `agents.list[].tools.profile`.
|
||||
</Step>
|
||||
<Step title="Provider tool profile">
|
||||
`tools.byProvider[provider].profile` or `agents.list[].tools.byProvider[provider].profile`.
|
||||
</Step>
|
||||
<Step title="Global tool policy">
|
||||
`tools.allow` / `tools.deny`.
|
||||
</Step>
|
||||
<Step title="Provider tool policy">
|
||||
`tools.byProvider[provider].allow/deny`.
|
||||
</Step>
|
||||
<Step title="Agent-specific tool policy">
|
||||
`agents.list[].tools.allow/deny`.
|
||||
</Step>
|
||||
<Step title="Agent provider policy">
|
||||
`agents.list[].tools.byProvider[provider].allow/deny`.
|
||||
</Step>
|
||||
<Step title="Sandbox tool policy">
|
||||
`tools.sandbox.tools` or `agents.list[].tools.sandbox.tools`.
|
||||
</Step>
|
||||
<Step title="Subagent tool policy">
|
||||
`tools.subagents.tools`, if applicable.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Each level can further restrict tools, but cannot grant back denied tools from earlier levels.
|
||||
If `agents.list[].tools.sandbox.tools` is set, it replaces `tools.sandbox.tools` for that agent.
|
||||
If `agents.list[].tools.profile` is set, it overrides `tools.profile` for that agent.
|
||||
Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.4`).
|
||||
|
||||
If any explicit allowlist in that chain leaves the run with no callable tools,
|
||||
OpenClaw stops before submitting the prompt to the model. This is intentional:
|
||||
an agent configured with a missing tool such as
|
||||
`agents.list[].tools.allow: ["query_db"]` should fail loudly until the plugin
|
||||
that registers `query_db` is enabled, not continue as a text-only agent.
|
||||
<AccordionGroup>
|
||||
<Accordion title="Precedence rules">
|
||||
- Each level can further restrict tools, but cannot grant back denied tools from earlier levels.
|
||||
- If `agents.list[].tools.sandbox.tools` is set, it replaces `tools.sandbox.tools` for that agent.
|
||||
- If `agents.list[].tools.profile` is set, it overrides `tools.profile` for that agent.
|
||||
- Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.4`).
|
||||
</Accordion>
|
||||
<Accordion title="Empty allowlist behavior">
|
||||
If any explicit allowlist in that chain leaves the run with no callable tools, OpenClaw stops before submitting the prompt to the model. This is intentional: an agent configured with a missing tool such as `agents.list[].tools.allow: ["query_db"]` should fail loudly until the plugin that registers `query_db` is enabled, not continue as a text-only agent.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Tool policies support `group:*` shorthands that expand to multiple tools. See [Tool groups](/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands) for the full list.
|
||||
|
||||
Per-agent elevated overrides (`agents.list[].tools.elevated`) can further restrict elevated exec for specific agents. See [Elevated Mode](/tools/elevated) for details.
|
||||
Per-agent elevated overrides (`agents.list[].tools.elevated`) can further restrict elevated exec for specific agents. See [Elevated mode](/tools/elevated) for details.
|
||||
|
||||
---
|
||||
|
||||
## Migration from Single Agent
|
||||
## Migration from single agent
|
||||
|
||||
**Before (single agent):**
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"workspace": "~/.openclaw/workspace",
|
||||
"sandbox": {
|
||||
"mode": "non-main"
|
||||
}
|
||||
}
|
||||
},
|
||||
"tools": {
|
||||
"sandbox": {
|
||||
<Tabs>
|
||||
<Tab title="Before (single agent)">
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"workspace": "~/.openclaw/workspace",
|
||||
"sandbox": {
|
||||
"mode": "non-main"
|
||||
}
|
||||
}
|
||||
},
|
||||
"tools": {
|
||||
"allow": ["read", "write", "apply_patch", "exec"],
|
||||
"deny": []
|
||||
"sandbox": {
|
||||
"tools": {
|
||||
"allow": ["read", "write", "apply_patch", "exec"],
|
||||
"deny": []
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**After (multi-agent with different profiles):**
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"list": [
|
||||
{
|
||||
"id": "main",
|
||||
"default": true,
|
||||
"workspace": "~/.openclaw/workspace",
|
||||
"sandbox": { "mode": "off" }
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="After (multi-agent)">
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"list": [
|
||||
{
|
||||
"id": "main",
|
||||
"default": true,
|
||||
"workspace": "~/.openclaw/workspace",
|
||||
"sandbox": { "mode": "off" }
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
Legacy `agent.*` configs are migrated by `openclaw doctor`; prefer `agents.defaults` + `agents.list` going forward.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Tool Restriction Examples
|
||||
## Tool restriction examples
|
||||
|
||||
### Read-only Agent
|
||||
<Tabs>
|
||||
<Tab title="Read-only agent">
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"allow": ["read"],
|
||||
"deny": ["exec", "write", "edit", "apply_patch", "process"]
|
||||
}
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Safe execution (no file modifications)">
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"allow": ["read", "exec", "process"],
|
||||
"deny": ["write", "edit", "apply_patch", "browser", "gateway"]
|
||||
}
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Communication-only">
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"sessions": { "visibility": "tree" },
|
||||
"allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
|
||||
"deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"allow": ["read"],
|
||||
"deny": ["exec", "write", "edit", "apply_patch", "process"]
|
||||
}
|
||||
}
|
||||
```
|
||||
`sessions_history` in this profile still returns a bounded, sanitized recall view rather than a raw transcript dump. Assistant recall strips thinking tags, `<relevant-memories>` scaffolding, plain-text tool-call XML payloads (including `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, and truncated tool-call blocks), downgraded tool-call scaffolding, leaked ASCII/full-width model control tokens, and malformed MiniMax tool-call XML before redaction/truncation.
|
||||
|
||||
### Safe Execution Agent (no file modifications)
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"allow": ["read", "exec", "process"],
|
||||
"deny": ["write", "edit", "apply_patch", "browser", "gateway"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Communication-only Agent
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"sessions": { "visibility": "tree" },
|
||||
"allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
|
||||
"deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`sessions_history` in this profile still returns a bounded, sanitized recall
|
||||
view rather than a raw transcript dump. Assistant recall strips thinking tags,
|
||||
`<relevant-memories>` scaffolding, plain-text tool-call XML payloads
|
||||
(including `<tool_call>...</tool_call>`,
|
||||
`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
|
||||
`<function_calls>...</function_calls>`, and truncated tool-call blocks),
|
||||
downgraded tool-call scaffolding, leaked ASCII/full-width model control
|
||||
tokens, and malformed MiniMax tool-call XML before redaction/truncation.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfall: "non-main"
|
||||
## Common pitfall: "non-main"
|
||||
|
||||
`agents.defaults.sandbox.mode: "non-main"` is based on `session.mainKey` (default `"main"`),
|
||||
not the agent id. Group/channel sessions always get their own keys, so they
|
||||
are treated as non-main and will be sandboxed. If you want an agent to never
|
||||
sandbox, set `agents.list[].sandbox.mode: "off"`.
|
||||
<Warning>
|
||||
`agents.defaults.sandbox.mode: "non-main"` is based on `session.mainKey` (default `"main"`), not the agent id. Group/channel sessions always get their own keys, so they are treated as non-main and will be sandboxed. If you want an agent to never sandbox, set `agents.list[].sandbox.mode: "off"`.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
@@ -325,55 +339,55 @@ sandbox, set `agents.list[].sandbox.mode: "off"`.
|
||||
|
||||
After configuring multi-agent sandbox and tools:
|
||||
|
||||
1. **Check agent resolution:**
|
||||
|
||||
```exec
|
||||
openclaw agents list --bindings
|
||||
```
|
||||
|
||||
2. **Verify sandbox containers:**
|
||||
|
||||
```exec
|
||||
docker ps --filter "name=openclaw-sbx-"
|
||||
```
|
||||
|
||||
3. **Test tool restrictions:**
|
||||
- Send a message requiring restricted tools
|
||||
- Verify the agent cannot use denied tools
|
||||
|
||||
4. **Monitor logs:**
|
||||
|
||||
```exec
|
||||
tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"
|
||||
```
|
||||
<Steps>
|
||||
<Step title="Check agent resolution">
|
||||
```bash
|
||||
openclaw agents list --bindings
|
||||
```
|
||||
</Step>
|
||||
<Step title="Verify sandbox containers">
|
||||
```bash
|
||||
docker ps --filter "name=openclaw-sbx-"
|
||||
```
|
||||
</Step>
|
||||
<Step title="Test tool restrictions">
|
||||
- Send a message requiring restricted tools.
|
||||
- Verify the agent cannot use denied tools.
|
||||
</Step>
|
||||
<Step title="Monitor logs">
|
||||
```bash
|
||||
tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Agent not sandboxed despite `mode: "all"`
|
||||
|
||||
- Check if there's a global `agents.defaults.sandbox.mode` that overrides it
|
||||
- Agent-specific config takes precedence, so set `agents.list[].sandbox.mode: "all"`
|
||||
|
||||
### Tools still available despite deny list
|
||||
|
||||
- Check tool filtering order: global → agent → sandbox → subagent
|
||||
- Each level can only further restrict, not grant back
|
||||
- Verify with logs: `[tools] filtering tools for agent:${agentId}`
|
||||
|
||||
### Container not isolated per agent
|
||||
|
||||
- Set `scope: "agent"` in agent-specific sandbox config
|
||||
- Default is `"session"` which creates one container per session
|
||||
<AccordionGroup>
|
||||
<Accordion title="Agent not sandboxed despite `mode: 'all'`">
|
||||
- Check if there's a global `agents.defaults.sandbox.mode` that overrides it.
|
||||
- Agent-specific config takes precedence, so set `agents.list[].sandbox.mode: "all"`.
|
||||
</Accordion>
|
||||
<Accordion title="Tools still available despite deny list">
|
||||
- Check tool filtering order: global → agent → sandbox → subagent.
|
||||
- Each level can only further restrict, not grant back.
|
||||
- Verify with logs: `[tools] filtering tools for agent:${agentId}`.
|
||||
</Accordion>
|
||||
<Accordion title="Container not isolated per agent">
|
||||
- Set `scope: "agent"` in agent-specific sandbox config.
|
||||
- Default is `"session"` which creates one container per session.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Sandboxing](/gateway/sandboxing) -- full sandbox reference (modes, scopes, backends, images)
|
||||
- [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) -- debugging "why is this blocked?"
|
||||
- [Elevated Mode](/tools/elevated)
|
||||
- [Multi-Agent Routing](/concepts/multi-agent)
|
||||
- [Sandbox Configuration](/gateway/config-agents#agentsdefaultssandbox)
|
||||
- [Session Management](/concepts/session)
|
||||
- [Elevated mode](/tools/elevated)
|
||||
- [Multi-agent routing](/concepts/multi-agent)
|
||||
- [Sandbox configuration](/gateway/config-agents#agentsdefaultssandbox)
|
||||
- [Sandbox vs tool policy vs elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) — debugging "why is this blocked?"
|
||||
- [Sandboxing](/gateway/sandboxing) — full sandbox reference (modes, scopes, backends, images)
|
||||
- [Session management](/concepts/session)
|
||||
|
||||
@@ -70,6 +70,9 @@ Gateway startup runtime-dependency repair.
|
||||
Explicit disablement still wins: `plugins.entries.<id>.enabled: false`,
|
||||
`plugins.deny`, `plugins.enabled: false`, and `channels.<id>.enabled: false`
|
||||
prevent automatic bundled runtime-dependency repair for that plugin/channel.
|
||||
A non-empty `plugins.allow` also bounds default-enabled bundled runtime-dependency
|
||||
repair; explicit bundled channel enablement (`channels.<id>.enabled: true`) can
|
||||
still repair that channel's plugin dependencies.
|
||||
External plugins and custom load paths must still be installed through
|
||||
`openclaw plugins install`.
|
||||
|
||||
@@ -87,6 +90,28 @@ Both show up under `openclaw plugins list`. See [Plugin Bundles](/plugins/bundle
|
||||
If you are writing a native plugin, start with [Building Plugins](/plugins/building-plugins)
|
||||
and the [Plugin SDK Overview](/plugins/sdk-overview).
|
||||
|
||||
## Package Entrypoints
|
||||
|
||||
Native plugin npm packages must declare `openclaw.extensions` in `package.json`.
|
||||
Each entry must stay inside the package directory and resolve to a readable
|
||||
runtime file, or to a TypeScript source file with an inferred built JavaScript
|
||||
peer such as `src/index.ts` to `dist/index.js`.
|
||||
|
||||
Use `openclaw.runtimeExtensions` when published runtime files do not live at the
|
||||
same paths as the source entries. When present, `runtimeExtensions` must contain
|
||||
exactly one entry for every `extensions` entry. Mismatched lists fail install and
|
||||
plugin discovery rather than silently falling back to source paths.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@acme/openclaw-plugin",
|
||||
"openclaw": {
|
||||
"extensions": ["./src/index.ts"],
|
||||
"runtimeExtensions": ["./dist/index.js"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Official plugins
|
||||
|
||||
### Installable (npm)
|
||||
@@ -199,6 +224,16 @@ OpenClaw scans for plugins in this order (first match wins):
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Packaged installs and Docker images normally resolve bundled plugins from the
|
||||
compiled `dist/extensions` tree. If a bundled plugin source directory is
|
||||
bind-mounted over the matching packaged source path, for example
|
||||
`/app/extensions/synology-chat`, OpenClaw treats that mounted source directory
|
||||
as a bundled source overlay and discovers it before the packaged
|
||||
`/app/dist/extensions/synology-chat` bundle. This keeps maintainer container
|
||||
loops working without switching every bundled plugin back to TypeScript source.
|
||||
Set `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` to force packaged dist bundles
|
||||
even when source overlay mounts are present.
|
||||
|
||||
### Enablement rules
|
||||
|
||||
- `plugins.enabled: false` disables all plugins
|
||||
@@ -337,8 +372,9 @@ plugins. It is not supported with `--link`, which reuses the source path instead
|
||||
of copying over a managed install target.
|
||||
|
||||
When `plugins.allow` is already set, `openclaw plugins install` adds the
|
||||
installed plugin id to that allowlist before enabling it, so installs are
|
||||
immediately loadable after restart.
|
||||
installed plugin id to that allowlist before enabling it. If the same plugin id
|
||||
is present in `plugins.deny`, install removes that stale deny entry so the
|
||||
explicit install is immediately loadable after restart.
|
||||
|
||||
OpenClaw keeps a persisted local plugin registry as the cold read model for
|
||||
plugin inventory, contribution ownership, and startup planning. Install, update,
|
||||
|
||||
Reference in New Issue
Block a user