openclaw security CLI Reference

`openclaw security`

Security tooling: audit mode, plus 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

Plain security audit remains on the cold config/filesystem/read-only path: it never picks up 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 auth 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 is raised when multiple DM senders share the main session, with a recommendation for 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; split trust boundaries with separate gateways (or separate OS users/hosts) for that.
security.trust_model.group_scope_main is emitted when global session.groupScope="main" or a binding override merges group/channel rooms into the main session. Every member of each matched room shares that context, so reserve this for trusted rooms (see Groups).
security.trust_model.multi_user_heuristic is emitted when config suggests likely shared-user ingress (for example open DM/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/private identities or credentials off that runtime.
A warning appears when small models (<=300B parameters) run without sandboxing while web/browser tools are enabled.

Webhook/hooks

Startup logs a non-fatal security warning, 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). Additional warnings 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 fires when sandbox Docker settings are configured while sandbox mode is off.
A warning fires when gateway.nodes.commands.deny uses ineffective pattern-like/unknown entries (matching is exact node command-name only, not shell-text filtering).
A warning fires when gateway.nodes.commands.allow explicitly enables dangerous node commands.
A warning fires when global tools.profile="minimal" is overridden by agent tool profiles.
A warning fires when write/edit tools are disabled but exec is still available without a constraining sandbox filesystem boundary.
A warning fires when open DMs or groups expose runtime/filesystem tools without sandbox/workspace guards.
A warning fires when installed plugin tools may be reachable under permissive tool policy.

Sandbox browser

A warning fires 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 fires when existing sandbox browser Docker containers have missing/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 (header-spoofing risk if proxies are misconfigured).
discovery.mdns.mode="full" is flagged (metadata leakage via mDNS TXT records).
A warning fires 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 fires when npm-based plugin/hook install records are unpinned, missing integrity metadata, or drift from currently installed package versions.
A warning fires when channel allowlists rely on mutable names/emails/tags instead of stable IDs (Discord, Slack, Google Chat, Microsoft Teams, Mattermost, IRC scopes where applicable).

Settings prefixed with dangerous/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 and/or detailIncludes substrings:

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

Suppressed findings no longer appear in the active summary and findings list. For audit purposes, JSON output retains them under suppressedFindings. When suppression rules are in place, the active output additionally includes an security.audit.suppressions.active info finding that cannot be suppressed, letting readers recognize that the audit was filtered. Dangerous configuration flags are reported individually, one per finding, so approving a single dangerous flag does not conceal other enabled flags that share the same config.insecure_or_dangerous_flags checkId.

Since suppressions can mask ongoing risk, adding or removing them via agent-run shell commands demands exec approval, unless 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'

When --fix --json is enabled, output covers both fix actions and the final report:

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

What `--fix` changes

Performs safe, deterministic remediations:

switches common groupPolicy="open" to groupPolicy="allowlist" (including account variants in supported channels)
when WhatsApp group policy changes to allowlist, populates groupAllowFrom from the stored allowFrom file, provided that list exists and config does not already specify allowFrom
restricts permissions for state/config and common sensitive files (credentials/*.json, legacy auth-profiles.json, openclaw-agent.sqlite, and legacy session artifacts)
also restricts config include files referenced from openclaw.json
applies chmod on POSIX hosts and icacls resets on Windows

--fix will not:

rotate tokens/passwords/API keys
disable tools (gateway, cron, exec, etc.)
modify gateway bind/auth/network exposure settings
remove or rewrite plugins/skills