openclaw security: CLI audit and fix

`openclaw security`

Security auditing with optional safe remediation. See also: Security.

openclaw security audit
openclaw security audit --deep
openclaw security audit --deep --password <password>
openclaw security audit --deep --token <token>
openclaw security audit --auth password --password <password>
openclaw security audit --fix
openclaw security audit --json

Audit modes

In its default mode, security audit operates on the cold config, filesystem, and read-only paths. It does not detect plugin runtime security collectors, so routine audits avoid loading every installed plugin runtime. --deep adds best-effort live Gateway probes and plugin owned security audit collectors. Explicit internal callers may also opt into those collectors when they already have an appropriate runtime scope.

If Gateway password authentication is provided only at startup, supply the same value with --auth password --password <password> so the audit can verify it against hooks.token.

What it checks

DM/trust model

A warning appears when multiple DM senders share the main session, recommending secure DM mode: session.dmScope="per-channel-peer" (or per-account-channel-peer for multi-account channels) for shared inboxes. This is cooperative shared-inbox hardening, not isolation for mutually untrusted operators. For that, split trust boundaries using separate gateways or separate OS users or hosts.
security.trust_model.multi_user_heuristic is emitted when the config suggests likely shared-user ingress, for example open DM or group policy, configured group targets, or wildcard sender rules. OpenClaw's default trust model is personal assistant (one operator), not hostile multi-tenant isolation. For intentional shared-user setups: sandbox all sessions, keep filesystem access workspace scoped, and keep personal or private identities or credentials off that runtime.
A warning is issued when small models (<=300B parameters) are used without sandboxing and with web or browser tools enabled.

Webhook/hooks

At startup a non-fatal security warning is logged, and audit flags hooks.token reuse of active Gateway shared-secret auth values (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN, gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD). Warnings also occur when:

hooks.token is short
hooks.path="/"
hooks.defaultSessionKey is unset
hooks.allowedAgentIds is unrestricted
request sessionKey overrides are enabled
overrides are enabled without hooks.allowedSessionKeyPrefixes

Run openclaw doctor --fix to rotate a persisted reused hooks.token, then update external hook senders to use the new token.

Sandbox/tools

A warning appears when sandbox Docker settings are configured but sandbox mode is off.
A warning appears when gateway.nodes.commands.deny uses ineffective pattern-like or unknown entries. Matching is exact node command name only, not shell-text filtering.
A warning appears when gateway.nodes.commands.allow explicitly enables dangerous node commands.
A warning appears when global tools.profile="minimal" is overridden by agent tool profiles.
A warning appears when write or edit tools are disabled but exec is still available without a constraining sandbox filesystem boundary.
A warning appears when open DMs or groups expose runtime or filesystem tools without sandbox or workspace guards.
A warning appears when installed plugin tools may be reachable under a permissive tool policy.

Sandbox browser

A warning appears when sandbox browser uses Docker bridge network without sandbox.browser.cdpSourceRange.
Dangerous sandbox Docker network modes are flagged, including host and container:* namespace joins.
A warning appears when existing sandbox browser Docker containers have missing or stale hash labels, for example pre-migration containers missing openclaw.browserConfigEpoch, and recommends openclaw sandbox recreate --browser --all.

Network/discovery

gateway.allowRealIpFallback=true is flagged, posing a header-spoofing risk if proxies are misconfigured.
discovery.mdns.mode="full" is flagged, indicating metadata leakage via mDNS TXT records.
A warning appears when gateway.auth.mode="none" leaves Gateway HTTP APIs reachable without a shared secret (/tools/invoke plus any enabled /v1/* endpoint).

Plugins/channels

A warning appears when npm based plugin or hook install records are unpinned, missing integrity metadata, or drift from currently installed package versions.
A warning appears when channel allowlists rely on mutable names, emails, or tags instead of stable IDs. This applies to Discord, Slack, Google Chat, Microsoft Teams, Mattermost, and IRC scopes where applicable.

Settings prefixed with dangerous or dangerously are explicit break-glass operator overrides. Enabling one is not, by itself, a security vulnerability report. For the complete dangerous-parameter inventory, see "Insecure or dangerous flags summary" in Security.

SecretRef behavior

security audit resolves supported SecretRefs in read-only mode for its targeted paths. If a SecretRef is unavailable in the current command path, audit continues and reports secretDiagnostics instead of crashing. --token and --password only override deep-probe auth for that command invocation. They do not rewrite config or SecretRef mappings.

Suppressions

Accept intentional standing findings with security.audit.suppressions. Each suppression matches an exact checkId and can be narrowed with case-insensitive titleIncludes or detailIncludes substrings:

{
  "security": {
    "audit": {
      "suppressions": [
        {
          "checkId": "plugins.tools_reachable_permissive_policy",
          "detailIncludes": "Enabled extension plugins: gbrain",
          "reason": "trusted local operator plugin"
        }
      ]
    }
  }
}

Suppressed findings are removed from the active summary and findings list. JSON output keeps them under suppressedFindings for auditability. When suppressions are configured, active output also keeps an unsuppressible security.audit.suppressions.active info finding so readers can tell the audit was filtered. Dangerous config flags are emitted one flag per finding, so accepting one dangerous flag does not hide other enabled flags that share the same config.insecure_or_dangerous_flags checkId.

When suppressions are added or removed through agent shell commands, exec approval is required because they can conceal active risk. The only exception is when exec is already operating with security="full" and ask="off" for trusted local automation.

JSON output

openclaw security audit --json | jq '.summary'
openclaw security audit --deep --json | jq '.findings[] | select(.severity=="critical") | .checkId'

With --fix --json, both the fix actions and the final report appear in the output:

openclaw security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summary}'

What `--fix` changes

Applies safe, deterministic remediations:

common groupPolicy="open" values are switched to groupPolicy="allowlist", including account variants within supported channels
when a WhatsApp group policy changes to allowlist, groupAllowFrom is seeded from the stored allowFrom file if that list exists and no allowFrom is already defined in the config
logging.redactSensitive is set from "off" to "tools"
permissions are tightened for state/config and commonly sensitive files: credentials/*.json, auth-profiles.json, openclaw-agent.sqlite, and legacy session artifacts
config include files referenced from openclaw.json also get tightened permissions
on POSIX hosts chmod is used, while Windows relies on icacls resets

--fix does not:

rotate tokens, passwords, or API keys
disable tools like gateway, cron, exec, and others
alter gateway bind, authentication, or network exposure settings
remove or rewrite plugins or skills