English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

CLI commands

보안

openclaw security

보안 도구(감사 + 선택적 수정).

관련 항목:

감사

bash
openclaw security auditopenclaw security audit --deepopenclaw security audit --deep --password <password>openclaw security audit --deep --token <token>openclaw security audit --fixopenclaw security audit --json

일반 security audit는 차가운 설정/파일 시스템/읽기 전용 경로에 머뭅니다. 기본적으로 Plugin 런타임 보안 수집기를 찾지 않으므로, 일상적인 감사가 설치된 모든 Plugin 런타임을 로드하지 않습니다. 최선 노력 방식의 라이브 Gateway 프로브와 Plugin 소유 보안 감사 수집기를 포함하려면 --deep을 사용하세요. 명시적인 내부 호출자도 적절한 런타임 범위를 이미 가지고 있을 때 해당 Plugin 소유 수집기를 선택적으로 사용할 수 있습니다.

감사는 여러 DM 발신자가 기본 세션을 공유할 때 경고하고 보안 DM 모드를 권장합니다: 공유 받은 편지함에는 session.dmScope="per-channel-peer"(또는 다중 계정 채널에는 per-account-channel-peer). 이는 협력적/공유 받은 편지함 강화를 위한 것입니다. 상호 신뢰하지 않거나 적대적인 운영자가 단일 Gateway를 공유하는 구성은 권장되지 않습니다. 별도 Gateway(또는 별도 OS 사용자/호스트)로 신뢰 경계를 나누세요. 또한 설정이 공유 사용자 인그레스 가능성을 시사할 때(예: 열린 DM/그룹 정책, 구성된 그룹 대상, 와일드카드 발신자 규칙) security.trust_model.multi_user_heuristic을 내보내며, OpenClaw가 기본적으로 개인 비서 신뢰 모델임을 알려 줍니다. 의도적인 공유 사용자 구성의 경우 감사 지침은 모든 세션을 샌드박스화하고, 파일 시스템 접근을 작업 공간 범위로 제한하며, 개인/비공개 신원 또는 자격 증명을 해당 런타임에 두지 않는 것입니다. 또한 작은 모델(<=300B)을 샌드박스 없이 사용하면서 웹/브라우저 도구를 활성화한 경우 경고합니다. Webhook 인그레스의 경우, 시작 시 치명적이지 않은 보안 경고를 로그에 남기고 감사는 hooks.token이 gateway.auth.token / OPENCLAW_GATEWAY_TOKEN 및 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD를 포함한 활성 Gateway 공유 비밀 인증 값을 재사용하는지 플래그로 표시합니다. 또한 다음 경우에도 경고합니다.

  • hooks.token이 짧음
  • hooks.path="/"
  • hooks.defaultSessionKey가 설정되지 않음
  • hooks.allowedAgentIds가 제한되지 않음
  • 요청 sessionKey 재정의가 활성화됨
  • hooks.allowedSessionKeyPrefixes 없이 재정의가 활성화됨

Gateway 비밀번호 인증이 시작 시에만 제공되는 경우, 감사가 이를 hooks.token과 대조할 수 있도록 같은 값을 openclaw security audit --auth password --password <password>에 전달하세요. 지속 저장된 재사용 hooks.token을 회전하려면 openclaw doctor --fix를 실행한 다음, 외부 훅 발신자가 새 훅 토큰을 사용하도록 업데이트하세요.

샌드박스 모드가 꺼진 상태에서 샌드박스 Docker 설정이 구성된 경우, gateway.nodes.denyCommands가 효과 없는 패턴형/알 수 없는 항목을 사용하는 경우(셸 텍스트 필터링이 아니라 정확한 node 명령 이름 일치만 해당), gateway.nodes.allowCommands가 위험한 node 명령을 명시적으로 활성화하는 경우, 전역 tools.profile="minimal"이 에이전트 도구 프로필로 재정의되는 경우, 쓰기/편집 도구가 비활성화되었지만 제약적인 샌드박스 파일 시스템 경계 없이 exec가 여전히 사용 가능한 경우, 열린 DM 또는 그룹이 샌드박스/작업 공간 보호 없이 런타임/파일 시스템 도구를 노출하는 경우, 그리고 설치된 Plugin 도구가 허용적인 도구 정책 아래에서 접근 가능할 수 있는 경우에도 경고합니다. 또한 gateway.allowRealIpFallback=true(프록시가 잘못 구성된 경우 헤더 스푸핑 위험)와 discovery.mdns.mode="full"(mDNS TXT 레코드를 통한 메타데이터 유출)을 플래그로 표시합니다. 또한 샌드박스 브라우저가 sandbox.browser.cdpSourceRange 없이 Docker bridge 네트워크를 사용하는 경우 경고합니다. 또한 위험한 샌드박스 Docker 네트워크 모드(host 및 container:* 네임스페이스 조인 포함)를 플래그로 표시합니다. 또한 기존 샌드박스 브라우저 Docker 컨테이너에 누락되었거나 오래된 해시 라벨이 있는 경우(예: openclaw.browserConfigEpoch가 없는 마이그레이션 전 컨테이너) 경고하고 openclaw sandbox recreate --browser --all을 권장합니다. 또한 npm 기반 Plugin/훅 설치 레코드가 고정되지 않았거나, 무결성 메타데이터가 없거나, 현재 설치된 패키지 버전과 차이가 있는 경우 경고합니다. 채널 허용 목록이 안정적인 ID 대신 변경 가능한 이름/이메일/태그에 의존하는 경우 경고합니다(해당되는 범위의 Discord, Slack, Google Chat, Microsoft Teams, Mattermost, IRC). gateway.auth.mode="none"가 공유 비밀 없이 Gateway HTTP API에 접근 가능하게 남겨 두는 경우 경고합니다(/tools/invoke 및 활성화된 모든 /v1/* 엔드포인트). dangerous/dangerously 접두사가 붙은 설정은 명시적인 비상 운영자 재정의입니다. 이를 활성화하는 것만으로는 보안 취약점 보고가 아닙니다. 전체 위험 매개변수 목록은 보안의 "안전하지 않거나 위험한 플래그 요약" 섹션을 참조하세요.

의도적인 상시 발견 항목은 security.audit.suppressions로 수락할 수 있습니다. 각 억제는 정확한 checkId와 일치하며, 대소문자를 구분하지 않는 부분 문자열인 titleIncludes 및/또는 detailIncludes로 범위를 좁힐 수 있습니다.

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

억제된 발견 항목은 활성 summary와 findings 목록에서 제거됩니다. JSON 출력은 감사 가능성을 위해 이를 suppressedFindings 아래에 유지합니다. 억제가 구성된 경우, 활성 출력은 억제할 수 없는 security.audit.suppressions.active 정보 발견 항목도 유지하므로 독자가 감사가 필터링되었음을 알 수 있습니다. 위험한 설정 플래그는 발견 항목 하나당 플래그 하나로 내보내므로, 위험한 플래그 하나를 수락해도 같은 config.insecure_or_dangerous_flags checkId를 공유하는 다른 활성화된 플래그가 숨겨지지 않습니다. 억제는 상시 위험을 숨길 수 있으므로, 에이전트 실행 셸 명령을 통해 억제를 추가하거나 제거하려면 신뢰할 수 있는 로컬 자동화를 위해 exec가 이미 security="full" 및 ask="off"로 실행 중인 경우가 아니라면 exec 승인이 필요합니다.

SecretRef 동작:

  • security audit는 대상 경로에 대해 지원되는 SecretRef를 읽기 전용 모드에서 확인합니다.
  • 현재 명령 경로에서 SecretRef를 사용할 수 없는 경우, 감사는 중단되지 않고 계속 진행하며 secretDiagnostics를 보고합니다.
  • --token 및 --password는 해당 명령 호출의 심층 프로브 인증만 재정의합니다. 설정 또는 SecretRef 매핑을 다시 작성하지 않습니다.

JSON 출력

CI/정책 검사에는 --json을 사용하세요.

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

--fix와 --json을 함께 사용하면 출력에 수정 작업과 최종 보고서가 모두 포함됩니다.

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

--fix가 변경하는 내용

--fix는 안전하고 결정적인 개선을 적용합니다.

  • 일반적인 groupPolicy="open"을 groupPolicy="allowlist"로 전환합니다(지원되는 채널의 계정 변형 포함).
  • WhatsApp 그룹 정책이 allowlist로 전환될 때, 저장된 allowFrom 파일의 목록이 존재하고 설정이 아직 allowFrom을 정의하지 않은 경우 그 목록으로 groupAllowFrom을 시드합니다.
  • logging.redactSensitive를 "off"에서 "tools"로 설정합니다.
  • 상태/설정 및 일반적인 민감 파일의 권한을 강화합니다. (credentials/*.json, auth-profiles.json, sessions.json, 세션 *.jsonl)
  • openclaw.json에서 참조하는 설정 include 파일도 강화합니다.
  • POSIX 호스트에서는 chmod를, Windows에서는 icacls 재설정을 사용합니다.

--fix는 다음을 수행하지 않습니다.

  • 토큰/비밀번호/API 키 회전
  • 도구 비활성화(gateway, cron, exec 등)
  • Gateway 바인드/인증/네트워크 노출 선택 변경
  • Plugin/Skills 제거 또는 재작성

관련 항목

Was this useful?
On this page

On this page