diff --git a/docs/automation/cron-jobs.md b/docs/automation/cron-jobs.md index 4e8ffff63ecf..7c26fa4eb48a 100644 --- a/docs/automation/cron-jobs.md +++ b/docs/automation/cron-jobs.md @@ -330,7 +330,7 @@ Implicit announce delivery uses configured channel allowlists to validate and re Failure notifications follow a separate destination path: -- `cron.failureDestination` sets a global default for failure notifications. +- The destination fields on `cron.failureAlert` (`mode`, `channel`, `to`, `accountId`) set a global default for failure notifications. The retired `cron.failureDestination` block is merged into them by `openclaw doctor --fix`. - `job.delivery.failureDestination` overrides that per job. - If neither is set and the job already delivers via `announce`, failure notifications fall back to that primary announce target. - `delivery.failureDestination` is only supported on `sessionTarget="isolated"` jobs unless the primary delivery mode is `webhook`. diff --git a/docs/cli/audit.md b/docs/cli/audit.md index e66678e882dd..0314a3839521 100644 --- a/docs/cli/audit.md +++ b/docs/cli/audit.md @@ -13,10 +13,10 @@ Query the Gateway's metadata-only audit ledger for agent runs, tool actions, and opt-in message lifecycle records. The ledger is on by default for run and tool events. Set -[`audit.enabled: false`](/gateway/configuration-reference#audit) and restart the -Gateway to stop all new event records. Message records are separately disabled by -default; set `audit.messages` to `direct` or `all` and restart the Gateway to -record them. Existing records stay queryable until they expire (30 days). +[`logging.audit.enabled: false`](/gateway/configuration-reference#audit) and +restart the Gateway to stop all new event records. Message records are +separately disabled by default; set `logging.audit.messages` to `direct` or +`all` and restart the Gateway to record them. Existing records stay queryable until they expire (30 days). The ledger is separate from conversation transcripts: it records identity, ordering, provenance, action, status, and normalized outcome codes, but never diff --git a/docs/cli/cron.md b/docs/cli/cron.md index a96e671ae391..88297ea7376f 100644 --- a/docs/cli/cron.md +++ b/docs/cli/cron.md @@ -101,7 +101,7 @@ Reminders created from an active chat preserve the live chat delivery target for Failure notifications resolve in this order: 1. `delivery.failureDestination` on the job. -2. Global `cron.failureDestination`. +2. The global destination fields on `cron.failureAlert` (`mode`, `channel`, `to`, `accountId`). The retired `cron.failureDestination` block is merged into them by `openclaw doctor --fix`. 3. The job's primary announce target (when neither of the above resolves to a concrete destination). diff --git a/docs/cli/security.md b/docs/cli/security.md index 9773405a69b0..e556671f8299 100644 --- a/docs/cli/security.md +++ b/docs/cli/security.md @@ -123,7 +123,6 @@ Applies safe, deterministic remediations: - flips common `groupPolicy="open"` to `groupPolicy="allowlist"` (including account variants in supported channels) - when WhatsApp group policy flips to `allowlist`, seeds `groupAllowFrom` from the stored `allowFrom` file when that list exists and config does not already define `allowFrom` -- sets `logging.redactSensitive` from `"off"` to `"tools"` - tightens permissions for state/config and common sensitive files (`credentials/*.json`, `auth-profiles.json`, `openclaw-agent.sqlite`, and legacy session artifacts) - also tightens config include files referenced from `openclaw.json` - uses `chmod` on POSIX hosts and `icacls` resets on Windows diff --git a/docs/diagnostics/flags.md b/docs/diagnostics/flags.md index 3406923c0a63..4a211944f8fc 100644 --- a/docs/diagnostics/flags.md +++ b/docs/diagnostics/flags.md @@ -162,7 +162,7 @@ Named profiles use `/tmp/openclaw/openclaw--YYYY-MM-DD.log`; for example, `--dev` uses `openclaw-dev-YYYY-MM-DD.log`. If you set `logging.file`, use that path instead. Logs are JSONL (one JSON -object per line). Redaction still applies based on `logging.redactSensitive`. +object per line). Redaction still applies; it is always on. See [Logging](/logging) for the full log-path resolution, rotation, and redaction model. diff --git a/docs/docs_map.md b/docs/docs_map.md index 65075180196a..5a7554db3558 100644 --- a/docs/docs_map.md +++ b/docs/docs_map.md @@ -3477,7 +3477,6 @@ Do not edit it by hand; run `pnpm docs:map:gen`. - H2: Bridge (legacy, removed) - H2: Cron - H3: cron.failureAlert - - H3: cron.failureDestination - H2: Media model template variables - H2: Config includes ($include) - H2: Related diff --git a/docs/gateway/audit.md b/docs/gateway/audit.md index 6f66fc0af439..be9e816fff55 100644 --- a/docs/gateway/audit.md +++ b/docs/gateway/audit.md @@ -38,7 +38,7 @@ field reference and query filters. ## Message lifecycle events -Set [`audit.messages`](/gateway/configuration-reference#audit) to choose what +Set [`logging.audit.messages`](/gateway/configuration-reference#audit) to choose what is recorded, then restart the Gateway: - `off` (default): no message records. diff --git a/docs/gateway/configuration-examples.md b/docs/gateway/configuration-examples.md index aa793bbbc998..59ddb4e22d76 100644 --- a/docs/gateway/configuration-examples.md +++ b/docs/gateway/configuration-examples.md @@ -97,7 +97,6 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number. file: "/tmp/openclaw/openclaw.log", consoleLevel: "info", consoleStyle: "pretty", - redactSensitive: "tools", }, // Message formatting diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 58621b24ee75..870d2e35147a 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -1197,9 +1197,11 @@ Notes: ```json5 { - audit: { - enabled: true, - messages: "off", // off | direct | all + logging: { + audit: { + enabled: true, + messages: "off", // off | direct | all + }, }, } ``` @@ -1229,7 +1231,12 @@ and coverage limits. available. These are correlation aids rather than anonymization; the state database stores the derivation key, but RPC and CLI exports do not. -The running Gateway captures `audit.enabled` and `audit.messages` at startup; +A root-level `audit` block is retired; the canonical path is `logging.audit`. +The root config object is strict, so an old top-level `audit` block is rejected. +Run [`openclaw doctor --fix`](/cli/doctor) to move it to `logging.audit`. + +The running Gateway captures `logging.audit.enabled` and +`logging.audit.messages` at startup; restart it after changing either setting. Message coverage currently includes accepted inbound messages that reach core dispatch and one terminal row per original logical outbound reply payload that reaches shared durable delivery. @@ -1247,8 +1254,7 @@ writer is best-effort, not a lossless compliance archive. level: "info", file: "/tmp/openclaw/openclaw.log", consoleLevel: "info", - consoleStyle: "pretty", // pretty | compact | json - redactSensitive: "tools", // off | tools + consoleStyle: "pretty", // pretty | json redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"], }, } @@ -1257,8 +1263,10 @@ writer is best-effort, not a lossless compliance archive. - Default log file: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`; named profiles use `/tmp/openclaw/openclaw--YYYY-MM-DD.log`. - Set `logging.file` for a stable path. - `consoleLevel` bumps to `debug` when `--verbose`. +- `consoleStyle`: `"pretty"` or `"json"`. The earlier `"compact"` value is retired; [`openclaw doctor --fix`](/cli/doctor) maps it to `"pretty"`. - `maxFileBytes`: maximum active log file size in bytes before rotation (positive integer; default: `104857600` = 100 MB). OpenClaw keeps up to five numbered archives beside the active file. -- `redactSensitive` / `redactPatterns`: best-effort masking for console output, file logs, OTLP log records, and persisted session transcript text. `redactSensitive: "off"` only disables this general log/transcript policy; UI/tool/diagnostic safety surfaces still redact secrets before emission. +- `redactPatterns`: regexes for best-effort masking of console output, file logs, OTLP log records, and persisted session transcript text. Setting this **replaces** the built-in default patterns for log and transcript output, so include the defaults you still want; omitting them also turns off form-body and structured auth-header redaction. Tool payload redaction is separate and always merges your patterns with the defaults. +- Redaction is always on and is no longer configurable. The retired `logging.redactSensitive` switch (including its `"off"` value) is removed by [`openclaw doctor --fix`](/cli/doctor); the runtime always applies `tools`-mode redaction to logs and transcripts. UI, tool, and diagnostic safety surfaces redact secrets independently of this policy. --- @@ -1444,17 +1452,27 @@ Current builds no longer include the TCP bridge. Nodes connect over the Gateway { cron: { enabled: true, - webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs + triggers: { + enabled: true, + }, webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth sessionRetention: "24h", // duration string or false }, } ``` +- `enabled`: execute stored cron jobs (default: `true`). Set `false` to pause all cron execution without deleting jobs. +- `triggers.enabled`: also run event-driven cron triggers (default: `false`). - `sessionRetention`: how long to keep completed isolated cron run sessions before pruning SQLite session rows. Also controls cleanup of archived deleted cron transcripts. Default: `24h`; set `false` to disable. - Run history automatically keeps the newest 2000 terminal rows per job. Lost rows retain their 24-hour cleanup window. - `webhookToken`: bearer token used for cron webhook POST delivery (`delivery.mode = "webhook"`), if omitted no auth header is sent. -- `webhook`: deprecated legacy fallback webhook URL (http/https) used by `openclaw doctor --fix` to migrate stored jobs that still have `notify: true`; runtime delivery uses per-job `delivery.mode="webhook"` plus `delivery.to`, or `delivery.completionDestination` when preserving announce delivery. + +The `cron` block is strict; `cron.enabled`, `cron.triggers`, `cron.webhookToken`, +`cron.sessionRetention`, and `cron.failureAlert` are the only accepted keys. The +retired `cron.webhook` fallback URL is gone: runtime delivery uses per-job +`delivery.mode = "webhook"` plus `delivery.to`, or `delivery.completionDestination` +when preserving announce delivery. `openclaw doctor --fix` strips a leftover +`cron.webhook` from existing config files. ### `cron.failureAlert` @@ -1463,29 +1481,9 @@ Current builds no longer include the TCP bridge. Nodes connect over the Gateway cron: { failureAlert: { enabled: false, - after: 3, + after: 2, cooldownMs: 3600000, includeSkipped: false, - mode: "announce", - accountId: "main", - }, - }, -} -``` - -- `enabled`: enable failure alerts for cron jobs (default: `false`). -- `after`: consecutive failures before an alert fires (positive integer, min: `1`). -- `cooldownMs`: minimum milliseconds between repeated alerts for the same job (non-negative integer). -- `includeSkipped`: count consecutive skipped runs toward the alert threshold (default: `false`). Skipped runs are tracked separately and do not affect execution-error backoff. -- `mode`: delivery mode - `"announce"` sends via a channel message; `"webhook"` posts to the configured webhook. -- `accountId`: optional account or channel id to scope alert delivery. - -### `cron.failureDestination` - -```json5 -{ - cron: { - failureDestination: { mode: "announce", channel: "last", to: "channel:C1234567890", @@ -1495,12 +1493,19 @@ Current builds no longer include the TCP bridge. Nodes connect over the Gateway } ``` -- Default destination for cron failure notifications across all jobs. -- `mode`: `"announce"` or `"webhook"`; defaults to `"announce"` when enough target data exists. +`cron.failureAlert` owns both the alert threshold and the default failure +destination for every job. The retired `cron.failureDestination` block is merged +into it by [`openclaw doctor --fix`](/cli/doctor). + +- `enabled`: enable failure alerts for cron jobs (default: `false`). +- `after`: consecutive failures before an alert fires (positive integer, min: `1`; default: `2`). +- `cooldownMs`: minimum milliseconds between repeated alerts for the same job (non-negative integer; default: `3600000`). +- `includeSkipped`: count consecutive skipped runs toward the alert threshold (default: `false`). Skipped runs are tracked separately and do not affect execution-error backoff. +- `mode`: delivery mode - `"announce"` sends via a channel message; `"webhook"` posts to the target in `to`. Defaults to `"announce"` when enough target data exists. - `channel`: channel override for announce delivery. `"last"` reuses the last known delivery channel. - `to`: explicit announce target or webhook URL. Required for webhook mode. -- `accountId`: optional account override for delivery. -- Per-job `delivery.failureDestination` overrides this global default. +- `accountId`: optional account or channel id to scope alert delivery. +- Per-job `delivery.failureDestination` overrides these global destination fields. - When neither global nor per-job failure destination is set, jobs that already deliver via `announce` fall back to that primary announce target on failure. - `delivery.failureDestination` is only supported for `sessionTarget="isolated"` jobs unless the job's primary `delivery.mode` is `"webhook"`. diff --git a/docs/gateway/logging.md b/docs/gateway/logging.md index 26a9e9f0a6a3..a6b53324c29e 100644 --- a/docs/gateway/logging.md +++ b/docs/gateway/logging.md @@ -52,7 +52,7 @@ The CLI captures `console.log/info/warn/error/debug/trace`, writes them to file Tune console verbosity independently: - `logging.consoleLevel` (default `info`) -- `logging.consoleStyle` (`pretty` | `compact` | `json`; defaults to `pretty` on a TTY, `compact` otherwise) +- `logging.consoleStyle` (`pretty` | `json`). When unset, output is `pretty` on a TTY and the automatic `compact` style otherwise. `compact` is no longer a settable value; `openclaw doctor --fix` maps a stored one to `pretty`. ## Redaction diff --git a/docs/gateway/opentelemetry.md b/docs/gateway/opentelemetry.md index cbf5cece0b40..c48369eb902f 100644 --- a/docs/gateway/opentelemetry.md +++ b/docs/gateway/opentelemetry.md @@ -536,7 +536,7 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway ``` Flag output goes to the standard log file (`logging.file`) and is still -redacted by `logging.redactSensitive`. Full guide: +redacted by the always-on log redaction policy. Full guide: [Diagnostics flags](/diagnostics/flags). ## Disable diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md index fc62ab8fc906..7af9c25a2e63 100644 --- a/docs/gateway/protocol.md +++ b/docs/gateway/protocol.md @@ -783,8 +783,9 @@ and may drop records on failure or saturation, so this surface is not a lossless compliance archive. Recording is on by default and controlled by -[`audit.enabled`](/gateway/configuration-reference#audit). Message recording is -separately controlled by `audit.messages` and defaults to `"off"`. When +[`logging.audit.enabled`](/gateway/configuration-reference#audit). Message +recording is separately controlled by `logging.audit.messages` and defaults to +`"off"`. When recording is disabled, `audit.activity.list` keeps serving records written earlier until they expire. diff --git a/docs/gateway/security/audit-checks.md b/docs/gateway/security/audit-checks.md index 147651a6719d..962231f1e9b3 100644 --- a/docs/gateway/security/audit-checks.md +++ b/docs/gateway/security/audit-checks.md @@ -81,7 +81,6 @@ exhaustive): | `hooks.installs_unpinned_npm_specs` | warn | Hook install records are not pinned to immutable npm specs | hook install metadata | no | | `hooks.installs_missing_integrity` | warn | Hook install records lack integrity metadata | hook install metadata | no | | `hooks.installs_version_drift` | warn | Hook install records drift from installed packages | hook install metadata | no | -| `logging.redact_off` | warn | Sensitive values leak to logs/status | `logging.redactSensitive` | yes | | `browser.control_invalid_config` | warn | Browser control config is invalid before runtime | `browser.*` | no | | `browser.control_no_auth` | critical | Browser control exposed without token/password auth | `gateway.auth.*` | no | | `browser.remote_cdp_http` | warn | Remote CDP over plain HTTP lacks transport encryption | browser profile `cdpUrl` | no | diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index a5fae7c045cf..ed55e72e6e0d 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -39,7 +39,7 @@ openclaw security audit --fix # apply safe remediations openclaw security audit --json ``` -`--fix` is intentionally narrow: it flips open group policies to allowlists, restores `logging.redactSensitive: "tools"`, tightens state/config/include-file permissions (`600` files, `700` dirs), and on Windows uses ACL resets instead of POSIX `chmod`. +`--fix` is intentionally narrow: it flips open group policies to allowlists, tightens state/config/include-file permissions (`600` files, `700` dirs), and on Windows uses ACL resets instead of POSIX `chmod`. ### What the audit checks (high level) @@ -780,7 +780,7 @@ OpenClaw stores session transcripts on disk under `~/.openclaw/agents// Gateway logs may include tool summaries, errors, and URLs; session transcripts can include pasted secrets, file contents, command output, and links. -- Keep log/transcript redaction on (`logging.redactSensitive: "tools"`, default). +- Log/transcript redaction is always on and cannot be disabled by config. - Add custom patterns for your environment via `logging.redactPatterns` (tokens, hostnames, internal URLs). - When sharing diagnostics, prefer `openclaw status --all` (pasteable, secrets redacted) over raw logs. - Prune old session transcripts and log files if you do not need long retention. diff --git a/docs/logging.md b/docs/logging.md index 61d8775ec986..018593dc10c1 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -196,7 +196,6 @@ All logging configuration lives under `logging` in `~/.openclaw/openclaw.json`. "file": "/path/to/openclaw.log", "consoleLevel": "info", "consoleStyle": "pretty", - "redactSensitive": "tools", "redactPatterns": ["sk-.*"] } } @@ -289,12 +288,16 @@ OTEL model-call spans/metrics when diagnostics export is enabled. ### Console styles -`logging.consoleStyle`: +`logging.consoleStyle` accepts `pretty` or `json`: - `pretty`: human-friendly, colored, with timestamps. -- `compact`: tighter output (best for long sessions). - `json`: JSON per line (for log processors). +A third rendering style, `compact` (tighter output, best for long sessions), is +applied automatically when stdout is not a TTY. It is no longer a settable +config value; `openclaw doctor --fix` maps a stored `consoleStyle: "compact"` +to `"pretty"`. + ### Redaction OpenClaw can redact sensitive tokens before they hit console output, file logs, diff --git a/docs/reference/memory-config.md b/docs/reference/memory-config.md index d1ce46a64aa9..d7c3cbb1d5eb 100644 --- a/docs/reference/memory-config.md +++ b/docs/reference/memory-config.md @@ -448,10 +448,10 @@ Concurrency, polling, and timeout behavior are provider-owned. Index session transcripts and surface them via `memory_search`: -| Key | Type | Default | Description | -| ----------------------------- | ---------- | ------------ | ---------------------------------------- | -| `rememberAcrossConversations` | `boolean` | `false` | Permit private cross-conversation recall | -| `sources` | `string[]` | `["memory"]` | Add `"sessions"` to include transcripts | +| Key | Type | Default | Description | +| ----------------------------- | ---------- | ---------------------------------------------------------- | ---------------------------------------- | +| `rememberAcrossConversations` | `boolean` | On for personal installs; off with configured DM isolation | Permit private cross-conversation recall | +| `sources` | `string[]` | `["memory"]` | Add `"sessions"` to include transcripts | Session indexing is opt-in and runs asynchronously. Results can be slightly stale. Session logs live on disk, so treat filesystem access as the trust boundary. diff --git a/docs/tools/tool-search.md b/docs/tools/tool-search.md index 26bea4bb3d77..3c8083f406ef 100644 --- a/docs/tools/tool-search.md +++ b/docs/tools/tool-search.md @@ -282,15 +282,23 @@ Disable it: ## Prompt and telemetry -Tool Search records enough telemetry to compare it with direct tool exposure: +Code mode attaches a `telemetry` object to every `tool_search_code` result: -- total serialized tool and prompt bytes sent to the harness -- catalog size and source breakdown -- search, describe, and call counts -- final tool calls executed through OpenClaw -- selected tool ids and sources +- `catalogSize`: number of catalog entries the runtime resolved +- `sources`: catalog entry counts split into `openclaw`, `mcp`, and `client` +- `searchCount`, `describeCount`, `callCount`: running totals for the catalog + session, carried across calls rather than reset per call -Session logs should make it possible to answer: +`tools` and `directory` mode emit no telemetry object; their `tool_search`, +`tool_describe`, and `tool_call` results carry only the catalog data for that +operation. OpenClaw does not record serialized tool or prompt byte counts. The +[E2E scenario](#e2e-validation) measures provider payload bytes separately from +the mock provider lane, not from the runtime. + +Regardless of mode, target tool calls are projected into the session transcript +as normal tool call and tool result pairs, and search, describe, and call +results carry each tool's `id` and `source`. Session logs therefore still +answer: - how many tool schemas the model saw up front - how many search and describe operations it performed