Security

기준일: 2026-07-26
공식 기준: Security

Security 문서는 OpenClaw 공식 문서(cli/security)를 한국어로 정리한 가이드입니다. CLI reference for openclaw security (audit and fix common security footguns) 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

CLI reference for openclaw security (audit and fix common security footguns)

한국어 가이드 범위: cli/security 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Audit modes
• What it checks
• SecretRef behavior
• Suppressions
• JSON output
• What --fix changes
• 관련 문서

상세 내용

openclaw security

Security tools: audit plus optional safe fixes. 관련: Security.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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 stays on the cold config/filesystem/read-only path: it does not discover plugin runtime security collectors, so routine audits do not load 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).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

What it checks

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). Also warns when:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Warns when multiple DM senders share the main session and recommends 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.
• Emits security.trust_model.multi_user_heuristic 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.
• Warns when small models (<=300B parameters) are used without sandboxing and with web/browser tools enabled.
• 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
• Warns when sandbox Docker settings are configured while sandbox mode is off.
• Warns when gateway.nodes.commands.deny uses ineffective pattern-like/unknown entries (matching is exact node command-name only, not shell-text filtering).
• Warns when gateway.nodes.commands.allow explicitly enables dangerous node commands.
• Warns when global tools.profile="minimal" is overridden by agent tool profiles.
• Warns when write/edit tools are disabled but exec is still available without a constraining sandbox filesystem boundary.
• Warns when open DMs or groups expose runtime/filesystem tools without sandbox/workspace guards.
• Warns when installed plugin tools may be reachable under permissive tool policy.
• Warns when sandbox browser uses Docker bridge network without sandbox.browser.cdpSourceRange.
• Flags dangerous sandbox Docker network modes, including host and container:* namespace joins.
• Warns 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.
• Flags gateway.allowRealIpFallback=true (header-spoofing risk if proxies are misconfigured).
• Flags discovery.mdns.mode="full" (metadata leakage via mDNS TXT records).
• Warns when gateway.auth.mode="none" leaves Gateway HTTP APIs reachable without a shared secret (/tools/invoke plus any enabled /v1/* endpoint).
• Warns when npm-based plugin/hook install records are unpinned, missing integrity metadata, or drift from currently installed package versions.
• Warns when channel allowlists rely on mutable names/emails/tags instead of stable IDs (Discord, Slack, Google Chat, Microsoft Teams, Mattermost, IRC scopes where applicable).

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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

JSON output

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

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

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

What --fix changes

Applies safe, deterministic remediations:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• 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
• rotate tokens/passwords/API keys
• disable tools (gateway, cron, exec, etc.)
• change gateway bind/auth/network exposure choices
• remove or rewrite plugins/skills

관련 문서

주요 항목:

• CLI reference
• Security audit

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/cli/security
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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

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

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

관련 링크

• 공식 원문: cli/security
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.