--- read_when: - 접근성 또는 자동화 범위를 확장하는 기능 추가 summary: 셸 접근 권한이 있는 AI Gateway 실행을 위한 보안 고려 사항 및 위협 모델 title: 보안 x-i18n: generated_at: "2026-07-12T15:19:11Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 15 provider: openai source_hash: 70b6c42ec5bc4f93aae50c18c9e112520f1cb93305da827a7c6cae8b81ca7bf8 source_path: gateway/security/index.md workflow: 16 --- **개인 비서 신뢰 모델.** 이 지침은 Gateway마다 하나의 신뢰할 수 있는 운영자 경계가 있다고 가정합니다(단일 사용자 개인 비서 모델). OpenClaw는 하나의 에이전트나 Gateway를 공유하는 여러 적대적 사용자를 위한 적대적 멀티테넌트 보안 경계가 **아닙니다**. 신뢰 수준이 혼재하거나 적대적 사용자가 있는 환경에서는 신뢰 경계를 분리하십시오. Gateway와 자격 증명을 각각 분리하고, 가능하면 OS 사용자나 호스트도 분리하십시오. ## 범위: 개인 비서 보안 모델 - 지원됨: Gateway마다 하나의 사용자/신뢰 경계(경계마다 하나의 OS 사용자/호스트/VPS를 사용하는 것이 좋습니다). - 지원되지 않음: 상호 신뢰하지 않거나 적대적인 사용자가 하나의 공유 Gateway/에이전트를 사용하는 구성. - 적대적 사용자 격리에는 별도의 Gateway가 필요하며, 가능하면 OS 사용자/호스트도 분리해야 합니다. - 신뢰할 수 없는 여러 사용자가 도구 사용이 활성화된 하나의 에이전트에 메시지를 보낼 수 있다면, 해당 에이전트에 위임된 도구 권한을 공유하게 됩니다. - 누군가 Gateway 호스트의 상태/구성(`openclaw.json`을 포함한 `~/.openclaw`)을 수정할 수 있다면 신뢰할 수 있는 운영자로 간주하십시오. - 하나의 Gateway 내에서 인증된 운영자 액세스는 사용자별 테넌트 역할이 아니라 신뢰할 수 있는 제어 영역 역할입니다. - `sessionKey`(세션 ID, 레이블)는 라우팅 선택자이지 권한 부여 토큰이 아닙니다. 여러 사용자나 조직을 호스팅합니까? 하나의 Gateway를 공유하지 말고 테넌트마다 격리된 Gateway 셀을 하나씩 실행하십시오. [멀티테넌트 호스팅](/gateway/multi-tenant-hosting)을 참조하십시오. 원격 액세스, DM 정책, 리버스 프록시 또는 공개 노출을 변경하기 전에 [Gateway 노출 실행 지침서](/ko/gateway/security/exposure-runbook)를 사전 점검/롤백 체크리스트로 확인하십시오. ## `openclaw security audit` 구성을 변경한 후 또는 네트워크 표면을 노출하기 전에 다음을 실행하십시오. ```bash openclaw security audit openclaw security audit --deep # 실시간 Gateway 프로브를 시도합니다 openclaw security audit --fix # 안전한 수정 조치를 적용합니다 openclaw security audit --json ``` `--fix`의 범위는 의도적으로 제한적입니다. 개방형 그룹 정책을 허용 목록으로 전환하고, `logging.redactSensitive: "tools"`를 복원하며, 상태/구성/include 파일의 권한을 강화합니다(파일은 `600`, 디렉터리는 `700`). Windows에서는 POSIX `chmod` 대신 ACL 재설정을 사용합니다. ### 감사에서 확인하는 항목(개요) - **인바운드 액세스** - DM/그룹 정책과 허용 목록: 낯선 사람이 봇을 작동시킬 수 있습니까? - **도구 피해 범위** - 승격된 도구 + 개방된 대화방: 프롬프트 인젝션이 셸/파일/네트워크 작업으로 이어질 수 있습니까? - **Exec 파일 시스템 드리프트** - 파일 시스템을 변경하는 도구는 거부되지만 `exec`/`process`는 샌드박스 제약 없이 계속 사용할 수 있는 상태. - **Exec 승인 드리프트** - `security="full"`, `autoAllowSkills`, `strictInlineEval`이 없는 인터프리터 허용 목록. `security="full"`만으로는 버그의 증거가 아니라 광범위한 보안 태세에 대한 경고입니다. 이는 신뢰할 수 있는 개인 비서 구성에서 선택되는 기본값이며, 위협 모델에 승인 또는 허용 목록 보호 장치가 필요한 경우에만 강화하십시오. - **네트워크 노출** - Gateway 바인딩/인증, Tailscale Serve/Funnel, 취약하거나 짧은 인증 토큰. - **브라우저 제어 노출** - 원격 Node, 릴레이 포트, 원격 CDP 엔드포인트. - **로컬 디스크 위생** - 권한, 심볼릭 링크, 구성 include, 동기화 폴더 경로. - **Plugin** - 명시적인 허용 목록 없이 로드되는 항목. - **정책 드리프트** - 샌드박스 Docker 설정은 구성되어 있지만 샌드박스 모드는 꺼져 있는 상태, 효과가 있는 것처럼 보이지만 페이로드 안의 셸 텍스트가 아니라 정확한 명령 ID(예: `system.run`)에만 일치하는 `gateway.nodes.denyCommands` 항목, 위험한 `gateway.nodes.allowCommands` 항목, 에이전트별로 재정의된 전역 `tools.profile="minimal"`, 허용적인 정책에서 접근할 수 있는 Plugin 소유 도구. - **런타임 예상 드리프트** - `tools.exec.host`의 기본값이 이제 `auto`인데도 암시적 exec가 여전히 `sandbox`를 의미한다고 가정하거나, 샌드박스 모드가 꺼진 상태에서 `tools.exec.host="sandbox"`를 설정하는 경우. - **모델 위생** - 구성된 레거시 모델에 대해 경고합니다(약한 경고이며 강제 차단이 아닙니다). 각 발견 항목에는 구조화된 `checkId`가 있습니다(예: `gateway.bind_no_auth`, `tools.exec.security_full_configured`). 접두사: `fs.*`(권한), `gateway.*`(바인딩/인증/Tailscale/Control UI/신뢰할 수 있는 프록시), `hooks.*`/`browser.*`/`sandbox.*`/`tools.exec.*`(표면별 강화), `plugins.*`/`skills.*`(공급망), `security.exposure.*`(액세스 정책 x 도구 피해 범위). 심각도와 자동 수정 지원을 포함한 전체 목록은 [보안 감사 검사 항목](/ko/gateway/security/audit-checks)을 참조하십시오. [형식 검증](/ko/security/formal-verification)도 참조하십시오. ### 발견 항목 분류 시 우선순위 1. "개방" 상태이면서 도구가 활성화된 모든 항목: 먼저 DM/그룹을 제한하고(페어링/허용 목록), 그다음 도구 정책/샌드박싱을 강화하십시오. 2. 공개 네트워크 노출(LAN 바인딩, Funnel, 인증 누락): 즉시 수정하십시오. 3. 브라우저 제어 원격 노출: 운영자 액세스처럼 취급하십시오(tailnet 전용, Node를 의도적으로 페어링, 공개 노출 금지). 4. 권한: 상태/구성/자격 증명/인증 정보는 그룹/모든 사용자가 읽을 수 없어야 합니다. 5. Plugin: 명시적으로 신뢰하는 항목만 로드하십시오. 6. 모델 선택: 도구를 사용하는 모든 봇에는 최신의 명령어 강화 모델을 권장합니다. ## 60초 내에 적용하는 강화된 기준 구성 ```json5 { gateway: { mode: "local", bind: "loopback", auth: { mode: "token", token: "replace-with-long-random-token" }, }, session: { dmScope: "per-channel-peer", }, tools: { profile: "messaging", deny: ["group:automation", "group:runtime", "group:fs", "sessions_spawn", "sessions_send"], fs: { workspaceOnly: true }, exec: { security: "deny", ask: "always" }, elevated: { enabled: false }, }, channels: { whatsapp: { dmPolicy: "pairing", groups: { "*": { requireMention: true } } }, }, } ``` Gateway를 로컬 전용으로 유지하고, DM을 격리하며, 제어 영역/런타임 도구를 기본적으로 비활성화합니다. 이후 신뢰할 수 있는 에이전트별로 도구를 선택적으로 다시 활성화하십시오. 채팅 기반 에이전트 턴에 적용되는 기본 제공 기준: 소유자가 아닌 발신자는 구성과 관계없이 `cron` 또는 `gateway` 도구를 사용할 수 없습니다. ## 신뢰 경계 매트릭스 위험 보고서를 분류하기 위한 간략한 모델: | 경계 또는 제어 | 의미 | 흔한 오해 | | --------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- | | `gateway.auth` (토큰/비밀번호/신뢰할 수 있는 프록시/기기 인증) | Gateway API 호출자를 인증합니다 | "보안을 유지하려면 모든 프레임에 메시지별 서명이 필요하다" | | `sessionKey` | 컨텍스트/세션 선택을 위한 라우팅 키 | "세션 키는 사용자 인증 경계이다" | | 프롬프트/콘텐츠 보호 장치 | 모델 악용 위험을 줄입니다 | "프롬프트 인젝션만으로 인증 우회가 입증된다" | | `canvas.eval` / 브라우저 evaluate | 활성화 시 의도적으로 제공되는 운영자 기능 | "모든 JS eval 프리미티브는 이 신뢰 모델에서 자동으로 취약점이다" | | 로컬 TUI `!` 셸 | 운영자가 명시적으로 실행하는 로컬 작업 | "로컬 셸 편의 명령은 원격 인젝션이다" | | Node 페어링 및 Node 명령 | 페어링된 기기에서 운영자 수준의 원격 실행 | "원격 기기 제어는 기본적으로 신뢰할 수 없는 사용자 액세스로 취급해야 한다" | | `gateway.nodes.pairing.autoApproveCidrs` | 옵트인 방식의 신뢰 네트워크 Node 등록 정책 | "기본적으로 비활성화된 허용 목록은 자동 페어링 취약점이다" | | `gateway.nodes.pairing.sshVerify` | 운영자 SSH를 통한 키 검증 Node 등록 | "기본적으로 활성화된 자동 승인은 자동 페어링 취약점이다" | ## 설계상 취약점이 아닌 항목 - 정책, 인증 또는 샌드박스 우회가 없는 프롬프트 인젝션만의 공격 연쇄. - 하나의 공유 호스트 또는 구성을 적대적 멀티테넌트 환경으로 가정하는 주장. - 공유 Gateway 구성에서 정상적인 운영자 읽기 경로 액세스(예: `sessions.list` / `sessions.preview` / `chat.history`)를 IDOR로 분류하는 경우. - localhost 전용 배포의 발견 항목(예: 루프백 전용 Gateway에서 HSTS 누락). - 이 저장소에 존재하지 않는 인바운드 경로에 대한 Discord 인바운드 Webhook 서명 관련 발견 항목. - Node 페어링 메타데이터를 `system.run`에 대한 숨겨진 두 번째 명령별 승인 계층으로 취급하는 경우. 실제 실행 경계는 Gateway의 전역 Node 명령 정책과 Node 자체의 exec 승인입니다. - `gateway.nodes.pairing.sshVerify`가 기본적으로 활성화되어 있다는 이유로 취약점으로 취급하는 경우. 네트워크 위치나 SSH 접근 가능성만으로는 절대 승인하지 않습니다. Gateway는 SSH(BatchMode, 엄격한 호스트 키)를 통해 기기 ID를 다시 읽고, 대기 중인 요청의 기기 키와 정확히 일치하는 경우에만 승인합니다. 이를 위해서는 연결 키 쌍이 운영자가 제어하는 호스트의 운영자 계정에 이미 존재해야 합니다. 프로브는 비공개/CGNAT 원본 주소로 제한되며, 신뢰할 수 있는 CIDR 자격 조건(범위가 없는 신규 `role: node`만 해당)을 공유합니다. `sshVerify: false`로 설정하면 이 기능이 꺼집니다. - `gateway.nodes.pairing.autoApproveCidrs` 자체를 취약점으로 취급하는 경우. 기본적으로 비활성화되어 있고, 명시적인 CIDR/IP 항목이 필요하며, 요청된 범위가 없는 최초 `role: node` 페어링에만 적용됩니다. 운영자/브라우저/Control UI, WebChat, 역할/범위 승격, 메타데이터 또는 공개 키 변경, 동일 호스트 루프백의 신뢰할 수 있는 프록시 헤더 경로는 절대 자동 승인하지 않습니다(루프백의 신뢰할 수 있는 프록시 인증이 활성화된 경우에도 마찬가지입니다). - `sessionKey`를 인증 토큰으로 취급하는 "사용자별 권한 부여 누락" 발견 항목. ## Gateway 및 Node 신뢰 Gateway와 Node를 역할이 다른 하나의 운영자 신뢰 도메인으로 취급하십시오. - **Gateway**: 제어 영역 및 정책 표면(`gateway.auth`, 도구 정책, 라우팅). - **Node**: 해당 Gateway와 페어링된 원격 실행 표면(명령, 기기 작업, 호스트 로컬 기능). - Gateway에 인증된 호출자는 Gateway 범위에서 신뢰됩니다. 페어링 후 Node 작업은 해당 Node에서 신뢰할 수 있는 운영자 작업으로 간주됩니다. [운영자 범위](/ko/gateway/operator-scopes)를 참조하십시오. - 공유 Gateway 토큰/비밀번호로 인증된 직접 루프백 백엔드 클라이언트는 사용자 기기 ID를 제시하지 않고도 내부 제어 영역 RPC를 수행할 수 있습니다. 이는 원격 또는 브라우저 페어링 우회가 아닙니다. 네트워크 클라이언트, Node 클라이언트, 기기 토큰 클라이언트 및 명시적 기기 ID에는 계속 페어링과 범위 승격 적용이 시행됩니다. - Exec 승인(허용 목록 + 확인)은 운영자 의도를 위한 보호 장치이지 적대적 멀티테넌트 격리를 위한 것이 아닙니다. 정확한 요청 컨텍스트와 최선형 방식의 직접 로컬 파일 피연산자를 결합하지만, 모든 런타임/인터프리터 로더 경로를 의미론적으로 모델링하지는 않습니다. 강력한 경계가 필요하면 샌드박싱과 호스트 격리를 사용하십시오. - 신뢰할 수 있는 단일 운영자 기본값: `gateway`/`node`의 호스트 exec는 승인 프롬프트 없이 허용됩니다(`security="full"`, `ask="off"`). 이는 의도된 UX이며 그 자체로는 취약점이 아닙니다. 적대적 사용자 격리가 필요하다면 OS 사용자/호스트별로 신뢰 경계를 분리하고 별도의 Gateway를 실행하십시오. ## 위협 모델 AI 비서는 임의의 셸 명령 실행, 파일 읽기/쓰기, 네트워크 서비스 액세스 및 모든 사람에게 메시지 전송을 수행할 수 있습니다(채널 액세스 권한이 부여된 경우). 메시지를 보내는 사람은 AI 비서를 속여 악의적인 작업을 수행하게 하거나, 소셜 엔지니어링으로 데이터 액세스를 얻거나, 인프라 세부 정보를 탐색하려고 할 수 있습니다. 여기서 발생하는 대부분의 실패는 특이한 익스플로잇이 아니라 "누군가 봇에 메시지를 보냈고 봇이 요청받은 작업을 수행한" 경우입니다. OpenClaw의 대응 원칙은 다음 순서로 적용됩니다. 1. **ID 우선** - 봇과 대화할 수 있는 사람을 결정합니다(DM 페어링 / 허용 목록 / 명시적 "open"). 2. **범위 다음** - 봇이 작업할 수 있는 위치를 결정합니다(그룹 허용 목록 + 멘션 게이팅, 도구, 샌드박싱, 기기 권한). 3. **모델 마지막** - 모델이 조작될 수 있다고 가정하고, 조작되더라도 피해 범위가 제한되도록 설계합니다. ## DM 액세스: 페어링, 허용 목록, 공개, 비활성화 DM을 지원하는 모든 채널은 메시지가 처리되기 전에 수신 DM을 제한하는 `dmPolicy`(또는 `*.dm.policy`)를 지원합니다. | 정책 | 동작 | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pairing` | 기본값입니다. 알 수 없는 발신자에게 페어링 코드가 제공되며, 승인될 때까지 봇은 해당 발신자를 무시합니다. 코드는 1시간 후 만료되며, 새 요청이 생성되기 전까지 DM을 반복해서 보내도 코드가 다시 전송되지 않습니다. 대기 중인 요청은 채널당 최대 3개로 제한됩니다. | | `allowlist` | 알 수 없는 발신자를 차단하며 페어링 핸드셰이크를 수행하지 않습니다. | | `open` | 누구나 DM을 보낼 수 있습니다(공개). 채널 허용 목록에 `"*"`를 포함해야 합니다(명시적 동의). | | `disabled` | 수신 DM을 완전히 무시합니다. | ```bash openclaw pairing list openclaw pairing approve ``` 세부 정보 및 디스크상의 파일: [페어링](/ko/channels/pairing) `dmPolicy="open"` 및 `groupPolicy="open"` 설정은 최후의 수단으로 간주하십시오. 대화방의 모든 구성원을 완전히 신뢰하지 않는다면 페어링과 허용 목록을 사용하는 것이 좋습니다. ### 허용 목록(2개 계층) - **DM 허용 목록** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; 레거시: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): 봇에 DM을 보낼 수 있는 사용자를 지정합니다. `dmPolicy="pairing"`인 경우 승인이 `~/.openclaw/credentials/-allowFrom.json`(기본 계정) 또는 `--allowFrom.json`(기본 계정이 아닌 계정)에 기록되고 구성의 허용 목록과 병합됩니다. - **그룹 허용 목록**(채널별): 봇이 허용하는 그룹/채널/길드를 지정합니다. - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: `requireMention`과 같은 그룹별 기본값입니다. 설정하면 그룹 허용 목록으로도 작동합니다(모두 허용하는 동작을 유지하려면 `"*"`를 포함하십시오). `agents.list[].groupChat.mentionPatterns`(예: `["@openclaw", "@mybot"]`)를 사용하여 멘션 트리거를 맞춤 설정하면 `requireMention`이 자체 봇 이름을 기준으로 제한하도록 할 수 있습니다. - `groupPolicy="allowlist"` + `groupAllowFrom`: 그룹 세션 내에서 봇을 트리거할 수 있는 사용자를 제한합니다(WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). - `channels.discord.guilds` / `channels.slack.channels`: 표면별 허용 목록 및 멘션 기본값입니다. - 확인 순서: 먼저 `groupPolicy`/그룹 허용 목록을 확인한 다음 멘션/답글 활성화를 확인합니다. 봇 메시지에 답글을 작성하는 것(암시적 멘션)은 `groupAllowFrom`을 **우회하지 않습니다**. 세부 정보: [구성](/ko/gateway/configuration) 및 [그룹](/ko/channels/groups) ### DM 세션 격리(다중 사용자 모드) 기본적으로 OpenClaw는 기기 간 연속성을 위해 모든 DM을 기본 세션으로 라우팅합니다. 여러 사람이 봇에 DM을 보낼 수 있는 경우(공개 DM 또는 여러 사람이 포함된 허용 목록) DM 세션을 격리하십시오. ```json5 { session: { dmScope: "per-channel-peer" } } ``` `session.dmScope` 값: | 값 | 범위 | | -------------------------- | ----------------------------------------------------------------------- | | `main`(구성 기본값) | 모든 DM이 하나의 세션을 공유합니다. | | `per-channel-peer` | 각 채널+발신자 쌍에 격리된 DM 컨텍스트가 부여됩니다(보안 DM 모드). | | `per-account-channel-peer` | 위와 같지만 계정별로 추가 분리됩니다(다중 계정 채널). | | `per-peer` | 각 발신자가 같은 유형의 모든 채널에서 하나의 세션을 사용합니다. | 로컬 CLI 온보딩은 설정되지 않은 경우 `session.dmScope: "per-channel-peer"`를 기록하며, 명시적으로 지정된 기존 값은 그대로 유지합니다. 이는 메시징 컨텍스트 경계이지 호스트 관리자 경계가 아닙니다. 서로 적대적인 사용자들이 동일한 Gateway 호스트/구성을 공유하는 경우에는 신뢰 경계별로 별도의 Gateway를 실행하십시오. 동일한 사람이 여러 채널을 통해 연락하는 경우 `session.identityLinks`를 사용하여 해당 DM 세션들을 하나의 정규 ID로 통합하십시오. [세션 관리](/ko/concepts/session) 및 [구성](/ko/gateway/configuration)을 참조하십시오. ## 컨텍스트 가시성과 트리거 권한 부여 두 가지 별개의 개념이 있습니다. - **트리거 권한 부여**: 에이전트를 트리거할 수 있는 사용자(`dmPolicy`, `groupPolicy`, 허용 목록, 멘션 제한)입니다. - **컨텍스트 가시성**: 모델에 전달되는 보충 컨텍스트(답글 본문, 인용문, 스레드 기록, 전달된 메타데이터)입니다. `contextVisibility`는 두 번째 항목을 제어합니다. - `"all"`(기본값): 수신한 보충 컨텍스트를 그대로 유지합니다. - `"allowlist"`: 활성 허용 목록 검사에서 허용된 발신자의 보충 컨텍스트만 전송하도록 필터링합니다. - `"allowlist_quote"`: `allowlist`와 같지만, 명시적으로 인용된 답글 하나는 계속 유지합니다. 채널별 또는 방/대화별로 설정합니다. [그룹](/ko/channels/groups#context-visibility-and-allowlists)을 참조하십시오. "모델이 허용 목록에 없는 발신자가 작성한 인용/과거 텍스트를 볼 수 있다"는 내용만 보여 주는 보고서는 그 자체로 인증 또는 샌드박스 우회가 아니라 `contextVisibility`로 해결할 수 있는 보안 강화 문제입니다. 보안에 영향을 미치는 보고서로 인정되려면 신뢰 경계 우회를 입증해야 합니다. ## 프롬프트 인젝션 공격자는 모델을 조작하여 안전하지 않은 작업을 수행하게 하는 메시지("지침을 무시해라", "파일 시스템을 덤프해라", "이 링크를 열고 명령을 실행해라")를 작성합니다. 프롬프트 인젝션은 시스템 프롬프트의 가드레일만으로는 **해결되지 않습니다**. 이는 유연한 지침일 뿐이며, 강제적인 보호는 도구 정책, 실행 승인, 샌드박싱, 채널 허용 목록에서 제공됩니다. 단, 운영자는 설계에 따라 이러한 보호를 비활성화할 수 있습니다. 프롬프트 인젝션에는 공개 DM이 필요하지 않습니다. 봇에 메시지를 보낼 수 있는 사람이 본인뿐이더라도 봇이 읽는 모든 **신뢰할 수 없는 콘텐츠**(웹 검색/가져오기 결과, 브라우저 페이지, 이메일, 문서, 첨부 파일, 붙여 넣은 로그/코드)에 적대적 지침이 포함될 수 있습니다. 위협 표면은 발신자뿐만 아니라 콘텐츠 자체이기도 합니다. 신뢰할 수 없는 것으로 취급해야 하는 위험 신호: - "이 파일/URL을 읽고 적힌 내용을 정확히 수행해라." - "시스템 프롬프트나 안전 규칙을 무시해라." - "숨겨진 지침이나 도구 출력을 공개해라." - "~/.openclaw 또는 로그의 전체 내용을 붙여 넣어라." 실제로 도움이 되는 조치: - 수신 DM을 제한하십시오(페어링/허용 목록). 그룹에서는 멘션 게이팅을 우선 사용하고 공개 방에서 상시 작동하는 봇은 피하십시오. - 링크, 첨부 파일, 붙여 넣은 지침을 기본적으로 적대적인 것으로 취급하십시오. - 민감한 도구는 샌드박스에서 실행하고, 에이전트가 접근할 수 있는 파일 시스템에 비밀을 두지 마십시오. 샌드박싱은 명시적으로 활성화해야 합니다. 샌드박스 모드가 꺼져 있으면 암시적 `host=auto`는 Gateway 호스트로 해석되지만, 명시적 `host=sandbox`는 계속 안전하게 실패합니다(사용 가능한 샌드박스 런타임이 없음). 설정에서 이 동작을 명시하려면 `host=gateway`를 설정하십시오. - 고위험 도구(`exec`, `browser`, `web_fetch`, `web_search`)는 신뢰할 수 있는 에이전트나 명시적 허용 목록으로 제한하십시오. - 인터프리터(`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`)를 허용 목록에 추가하는 경우 인라인 평가 형식(`-c`, `-e` 등)에 계속 명시적 승인이 필요하도록 `tools.exec.strictInlineEval`을 활성화하십시오. 허용 목록 모드에서는 인용 방식과 관계없이 모든 heredoc 구간(`<<`)에 항상 검토자 승인 또는 명시적 승인이 필요합니다. 허용된 명령이 heredoc 본문을 이용해 허용 목록 검토를 우회할 수는 없습니다. - 읽기 전용 또는 도구가 비활성화된 **리더 에이전트**로 신뢰할 수 없는 콘텐츠를 요약한 다음, 그 요약을 주 에이전트에 전달하여 피해 범위를 줄이십시오. - 도구가 활성화된 에이전트에서는 필요한 경우가 아니라면 `web_search` / `web_fetch` / `browser`를 비활성화하십시오. - OpenResponses URL 입력(`input_file` / `input_image`)의 경우 엄격한 `gateway.http.endpoints.responses.files.urlAllowlist` / `images.urlAllowlist`를 설정하고 `maxUrlParts`를 낮게 유지하십시오(빈 허용 목록은 설정되지 않은 것으로 간주됨). URL 가져오기를 완전히 비활성화하려면 `files.allowUrl: false` / `images.allowUrl: false`를 사용하십시오. - 프롬프트에 비밀을 넣지 말고 Gateway 호스트의 환경 변수/설정을 통해 전달하십시오. **모델 선택은 중요합니다.** 프롬프트 인젝션에 대한 내성은 모델 등급마다 동일하지 않습니다. 더 작고 저렴한 모델은 적대적 프롬프트에 의한 도구 오용과 지침 탈취에 더 취약합니다. 도구가 활성화된 에이전트나 신뢰할 수 없는 콘텐츠를 읽는 에이전트에서는 이전 세대/소형 모델의 프롬프트 인젝션 위험이 지나치게 높은 경우가 많습니다. 이러한 워크로드를 성능이 낮은 모델 등급에서 실행하지 마십시오. - 도구를 실행하거나 파일/네트워크에 접근할 수 있는 모든 봇에는 최신 세대의 최상위 모델을 사용하십시오. - 도구가 활성화된 에이전트나 신뢰할 수 없는 받은편지함에는 이전/저성능/소형 모델 등급을 사용하지 마십시오. - 소형 모델을 사용해야 한다면 피해 범위를 줄이십시오. 읽기 전용 도구, 강력한 샌드박싱, 최소한의 파일 시스템 접근 권한, 엄격한 허용 목록을 사용하십시오. 모든 세션에서 샌드박싱을 활성화하고 입력이 엄격하게 통제되지 않는 한 `web_search`/`web_fetch`/`browser`를 비활성화하십시오. - 신뢰할 수 있는 입력만 받고 도구를 사용하지 않는 채팅 전용 개인 비서에는 일반적으로 소형 모델도 적합합니다. ### 외부 콘텐츠 및 신뢰할 수 없는 입력 래핑 OpenResponses `input_file` 텍스트는 Gateway가 로컬에서 디코딩하더라도 신뢰할 수 없는 외부 콘텐츠로 계속 삽입됩니다. 해당 블록에는 `<<>>` 경계 마커와 `Source: External` 메타데이터가 포함됩니다(이 경로에서는 다른 곳에서 사용하는 더 긴 `SECURITY NOTICE:` 배너를 생략함). 미디어 이해 기능이 첨부 문서에서 텍스트를 추출한 후 미디어 프롬프트에 추가할 때도 동일한 마커 기반 래핑이 적용됩니다. OpenClaw는 래핑된 외부 콘텐츠와 메타데이터가 모델에 도달하기 전에 일반적인 자체 호스팅 LLM 채팅 템플릿 특수 토큰 리터럴(Qwen/ChatML, Llama, Gemma, Mistral, Phi, GPT-OSS 역할/턴 토큰)도 제거합니다. 자체 호스팅 OpenAI 호환 백엔드(vLLM, SGLang, TGI, LM Studio, 맞춤형 Hugging Face 토크나이저 스택)는 사용자 콘텐츠 내부의 `<|im_start|>` 또는 `<|start_header_id|>` 같은 리터럴 문자열을 구조적인 채팅 템플릿 토큰으로 토큰화하는 경우가 있습니다. 이러한 정제 과정이 없으면 가져온 페이지, 이메일 본문 또는 파일 콘텐츠 도구 출력에 포함된 신뢰할 수 없는 텍스트가 합성 `assistant`/`system` 역할 경계를 위조할 수 있습니다. 정제는 외부 콘텐츠 래핑 계층에서 이루어지므로 가져오기/읽기 도구와 수신 채널 콘텐츠 전체에 일관되게 적용됩니다. 호스팅 제공자(OpenAI, Anthropic)는 이미 자체적인 요청 측 정제를 적용합니다. 외부 콘텐츠 래핑을 활성화된 상태로 유지하고, 가능한 경우 특수 토큰을 분리하거나 이스케이프하는 백엔드 설정을 우선 사용하십시오. 아웃바운드 모델 응답에는 별도의 정제기가 있으며, 최종 채널 전달 경계에서 사용자에게 표시되는 답변에 유출된 ``, ``, ``, `` 및 이와 유사한 내부 스캐폴딩을 제거합니다. 이는 `dmPolicy`, 허용 목록, 실행 승인, 샌드박싱 또는 `contextVisibility`를 대체하지 않으며, 특정 토크나이저 계층 우회 하나만 차단합니다. ### 우회 플래그(프로덕션에서는 비활성화 유지) - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` - Cron 페이로드 필드 `allowUnsafeExternalContent` 범위가 엄격하게 제한된 디버깅을 위해서만 일시적으로 활성화하십시오. 활성화할 경우 해당 에이전트를 격리하십시오(샌드박스 + 최소한의 도구 + 전용 세션 네임스페이스). 전달이 사용자가 제어하는 시스템에서 이루어지더라도 Hook 페이로드는 신뢰할 수 없는 콘텐츠입니다(메일/문서/웹 콘텐츠에 프롬프트 인젝션이 포함될 수 있음). 성능이 낮은 모델 등급은 이러한 위험을 높입니다. Hook 기반 자동화에는 성능이 우수한 최신 모델 등급을 우선 사용하고, 엄격한 도구 정책(`tools.profile: "messaging"` 또는 그보다 엄격한 정책)과 가능한 경우 샌드박싱을 적용하십시오. ### 그룹에서의 추론 및 상세 출력 `/reasoning`, `/verbose`, `/trace`는 공개 채널에 노출해서는 안 되는 내부 추론, 도구 출력 또는 Plugin 진단 정보를 드러낼 수 있습니다. 여기에는 도구 인수, URL, Plugin 진단 정보, 모델이 본 데이터가 포함될 수 있습니다. 공개 대화방에서는 비활성화하고 신뢰할 수 있는 DM이나 엄격하게 통제되는 대화방에서만 활성화하십시오. ## 명령 권한 부여 슬래시 명령과 지시문은 채널 허용 목록/페어링 및 `commands.useAccessGroups`에서 파생된 권한 있는 발신자에 대해서만 적용됩니다([구성](/ko/gateway/configuration) 및 [슬래시 명령](/ko/tools/slash-commands) 참조). 채널 허용 목록이 비어 있거나 `"*"`를 포함하면 해당 채널에서는 사실상 누구나 명령을 사용할 수 있습니다. `/exec`는 권한 있는 운영자를 위한 세션 전용 편의 기능입니다. 구성을 기록하거나 다른 세션을 변경하지 않습니다. ## 제어 영역 도구 두 가지 기본 제공 도구가 영구적인 변경을 수행할 수 있습니다. - `gateway`는 `config.schema.lookup` / `config.get`으로 구성을 검사하고 `config.apply`, `config.patch`, `update.run`으로 변경합니다. - `cron`은 원래 채팅/작업이 종료된 후에도 계속 실행되는 예약 작업을 생성합니다. `gateway config.apply`/`config.patch`는 기본적으로 허용되지 않은 작업을 차단합니다. 위험도가 낮은 에이전트 런타임 조정(`agents.defaults.thinkingDefault`, 에이전트별 모델/사고/추론/고속 모드 필드), 멘션 게이팅(여러 중첩 깊이의 `channels.*.requireMention`), 표시되는 답장 설정(`messages.visibleReplies`, `messages.groupChat.visibleReplies`, `messages.groupChat.unmentionedInbound`)으로 구성된 제한적인 허용 목록만 에이전트가 조정할 수 있습니다. 그 밖의 구성 경로 변경은 모두 거부됩니다. 전역 모델 기본값과 프롬프트 오버레이는 계속 운영자가 제어하며, 새로 추가된 민감한 구성 트리는 의도적으로 허용 목록에 추가하지 않는 한 보호됩니다. 또한 이 도구는 `tools.exec.ask` 또는 `tools.exec.security` 재작성을 계속 거부합니다. 레거시 `tools.bash.*` 별칭은 쓰기 검사를 수행하기 전에 동등한 `tools.exec.*` 경로로 정규화됩니다. 신뢰할 수 없는 콘텐츠를 처리하는 모든 에이전트/표면에서는 기본적으로 다음 도구를 거부하십시오. ```json5 { tools: { deny: ["gateway", "cron", "sessions_spawn", "sessions_send"], }, } ``` `commands.restart=false`는 재시작 동작만 차단하며 `gateway` 구성/업데이트 동작은 비활성화하지 않습니다. ## Node 실행(`system.run`) macOS Node가 페어링되어 있으면 Gateway가 해당 Node에서 `system.run`을 호출할 수 있습니다. 이는 해당 Mac에서의 원격 코드 실행입니다. - Node 페어링(승인 + 토큰)이 필요합니다. 페어링은 Node ID/신뢰 및 토큰 발급을 설정하는 절차이며, 명령별 승인 표면이 아닙니다. - Gateway는 `gateway.nodes.allowCommands` / `denyCommands`를 통해 대략적인 전역 Node 명령 정책을 적용합니다. `denyCommands`는 정확한 Node 명령 이름(예: `system.run`)에만 일치하며 명령 페이로드 안의 셸 텍스트에는 일치하지 않습니다. 다시 연결되는 Node가 다른 명령 목록을 알리는 것 자체는 Gateway 전역 정책과 Node 자체의 실행 승인이 경계를 계속 적용하는 한 취약점이 아닙니다. - Node별 `system.run` 정책은 Node 자체의 실행 승인 파일(`exec.approvals.node.*`)이며, Mac의 Settings -> Exec approvals(security + ask + allowlist)에서 제어합니다. 이 정책은 Gateway의 전역 명령 ID 정책보다 더 엄격하거나 느슨할 수 있습니다. - `security="full"` 및 `ask="off"`로 실행되는 Node는 기본 신뢰 운영자 모델을 따릅니다. 배포 환경에 더 엄격한 정책이 필요하지 않은 한 이는 버그가 아니라 예상된 동작입니다. - 승인 모드는 정확한 요청 컨텍스트와 가능한 경우 하나의 구체적인 로컬 스크립트/파일 피연산자를 바인딩합니다. OpenClaw가 인터프리터/런타임 명령에서 정확히 하나의 직접적인 로컬 파일을 식별할 수 없으면 완전한 의미론적 범위를 보장하는 대신 승인 기반 실행을 거부합니다. - `host=node`의 경우 승인 기반 실행은 정규화하여 준비된 `systemRunPlan`도 저장합니다. 이후 승인된 전달은 저장된 계획을 재사용하며, 승인 요청이 생성된 후 호출자가 명령/cwd/세션 컨텍스트를 수정하면 Gateway 검증에서 거부합니다. - 원격 실행을 완전히 비활성화하려면 보안을 `deny`로 설정하고 해당 Mac의 Node 페어링을 제거하십시오. ## 동적 Skills(감시자 / 원격 Node) OpenClaw는 세션 도중 Skills 목록을 새로 고칠 수 있습니다. Skills 감시자는 `SKILL.md`가 변경되면 다음 에이전트 턴에서 스냅샷을 업데이트하며, macOS Node를 연결하면 바이너리 탐색을 기반으로 macOS 전용 Skills를 사용할 수 있게 될 수 있습니다. Skills 폴더를 신뢰할 수 있는 코드로 취급하고 이를 수정할 수 있는 사용자를 제한하십시오. ## Plugin Plugin은 Gateway와 동일한 프로세스에서 실행됩니다. 신뢰할 수 있는 코드로 취급하십시오. - 신뢰하는 소스에서만 설치하고, 명시적인 `plugins.allow` 허용 목록을 사용하는 것을 권장합니다. 활성화하기 전에 Plugin 구성을 검토하고, Plugin 변경 후 Gateway를 재시작하십시오. - 설치/업데이트(`openclaw plugins install `, `openclaw plugins update `)는 신뢰할 수 없는 코드를 실행합니다. - 설치 경로는 활성 Plugin 설치 루트 아래의 Plugin별 디렉터리입니다. - OpenClaw는 설치/업데이트 중에 기본 제공 로컬 위험 코드 차단을 실행하지 않습니다. 운영자가 소유한 로컬 허용/차단 결정에는 `security.installPolicy`를 사용하고, 진단 검사에는 `openclaw security audit --deep`을 사용하십시오. - npm 및 git Plugin 설치는 명시적인 설치/업데이트 흐름에서만 패키지 관리자 종속성 수렴을 실행합니다. 로컬 경로와 아카이브는 자체 완결형 패키지로 취급되며, OpenClaw는 `npm install`을 실행하지 않고 이를 복사하거나 참조합니다. - 정확한 버전을 고정하여 사용하는 것이 좋으며(`@scope/pkg@1.2.3`), 활성화하기 전에 압축 해제된 코드를 검사하십시오. - `--dangerously-force-unsafe-install`은 사용 중단되었으며 더 이상 설치/업데이트 동작을 변경하지 않습니다. - `security.installPolicy`를 사용하면 운영자가 신뢰할 수 있는 로컬 명령을 실행하여 Skills 및 Plugin 설치에 대한 호스트별 허용/차단 결정을 내릴 수 있습니다. 소스 자료가 준비된 후 설치를 계속하기 전에 실행되고 ClawHub Skills에도 적용되며, 사용 중단된 안전하지 않은 플래그로 우회할 수 없습니다. 자세한 내용: [Plugin](/ko/tools/plugin) ## 샌드박싱 전용 문서: [샌드박싱](/ko/gateway/sandboxing) 상호 보완적인 두 가지 접근 방식이 있습니다. - **Docker의 전체 Gateway**(컨테이너 경계): [Docker](/ko/install/docker) - **도구 샌드박스**(`agents.defaults.sandbox`; 호스트 Gateway + 샌드박스로 격리된 도구, 기본 백엔드는 Docker): [샌드박싱](/ko/gateway/sandboxing) 에이전트 간 액세스를 방지하려면 `agents.defaults.sandbox.scope`를 `"agent"`(기본값)로 유지하거나, 세션별 격리를 강화하려면 `"session"`을 사용하십시오. `scope: "shared"`는 단일 컨테이너 또는 작업 공간을 사용합니다. 샌드박스 내부의 에이전트 작업 공간 액세스(`agents.defaults.sandbox.workspaceAccess`): - `"none"`(기본값): 도구는 `~/.openclaw/sandboxes` 아래의 샌드박스 작업 공간을 볼 수 있으며 에이전트 작업 공간에는 액세스할 수 없습니다. - `"ro"`: 에이전트 작업 공간을 `/agent`에 읽기 전용으로 마운트합니다(`write`/`edit`/`apply_patch` 비활성화). - `"rw"`: 에이전트 작업 공간을 `/workspace`에 읽기/쓰기 가능 상태로 마운트합니다. 추가 `sandbox.docker.binds`는 정규화 및 표준화된 소스 경로를 기준으로 검증됩니다. 차단 경로 거부 목록에는 `/etc`, `/private/etc`, `/proc`, `/sys`, `/dev`, `/root`, `/boot`와 Docker 소켓을 포함하거나 가리키는 경우가 많은 디렉터리(`/run`, `/var/run` 및 그 아래의 `docker.sock`), HOME 자격 증명 하위 경로(`.aws`, `.cargo`, `.config`, `.docker`, `.gnupg`, `.netrc`, `.npm`, `.ssh`)가 포함됩니다. 상위 심볼릭 링크를 이용한 우회와 표준 홈 별칭은 기존 상위 경로를 통해 해석된 후 다시 검사되므로 차단된 루트로 해석되면 계속 기본적으로 차단됩니다. `tools.elevated`는 샌드박스 외부에서 exec를 실행하는 전역 기본 탈출 수단입니다. 유효 호스트의 기본값은 `gateway`이며, exec 대상이 `node`로 구성된 경우에는 `node`입니다. `tools.elevated.allowFrom`을 엄격하게 제한하고 알 수 없는 사용자에게 활성화하지 마십시오. 에이전트별로 `agents.list[].tools.elevated`를 통해 추가로 제한하십시오. [권한 상승 모드](/ko/tools/elevated)를 참조하십시오. ### 하위 에이전트 위임 보호 장치 세션 도구를 허용하는 경우 위임된 하위 에이전트 실행을 또 하나의 경계 결정으로 취급하십시오. - 에이전트에 위임이 반드시 필요하지 않다면 `sessions_spawn`을 거부하십시오. - `agents.defaults.subagents.allowAgents` 및 에이전트별 `agents.list[].subagents.allowAgents` 재정의를 안전한 것으로 확인된 대상 에이전트로 제한하십시오. - 샌드박스 상태를 유지해야 하는 워크플로에서는 `sandbox: "require"`로 `sessions_spawn`을 호출하십시오(기본값은 `"inherit"`). `"require"`는 대상 하위 런타임이 샌드박스되지 않은 경우 즉시 실패합니다. ### 읽기 전용 모드 `agents.defaults.sandbox.workspaceAccess: "ro"`(작업 공간에 액세스하지 않으려면 `"none"`)와 `write`, `edit`, `apply_patch`, `exec`, `process` 등을 차단하는 도구 허용/거부 목록을 결합하여 읽기 전용 프로필을 구성하십시오. - `tools.exec.applyPatch.workspaceOnly: true`(기본값): 샌드박싱이 꺼져 있어도 `apply_patch`가 작업 공간 디렉터리 외부에 쓰거나 외부 파일을 삭제하지 못하게 합니다. 의도적으로 `apply_patch`가 작업 공간 외부의 파일을 수정하도록 하려는 경우에만 `false`로 설정하십시오. - `tools.fs.workspaceOnly: true`(선택 사항): `read`/`write`/`edit`/`apply_patch` 경로와 네이티브 프롬프트 이미지 자동 로드 경로를 작업 공간 디렉터리로 제한합니다. - 파일 시스템 루트는 좁게 유지하십시오. 에이전트/샌드박스 작업 공간에 홈 디렉터리처럼 광범위한 루트를 사용하지 마십시오. 파일 시스템 도구에 민감한 로컬 파일(예: `~/.openclaw` 아래의 상태/구성)이 노출될 수 있습니다. ## 에이전트별 액세스 프로필(멀티 에이전트) 각 에이전트는 전체 액세스, 읽기 전용 또는 액세스 없음 등 자체적인 샌드박스 + 도구 정책을 가질 수 있습니다. 우선순위 규칙은 [멀티 에이전트 샌드박스 및 도구](/ko/tools/multi-agent-sandbox-tools)를 참조하십시오. 일반적인 패턴: 개인용 에이전트(전체 액세스, 샌드박스 없음), 가족/업무용 에이전트(샌드박스 + 읽기 전용 도구), 공개 에이전트(샌드박스 + 파일 시스템/셸 도구 없음). ### 전체 액세스(샌드박스 없음) ```json5 { agents: { list: [ { id: "personal", workspace: "~/.openclaw/workspace-personal", sandbox: { mode: "off" } }, ], }, } ``` ### 읽기 전용 도구 + 읽기 전용 작업 공간 ```json5 { agents: { list: [ { id: "family", workspace: "~/.openclaw/workspace-family", sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" }, tools: { allow: ["read"], deny: ["write", "edit", "apply_patch", "exec", "process", "browser"], }, }, ], }, } ``` ### 파일 시스템/셸 액세스 없음(공급자 메시징은 허용) ```json5 { agents: { list: [ { id: "public", workspace: "~/.openclaw/workspace-public", sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" }, tools: { // 세션 도구는 트랜스크립트 데이터를 노출할 수 있습니다. 기본 범위는 현재 세션 + // 생성된 하위 에이전트 세션입니다. 필요한 경우 tools.sessions.visibility로 더 제한하십시오. sessions: { visibility: "tree" }, // self | tree | agent | all allow: [ "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", "discord", "slack", "telegram", "whatsapp", ], deny: [ "apply_patch", "browser", "canvas", "cron", "edit", "exec", "gateway", "image", "nodes", "process", "read", "write", ], }, }, ], }, } ``` ## 브라우저 제어 위험 브라우저 제어를 활성화하면 모델에 실제 브라우저 액세스 권한이 부여됩니다. 해당 프로필에 이미 로그인된 세션이 있으면 모델이 그 계정과 데이터에 액세스할 수 있으므로 브라우저 프로필을 민감한 상태로 취급하십시오. - 에이전트 전용 프로필(기본 `openclaw` 프로필)을 사용하는 것이 좋습니다. 개인적으로 일상에서 사용하는 프로필은 피하십시오. - 샌드박스화된 에이전트를 신뢰하지 않는 한 호스트 브라우저 제어를 비활성화해 두십시오. - 독립형 루프백 브라우저 제어 API는 공유 비밀 인증(Gateway 토큰 전달자 인증 또는 Gateway 비밀번호)만 허용하며, 신뢰할 수 있는 프록시 또는 Tailscale Serve ID 헤더는 사용하지 않습니다. - 브라우저 다운로드를 신뢰할 수 없는 입력으로 취급하고, 격리된 다운로드 디렉터리를 사용하는 것이 좋습니다. - 가능하면 에이전트 프로필에서 브라우저 동기화와 비밀번호 관리자를 비활성화하십시오. - 원격 Gateway에서 "브라우저 제어"는 해당 프로필이 접근할 수 있는 모든 항목에 대한 "운영자 접근 권한"과 같습니다. - Gateway 및 노드 호스트를 tailnet에서만 접근 가능하게 유지하고, 브라우저 제어 포트를 LAN이나 공용 인터넷에 노출하지 마십시오. - 필요하지 않을 때는 브라우저 프록시 라우팅을 비활성화하십시오(`gateway.nodes.browser.mode="off"`). - Chrome MCP 기존 세션 모드는 "더 안전"하지 않습니다. 해당 호스트의 Chrome 프로필이 접근할 수 있는 모든 곳에서 사용자 본인처럼 동작할 수 있습니다. - 브라우저 머신에서 **노드 호스트**를 실행하고, Gateway가 브라우저에서 원격일 때 Gateway가 브라우저 작업을 프록시하도록 하십시오([브라우저 도구](/ko/tools/browser) 참조). 노드 페어링을 관리자 접근 권한처럼 취급하고, Gateway와 노드 호스트를 동일한 tailnet에 유지하며, LAN, 공용 인터넷 또는 Tailscale Funnel을 통해 릴레이/제어 포트를 노출하지 마십시오. ### 브라우저 SSRF 정책(기본적으로 엄격함) 명시적으로 허용하지 않는 한 비공개/내부 대상은 계속 차단됩니다. - 기본값: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`가 설정되지 않으므로 비공개/내부/특수 용도 대상은 계속 차단됩니다. 레거시 별칭 `allowPrivateNetwork`도 계속 허용됩니다. - 명시적 허용: 해당 대상을 허용하려면 `dangerouslyAllowPrivateNetwork: true`를 설정하십시오. - 엄격 모드에서는 명시적 예외에 `hostnameAllowlist`(`*.example.com` 같은 패턴)와 `allowedHostnames`(`localhost`처럼 그 외에는 차단되는 이름을 포함한 정확한 호스트 예외)를 사용하십시오. - 직접 탐색 요청은 사전 검사됩니다. 작업 도중과 제한된 작업 후 유예 기간 동안 보호된 Playwright 상호 작용(클릭, 좌표 클릭, 마우스 오버, 드래그, 스크롤, 선택, 키 누르기, 입력, 양식 채우기, 평가)은 HTTP 요청 바이트가 전송되기 전에 정책에서 거부된 최상위 및 하위 프레임 문서 로드를 가로채며, 이후 최종 `http(s)` URL을 최선의 방식으로 다시 검사합니다. - 관리형 Chrome을 새로 실행할 때마다 OpenClaw는 네트워크 예측을 최선의 방식으로 비활성화하여, 거부된 로드에 대해 관찰된 Chromium의 추측성 사전 연결을 억제합니다. 이는 심층 방어이지 정책 경계가 아닙니다. 제어 서비스 재시작 전후에 재사용되는 브라우저와 다른 브라우저 백엔드는 이 강화 조치를 공유하지 않을 수 있습니다. 페이지 라우팅은 네트워크 방화벽이 아니라 요청 수준 가로채기로 유지됩니다. 리디렉션 홉, 팝업의 첫 번째 요청, Service Worker 트래픽, 제한된 보호 기간 이후 실행되는 페이지 코드, 일부 백그라운드/하위 리소스 경로는 이를 우회할 수 있습니다. 최종 URL 검사는 탐지/격리 방어 수단으로 유지됩니다. 완전히 방지하려면 소유자 측 송신 격리 또는 정책을 적용하는 프록시가 필요합니다. ```json5 { browser: { ssrfPolicy: { dangerouslyAllowPrivateNetwork: false, hostnameAllowlist: ["*.example.com", "example.com"], allowedHostnames: ["localhost"], }, }, } ``` ## 네트워크 노출 ### 바인딩, 포트, 방화벽 Gateway는 하나의 포트에서 WebSocket과 HTTP를 다중화합니다(기본값 `18789`, 구성/플래그/환경 변수: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT`). 이 HTTP 표면에는 Control UI(SPA 자산, 기본 기준 경로 `/`)와 캔버스 호스트(`/__openclaw__/canvas` 및 `/__openclaw__/a2ui` - 임의의 HTML/JS, 일반 브라우저에서 로드할 때 신뢰할 수 없는 콘텐츠로 취급하십시오. 신뢰할 수 없는 네트워크/사용자에게 노출하거나 권한이 있는 웹 표면과 오리진을 공유하지 마십시오)가 포함됩니다. `gateway.bind`는 Gateway가 수신 대기할 위치를 제어합니다. - `"loopback"`(기본값): 로컬 클라이언트만 연결할 수 있습니다. - `"lan"`, `"tailnet"`, `"custom"`: 공격 표면을 확대합니다. Gateway 인증(공유 토큰/비밀번호 또는 올바르게 구성된 신뢰할 수 있는 프록시)과 실제 방화벽이 있는 경우에만 사용하십시오. 경험칙: LAN 바인딩보다 Tailscale Serve를 사용하는 것이 좋습니다(Serve는 Gateway를 루프백에 유지하고 Tailscale이 접근을 처리합니다). LAN에 바인딩해야 한다면 광범위하게 포트 포워딩하지 말고 엄격한 소스 IP 허용 목록으로 포트를 방화벽 처리하십시오. 인증되지 않은 Gateway를 `0.0.0.0`에 절대로 노출하지 마십시오. ### UFW를 사용한 Docker 포트 게시 게시된 컨테이너 포트(`-p HOST:CONTAINER` 또는 Compose `ports:`)는 호스트 `INPUT` 규칙만이 아니라 Docker의 포워딩 체인을 통해 라우팅됩니다. `DOCKER-USER`에서 규칙을 적용하십시오(Docker 자체의 허용 규칙보다 먼저 평가됨). 최신 배포판 대부분은 `iptables-nft` 프런트엔드를 사용하며, 이 프런트엔드는 여전히 이러한 규칙을 nftables 백엔드에 적용합니다. ```bash # /etc/ufw/after.rules (append as its own *filter section) *filter :DOCKER-USER - [0:0] -A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN -A DOCKER-USER -s 127.0.0.0/8 -j RETURN -A DOCKER-USER -s 10.0.0.0/8 -j RETURN -A DOCKER-USER -s 172.16.0.0/12 -j RETURN -A DOCKER-USER -s 192.168.0.0/16 -j RETURN -A DOCKER-USER -s 100.64.0.0/10 -j RETURN -A DOCKER-USER -p tcp --dport 80 -j RETURN -A DOCKER-USER -p tcp --dport 443 -j RETURN -A DOCKER-USER -m conntrack --ctstate NEW -j DROP -A DOCKER-USER -j RETURN COMMIT ``` IPv6에는 별도의 테이블이 있습니다. Docker IPv6가 활성화된 경우 `/etc/ufw/after6.rules`에 일치하는 정책을 추가하십시오. 인터페이스 이름은 VPS 이미지에 따라 다르며(`ens3`, `enp*` 등), 이름이 일치하지 않으면 거부 규칙을 아무 알림 없이 건너뛸 수 있으므로 인터페이스 이름(`eth0`)을 하드코딩하지 마십시오. ```bash ufw reload iptables -S DOCKER-USER ip6tables -S DOCKER-USER nmap -sT -p 1-65535 --open ``` 외부에서 접근 가능한 예상 포트는 의도적으로 노출한 것뿐이어야 합니다(대부분의 설정에서는 SSH와 리버스 프록시 포트). ### mDNS/Bonjour 검색 번들 `bonjour` Plugin이 활성화되면 Gateway는 로컬 기기 검색을 위해 mDNS(`_openclaw-gw._tcp`, 포트 5353)를 통해 존재를 브로드캐스트합니다. 전체 모드에는 운영 세부 정보를 노출하는 TXT 레코드가 포함됩니다. `cliPath`(사용자 이름과 설치 위치를 드러내는 파일 시스템 경로), `sshPort`(SSH 사용 가능 여부를 알림), `displayName`/`lanHost`(호스트 이름 정보). 인프라 세부 정보를 브로드캐스트하면 LAN 정찰이 더 쉬워집니다. - LAN 검색이 필요하지 않으면 Bonjour를 비활성화해 두십시오. macOS 호스트에서는 자동으로 시작되며 다른 환경에서는 명시적으로 활성화해야 합니다. 직접 Gateway URL, Tailnet, SSH 또는 광역 DNS-SD를 사용하면 로컬 멀티캐스트를 피할 수 있습니다. - **최소 모드**(Bonjour가 활성화되었을 때 기본값이며 노출된 Gateway에 권장됨)는 민감한 필드를 생략합니다. ```json5 { discovery: { mdns: { mode: "minimal" } } } ``` - **끄기**는 Plugin을 활성화된 상태로 유지하면서 로컬 검색을 억제합니다. ```json5 { discovery: { mdns: { mode: "off" } } } ``` - **전체 모드**(명시적 활성화)에는 `cliPath`와 `sshPort`가 포함됩니다. ```json5 { discovery: { mdns: { mode: "full" } } } ``` - 또는 구성 변경 없이 mDNS를 비활성화하려면 `OPENCLAW_DISABLE_BONJOUR=1`을 설정하십시오. 최소 모드에서 Gateway는 `role`, `gatewayPort`, `transport`를 브로드캐스트하지만 `cliPath`/`sshPort`는 생략합니다. CLI 경로가 필요한 앱은 대신 인증된 WebSocket 연결을 통해 가져올 수 있습니다. ### Gateway WebSocket 인증 Gateway 인증은 기본적으로 필수입니다. 유효한 인증 경로가 구성되지 않으면 Gateway는 WebSocket 연결을 거부합니다(실패 시 차단). 온보딩은 기본적으로 토큰을 생성하므로(루프백에서도) 로컬 클라이언트도 인증해야 합니다. ```json5 { gateway: { auth: { mode: "token", token: "your-token" } } } ``` `openclaw doctor --generate-gateway-token`으로 토큰을 생성할 수 있습니다. `gateway.remote.token`과 `gateway.remote.password`는 클라이언트 자격 증명 소스이며, 그 자체로는 로컬 WS 접근을 보호하지 않습니다. 로컬 호출 경로는 `gateway.auth.*`가 설정되지 않은 경우에만 `gateway.remote.*`를 대체 수단으로 사용합니다. `gateway.auth.token` 또는 `gateway.auth.password`가 SecretRef를 통해 명시적으로 구성되었지만 확인되지 않으면 확인이 실패 시 차단됩니다(원격 대체 수단으로 실패를 숨기지 않음). `wss://`를 사용할 때는 `gateway.remote.tlsFingerprint`로 원격 TLS를 고정하십시오. 평문 `ws://`는 루프백, 비공개 IP 리터럴, `.local`, Tailnet `*.ts.net` Gateway URL에 허용됩니다. 그 밖의 신뢰할 수 있는 비공개 DNS 이름에서는 비상 조치로 클라이언트 프로세스에 `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`을 설정하십시오(프로세스 환경에서만 사용하며 `openclaw.json` 키가 아님). 모바일 페어링과 Android 수동/스캔 Gateway 경로는 더 엄격합니다. 평문은 루프백에서만 허용되며, 비공개 LAN, 링크 로컬, `.local`, 점이 없는 호스트 이름은 신뢰할 수 있는 비공개 네트워크 평문 경로를 명시적으로 허용하지 않는 한 TLS를 사용해야 합니다. 직접 로컬 루프백 연결에서는 기기 페어링이 자동 승인됩니다(신뢰할 수 있는 공유 비밀 도우미 흐름을 위한 제한적인 백엔드/컨테이너 로컬 자체 연결 경로 포함). 동일 호스트에서 tailnet 주소로 연결하는 경우를 포함하여 Tailnet 및 LAN 연결은 원격으로 취급되며 여전히 승인이 필요합니다. 확인된 `tailnet` 주소 또는 `127.0.0.1`이나 `0.0.0.0`이 아닌 `custom` 주소는 별도의 `127.0.0.1` 리스너를 추가합니다. 해당 로컬 리스너에 대한 연결만 루프백 의미 체계를 적용받습니다. 루프백 요청의 전달된 헤더 증거는 루프백 로컬성을 무효화하며, 메타데이터 업그레이드 자동 승인은 제한적으로 적용됩니다. [Gateway 페어링](/ko/gateway/pairing)을 참조하십시오. 인증 모드: - `"token"`: 공유 전달자 토큰(대부분의 설정에 권장됨). - `"password"`: `OPENCLAW_GATEWAY_PASSWORD`를 통해 설정하는 것이 좋습니다. - `"trusted-proxy"`: ID 인식 리버스 프록시가 사용자를 인증하고 헤더를 통해 ID를 전달하도록 신뢰합니다. [신뢰할 수 있는 프록시 인증](/ko/gateway/trusted-proxy-auth)을 참조하십시오. 교체 체크리스트(토큰/비밀번호): 새 비밀을 생성/설정하고(`gateway.auth.token` 또는 `OPENCLAW_GATEWAY_PASSWORD`), Gateway를 다시 시작하고(또는 Gateway를 감독하는 경우 macOS 앱), 원격 클라이언트를 업데이트한 다음(`gateway.remote.token`/`.password`), 이전 자격 증명이 더 이상 작동하지 않는지 확인하십시오. ### Tailscale Serve ID 헤더 `gateway.auth.allowTailscale`이 `true`이면(Serve의 기본값) OpenClaw는 Control UI/WebSocket 인증에 Tailscale Serve ID 헤더 `tailscale-user-login`을 허용합니다. 로컬 Tailscale 데몬(`tailscale whois`)을 통해 `x-forwarded-for` 주소를 확인하고 헤더와 일치시켜 ID를 검증합니다. 이 동작은 Tailscale이 삽입한 `x-forwarded-for`, `x-forwarded-proto`, `x-forwarded-host`를 포함하는 루프백 요청에서만 실행됩니다. 이 비동기 검사에서는 제한기가 실패를 기록하기 전에 동일한 `{scope, ip}`의 실패한 시도를 직렬화하므로, 한 Serve 클라이언트에서 동시에 잘못 재시도하면 두 번째 시도가 즉시 잠길 수 있습니다. HTTP API 엔드포인트(`/v1/*`, `/tools/invoke`, `/api/channels/*`)는 Tailscale ID 헤더 인증을 사용하지 않습니다. Gateway에 구성된 HTTP 인증 모드를 따릅니다. Gateway HTTP 전달자 인증은 사실상 전부 아니면 전무인 운영자 접근 권한입니다. `/v1/chat/completions`, `/v1/responses`, `/api/v1/admin/rpc` 같은 Plugin 경로 또는 `/api/channels/*`를 호출할 수 있는 자격 증명은 해당 Gateway의 전체 접근 운영자 비밀입니다. 공유 비밀 전달자 인증은 전체 기본 운영자 범위(`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`)와 에이전트 턴의 소유자 의미 체계를 복원하며, 더 제한적인 `x-openclaw-scopes` 값은 해당 공유 비밀 경로를 축소하지 않습니다. 요청별 범위 의미 체계는 ID를 포함하는 모드(신뢰할 수 있는 프록시 인증) 또는 명시적으로 인증이 없는 비공개 인그레스에서 요청이 들어오는 경우에만 적용됩니다. 이러한 모드에서 `x-openclaw-scopes`를 생략하면 일반적인 기본 운영자 범위 집합으로 대체되며, 범위가 축소된 경우 `x-openclaw-model` 같은 소유자 수준 헤더에는 `operator.admin`이 필요합니다. `/tools/invoke`와 HTTP 세션 기록 엔드포인트에도 동일한 공유 비밀 규칙이 적용됩니다. 신뢰할 수 없는 호출자와 이러한 자격 증명을 공유하지 마십시오. 신뢰 경계마다 별도의 Gateway를 사용하는 것이 좋습니다. 토큰 없는 Serve 인증은 Gateway 호스트 자체가 신뢰할 수 있다고 가정하며, 적대적인 동일 호스트 프로세스로부터 보호하지 않습니다. 신뢰할 수 없는 로컬 코드가 Gateway 호스트에서 실행될 수 있다면 `allowTailscale`을 비활성화하고 명시적인 공유 비밀 인증(`token` 또는 `password`)을 요구하십시오. 자체 리버스 프록시에서 이러한 헤더를 전달하지 마십시오. Gateway 앞에서 TLS를 종료하거나 프록시하는 경우 `allowTailscale`을 비활성화하고 대신 공유 비밀 인증 또는 [신뢰할 수 있는 프록시 인증](/ko/gateway/trusted-proxy-auth)을 사용하십시오. [Tailscale](/ko/gateway/tailscale) 및 [웹 개요](/ko/web)를 참조하십시오. ### 리버스 프록시 구성 nginx/Caddy/Traefik 등의 뒤에서 전달된 클라이언트 IP를 올바르게 처리하려면 `gateway.trustedProxies`를 설정하십시오. Gateway가 `trustedProxies`에 **포함되지 않은** 주소에서 프록시 헤더를 감지하면 해당 연결을 로컬로 취급하지 않으며, Gateway 인증이 비활성화된 경우 해당 연결을 거부합니다. 이렇게 하면 프록시된 연결이 localhost에서 시작된 것처럼 보이고 자동으로 신뢰받는 것을 방지할 수 있습니다. `trustedProxies`는 더 엄격한 `gateway.auth.mode: "trusted-proxy"`에도 사용됩니다. 이 모드는 기본적으로 루프백 소스 프록시에 대해 안전하게 실패합니다. 같은 호스트의 루프백 리버스 프록시는 로컬 클라이언트 감지 및 전달된 IP 처리에 `trustedProxies`를 사용할 수 있지만, `gateway.auth.trustedProxy.allowLoopback = true`인 경우에만 `trusted-proxy` 인증 모드를 충족할 수 있습니다. 그렇지 않으면 토큰/비밀번호 인증을 사용하십시오. ```yaml gateway: trustedProxies: - "10.0.0.1" # 리버스 프록시 IP allowRealIpFallback: false # 기본값은 false이며, 프록시가 X-Forwarded-For를 제공할 수 없는 경우에만 활성화하십시오 auth: mode: password password: ${OPENCLAW_GATEWAY_PASSWORD} ``` `trustedProxies`가 설정되면 Gateway는 `X-Forwarded-For`를 사용하여 클라이언트 IP를 확인합니다. `gateway.allowRealIpFallback: true`를 명시적으로 설정하지 않는 한 `X-Real-IP`는 무시됩니다. 프록시가 `X-Forwarded-For`/`X-Real-IP`에 값을 추가하는 대신 해당 값을 **덮어쓰도록** 구성하십시오. ```nginx # 올바른 예 proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; # 잘못된 예: 신뢰할 수 없는 클라이언트가 제공한 값을 보존하거나 추가함 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ``` 신뢰할 수 있는 프록시 헤더를 사용해도 Node 기기 페어링이 자동으로 신뢰되지는 않습니다. `gateway.nodes.pairing.autoApproveCidrs`는 기본적으로 비활성화된 별도의 운영자 정책이며, 루프백 신뢰 프록시 인증이 활성화되어 있어도 루프백 소스의 신뢰 프록시 헤더 경로는 Node 자동 승인에서 계속 제외됩니다(로컬 호출자가 이러한 헤더를 위조할 수 있기 때문입니다). ### HSTS 및 오리진 참고 사항 - OpenClaw의 Gateway는 로컬/루프백 사용을 우선합니다. 리버스 프록시에서 TLS를 종료하는 경우 그곳에서 HSTS를 설정하십시오. - Gateway 자체에서 HTTPS를 종료하는 경우 `gateway.http.securityHeaders.strictTransportSecurity`는 OpenClaw 응답에 HSTS 헤더를 포함합니다. - 루프백이 아닌 Control UI 배포에는 기본적으로 `gateway.controlUi.allowedOrigins`가 필요합니다. `allowedOrigins: ["*"]`는 명시적인 전체 허용 정책이지 강화된 기본값이 아닙니다. 엄격하게 통제되는 로컬 테스트 외부에서는 사용하지 마십시오. - 일반적인 루프백 면제가 활성화되어 있어도 루프백에서 발생하는 브라우저 오리진 인증 실패에는 여전히 속도 제한이 적용되지만, 잠금 키는 하나의 공유 localhost 버킷 대신 정규화된 각 `Origin` 값의 범위로 지정됩니다. - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true`는 Host 헤더 오리진 폴백 모드를 활성화합니다. 운영자가 선택하는 위험한 정책으로 취급하십시오. - DNS 리바인딩 및 프록시 Host 헤더 동작을 배포 강화 문제로 취급하십시오. `trustedProxies`를 엄격하게 제한하고 Gateway를 공용 인터넷에 직접 노출하지 마십시오. - 자세한 배포 지침: [신뢰할 수 있는 프록시 인증](/ko/gateway/trusted-proxy-auth#tls-termination-and-hsts). ### HTTP를 통한 Control UI Control UI에서 기기 ID를 생성하려면 보안 컨텍스트(HTTPS 또는 localhost)가 필요합니다. - `gateway.controlUi.allowInsecureAuth`: 로컬 호환성 토글입니다. localhost에서 페이지가 안전하지 않은 HTTP로 로드될 때 기기 ID 없이 Control UI 인증을 허용합니다. 페어링 검사를 우회하지 않으며 원격(non-localhost) 기기 ID 요구 사항을 완화하지도 않습니다. HTTPS(Tailscale Serve)를 사용하거나 `127.0.0.1`에서 UI를 여는 방법을 권장합니다. - `gateway.controlUi.dangerouslyDisableDeviceAuth`: 비상시에만 사용하며 기기 ID 검사를 완전히 비활성화합니다. 보안을 심각하게 약화하므로, 적극적으로 디버깅 중이고 신속하게 되돌릴 수 있는 경우가 아니라면 비활성화 상태로 유지하십시오. - 이러한 플래그와 별개로 `gateway.auth.mode: "trusted-proxy"` 인증에 성공하면 기기 ID 없이 **운영자** Control UI 세션을 허용할 수 있습니다. 이는 의도된 인증 모드 동작이며 `allowInsecureAuth` 단축 경로가 아니고, Node 역할 Control UI 세션에는 적용되지 않습니다. `allowInsecureAuth`가 활성화되어 있으면 `openclaw security audit`에서 경고합니다. ### 안전하지 않거나 위험한 플래그 알려진 안전하지 않거나 위험한 디버그 스위치가 활성화될 때마다 `openclaw security audit`에서 `config.insecure_or_dangerous_flags`를 발생시킵니다(플래그당 발견 항목 1개). 프로덕션에서는 이러한 스위치를 설정하지 마십시오. 감사 억제가 구성된 경우 일치하는 발견 항목이 `suppressedFindings`로 이동하더라도 `security.audit.suppressions.active`는 활성 출력에 계속 표시됩니다. - `gateway.controlUi.allowInsecureAuth=true` - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` - `security.audit.suppressions configured ()` - `hooks.gmail.allowUnsafeExternalContent=true` - `hooks.mappings[].allowUnsafeExternalContent=true` - `tools.exec.applyPatch.workspaceOnly=false` - `plugins.entries.acpx.config.permissionMode=approve-all` Control UI 및 브라우저: - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` - `gateway.controlUi.dangerouslyDisableDeviceAuth` - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 채널 이름 일치(번들 및 Plugin 채널, 해당하는 경우 `accounts.`별로도 적용): - `channels.discord.dangerouslyAllowNameMatching` - `channels.googlechat.dangerouslyAllowNameMatching` - `channels.msteams.dangerouslyAllowNameMatching` - `channels.slack.dangerouslyAllowNameMatching` - `channels.irc.dangerouslyAllowNameMatching`(Plugin 채널) - `channels.mattermost.dangerouslyAllowNameMatching`(Plugin 채널) - `channels.synology-chat.dangerouslyAllowNameMatching`(Plugin 채널) - `channels.synology-chat.dangerouslyAllowInheritedWebhookPath`(Plugin 채널) - `channels.zalouser.dangerouslyAllowNameMatching`(Plugin 채널) 네트워크 노출: - `channels.telegram.network.dangerouslyAllowPrivateNetwork`(계정별 설정도 가능) 샌드박스 Docker(기본값 + 에이전트별): - `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets` - `agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources` - `agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin` ## 배포 및 호스트 신뢰 - Gateway 호스트에서 전체 디스크 암호화를 사용하십시오. 호스트를 공유하는 경우 Gateway 전용 OS 사용자 계정을 사용하는 것이 좋습니다. - 게시된 패키지의 종속성 잠금: 소스 체크아웃은 `pnpm-lock.yaml`을 사용합니다. 게시된 `openclaw` npm 패키지와 OpenClaw 소유 npm Plugin 패키지에는 `npm-shrinkwrap.json`이 포함되므로, 설치 시 새로운 종속성 그래프를 확인하는 대신 릴리스에서 검토된 전이 종속성 그래프를 사용합니다. 이는 공급망 강화 및 릴리스 재현성 경계이며 샌드박스가 아닙니다. [npm shrinkwrap](/ko/gateway/security/shrinkwrap)를 참조하십시오. - 안전한 파일 작업: OpenClaw는 루트 범위로 제한된 파일 액세스, 원자적 쓰기, 아카이브 추출, 임시 작업 공간 및 비밀 파일 도우미에 `@openclaw/fs-safe`를 사용합니다. 선택적 POSIX Python 도우미의 기본값은 **꺼짐**입니다. 추가적인 파일 디스크립터 상대 경로 변경 강화를 원하고 Python 런타임을 지원할 수 있는 경우에만 `OPENCLAW_FS_SAFE_PYTHON_MODE=auto` 또는 `require`로 설정하십시오. 자세한 내용은 [안전한 파일 작업](/ko/gateway/security/secure-file-operations)을 참조하십시오. - 공유 Slack 워크스페이스 위험: Slack의 모든 사용자가 봇에 메시지를 보낼 수 있다면 핵심 위험은 위임된 도구 권한입니다. 허용된 모든 발신자는 에이전트 정책 내에서 도구 호출(`exec`, 브라우저, 네트워크/파일 도구)을 유도할 수 있고, 한 발신자의 프롬프트/콘텐츠 주입이 공유 상태/기기/출력에 영향을 줄 수 있으며, 공유 에이전트에 민감한 자격 증명/파일이 있는 경우 허용된 모든 발신자가 도구 사용을 통해 잠재적으로 유출을 유도할 수 있습니다. 팀 워크플로에는 최소한의 도구만 갖춘 별도의 에이전트/Gateway를 사용하고, 개인 데이터 에이전트는 비공개로 유지하십시오. - 회사 공유 에이전트(허용 가능한 패턴): 에이전트를 사용하는 모든 사람이 동일한 신뢰 경계(예: 하나의 회사 팀) 내에 있고 에이전트의 범위가 업무로 엄격히 제한된 경우 적합합니다. 전용 머신/VM/컨테이너에서 실행하고, 전용 OS 사용자와 전용 브라우저/프로필/계정을 사용하며, 해당 런타임에서 개인 Apple/Google 계정이나 개인 암호 관리자/브라우저 프로필에 로그인하지 마십시오. 동일한 런타임에서 개인 ID와 회사 ID를 혼용하면 분리가 무너지고 개인 데이터 노출 위험이 증가합니다. ## 디스크의 비밀 정보 `~/.openclaw/`(또는 `$OPENCLAW_STATE_DIR/`) 아래의 모든 항목에는 비밀 정보나 개인 데이터가 포함될 수 있다고 가정하십시오: | 경로 | 내용 | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `openclaw.json` | 구성에는 토큰(Gateway, 원격 Gateway), 제공자 설정, 허용 목록이 포함될 수 있습니다. | | `credentials/**` | 채널 자격 증명(예: WhatsApp 자격 증명), 페어링 허용 목록, 레거시 OAuth 가져오기 데이터입니다. | | `agents//agent/auth-profiles.json` | API 키, 토큰 프로필, OAuth 토큰, 선택적 `keyRef`/`tokenRef`입니다. | | `agents//agent/codex-home/**` | 에이전트별 Codex 앱 서버 계정, 구성, Skills, Plugin, 네이티브 스레드 상태, 진단 정보(기본값)입니다. | | `$CODEX_HOME/**` 또는 `~/.codex/**` | 네이티브 Codex 런타임 상태입니다. 일반 하네스는 `plugins.entries.codex.config.appServer.homeScope: "user"`가 명시된 경우에만 이 상태에 액세스합니다. 별도의 감독 연결은 해석된 홈 범위가 `"user"`일 때 액세스하며, 이 값은 stdio 또는 Unix에서 설정되지 않은 경우의 기본값입니다. 네이티브 Codex 계정, 구성, Plugin 및 스레드 저장소를 포함합니다. 감독은 소스 메타데이터를 나열하고, 계속 진행되는 Chat의 정규 네이티브 브랜치와 해당 연결에서 이루어지는 후속 턴을 유지합니다. 브랜치를 만들면 범위가 제한된 영속 사용자 및 어시스턴트 기록을 인증되고 모델이 고정된 OpenClaw Chat으로 복사합니다. 소유자가 제어하는 Gateway에서만 활성화하십시오. [Codex 하네스](/ko/plugins/codex-harness#share-threads-with-codex-desktop-and-cli) 및 [Codex 감독](/plugins/codex-supervision)을 참조하십시오. | | `secrets.json`(선택 사항) | `file` SecretRef 제공자(`secrets.providers`)가 사용하는 파일 기반 비밀 페이로드입니다. | | `agents//agent/auth.json` | 레거시 호환성 파일입니다. 정적 `api_key` 항목은 발견 시 제거됩니다. | | `agents//agent/openclaw-agent.sqlite` | 비공개 메시지와 도구 출력을 포함할 수 있는 세션 행 및 트랜스크립트를 비롯한 에이전트별 런타임 상태입니다. | | `agents//sessions/**` | 비공개 메시지와 도구 출력을 포함할 수 있는 레거시 세션 마이그레이션 소스 및 아카이브입니다. | | 번들 Plugin 패키지 | 설치된 Plugin과 해당 `node_modules/`입니다. | | `sandboxes/**` | 도구 샌드박스 작업 공간입니다. 샌드박스 내에서 읽거나 쓴 파일의 복사본이 누적될 수 있습니다. | ### 자격 증명 저장소 맵 백업 결정에도 유용합니다. - WhatsApp: `~/.openclaw/credentials/whatsapp//creds.json` - Telegram 봇 토큰: 구성/환경 변수 또는 `channels.telegram.tokenFile`(일반 파일만 허용되며 심볼릭 링크는 거부됨) - Discord 봇 토큰: 구성/환경 변수 또는 SecretRef(환경 변수/파일/실행 제공자) - Slack 토큰: 구성/환경 변수(`channels.slack.*`) - 페어링 허용 목록: `~/.openclaw/credentials/-allowFrom.json`(기본 계정) / `--allowFrom.json`(기본 계정이 아닌 계정) - 모델 인증 프로필: `~/.openclaw/agents//agent/auth-profiles.json` - 레거시 OAuth 가져오기 데이터: `~/.openclaw/credentials/oauth.json` 보안 강화: 권한을 엄격하게 유지하십시오(디렉터리는 `700`, 파일은 `600`). Gateway 호스트에서 전체 디스크 암호화를 사용하고, 호스트를 공유하는 경우 전용 OS 사용자 계정을 사용하는 것이 좋습니다. ### 파일 권한 - `~/.openclaw/openclaw.json`: `600`(사용자만 읽기/쓰기 가능) - `~/.openclaw`: `700`(사용자만 접근 가능) `openclaw doctor`는 이러한 권한에 대해 경고하고 권한 강화를 제안할 수 있습니다. ### 작업 공간 `.env` 파일 OpenClaw는 에이전트와 도구를 위해 작업 공간 로컬 `.env` 파일을 로드하지만, 이 파일이 Gateway 런타임 제어를 암묵적으로 재정의하도록 허용하지 않습니다. - 신뢰할 수 없는 작업 공간의 `.env` 파일에서는 제공자 자격 증명 환경 변수가 차단됩니다. 예를 들면 `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `XAI_API_KEY`, `MISTRAL_API_KEY`, `GROQ_API_KEY`, `DEEPSEEK_API_KEY`, `PERPLEXITY_API_KEY`, `BRAVE_API_KEY`, `TAVILY_API_KEY`, `EXA_API_KEY`, `FIRECRAWL_API_KEY`와 설치된 신뢰할 수 있는 플러그인이 선언한 제공자 인증 키가 있습니다. 대신 제공자 자격 증명을 Gateway 프로세스 환경, `~/.openclaw/.env` (`$OPENCLAW_STATE_DIR/.env`), 구성의 `env` 블록 또는 선택적 로그인 셸 가져오기에 넣으십시오. - `OPENCLAW_`로 시작하는 모든 키는 신뢰할 수 없는 작업 공간의 `.env` 파일에서 차단됩니다. 이렇게 하면 전체 런타임 네임스페이스를 예약하여 향후 `OPENCLAW_*` 제어 항목이 체크인되거나 공격자가 제공한 `.env` 콘텐츠에서 암묵적으로 상속되지 않고 기본적으로 실패 시 차단됩니다. - Matrix, Mattermost, IRC 및 Synology Chat의 채널 엔드포인트 설정도 작업 공간 `.env` 재정의에서 차단됩니다(예: `MATRIX_HOMESERVER`, `MATTERMOST_URL`, `IRC_HOST`, `SYNOLOGY_CHAT_INCOMING_URL`). 따라서 복제된 작업 공간이 로컬 엔드포인트 구성을 통해 번들 커넥터 트래픽을 다른 곳으로 리디렉션할 수 없습니다. 이러한 설정은 Gateway 프로세스 환경 또는 `env.shellEnv`에서 가져와야 합니다. - 신뢰할 수 있는 프로세스/OS 환경 변수, 전역 런타임 dotenv, 구성의 `env` 및 활성화된 로그인 셸 가져오기는 계속 적용됩니다. 이는 작업 공간 `.env` 파일 로딩만 제한합니다. 작업 공간 `.env` 파일은 에이전트 코드 옆에 있는 경우가 많고 실수로 커밋되거나 도구에 의해 작성될 수 있습니다. 제공자 자격 증명을 차단하면 복제된 작업 공간이 공격자가 제어하는 제공자 계정으로 대체하는 것을 방지할 수 있습니다. ### 로그 및 트랜스크립트 OpenClaw는 세션 연속성과 선택적 메모리 인덱싱을 위해 세션 트랜스크립트를 디스크의 `~/.openclaw/agents//sessions/*.jsonl` 아래에 저장합니다. 파일 시스템에 접근할 수 있는 모든 프로세스/사용자가 이를 읽을 수 있습니다. 디스크 접근을 신뢰 경계로 간주하고 `~/.openclaw` 권한을 제한하십시오. 더 강력하게 격리하려면 에이전트를 별도의 OS 사용자 또는 호스트에서 실행하십시오. Gateway 로그에는 도구 요약, 오류 및 URL이 포함될 수 있으며, 세션 트랜스크립트에는 붙여 넣은 비밀, 파일 내용, 명령 출력 및 링크가 포함될 수 있습니다. - 로그/트랜스크립트 민감 정보 삭제를 활성화된 상태로 유지하십시오(`logging.redactSensitive: "tools"`, 기본값). - `logging.redactPatterns`를 통해 환경에 맞는 사용자 지정 패턴(토큰, 호스트 이름, 내부 URL)을 추가하십시오. - 진단 정보를 공유할 때는 원시 로그보다 `openclaw status --all`(붙여 넣기 가능, 비밀이 삭제됨)을 사용하는 것이 좋습니다. - 장기간 보관할 필요가 없다면 오래된 세션 트랜스크립트와 로그 파일을 정리하십시오. 자세한 내용: [로깅](/ko/gateway/logging) ## 보안 기준선(복사/붙여넣기) ```json5 { gateway: { mode: "local", bind: "loopback", port: 18789, auth: { mode: "token", token: "your-long-random-token" }, }, channels: { whatsapp: { dmPolicy: "pairing", groups: { "*": { requireMention: true } }, }, }, } ``` Gateway를 비공개로 유지하고 DM 페어링을 요구하며 그룹 봇이 항상 활성화되는 것을 방지합니다. 도구 실행도 더 안전하게 하려면 소유자가 아닌 모든 에이전트에 샌드박스를 추가하고 위험한 도구를 거부하십시오(위의 "에이전트별 접근 프로필" 참조). ### 별도 번호(WhatsApp, Signal, Telegram) 전화번호 기반 채널에서는 개인 대화가 비공개로 유지되고 봇 번호가 자체 경계 내에서 자동화를 처리하도록 개인 번호와 별도의 번호에서 어시스턴트를 실행하는 것을 고려하십시오. ## 인시던트 대응 ### 격리 1. 중지하십시오. macOS 앱이 Gateway를 감독하는 경우 앱을 중지하거나 `openclaw gateway` 프로세스를 종료하십시오. 2. 노출을 차단하십시오. 상황을 파악할 때까지 `gateway.bind: "loopback"`을 설정하거나 Tailscale Funnel/Serve를 비활성화하십시오. 3. 접근을 동결하십시오. 위험한 DM/그룹을 `dmPolicy: "disabled"`로 전환하거나 멘션을 요구하고, 모든 `"*"` 전체 허용 항목을 제거하십시오. ### 교체(비밀이 유출되었다면 침해된 것으로 간주) 1. Gateway 인증(`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`)을 교체하고 다시 시작하십시오. 2. Gateway를 호출할 수 있는 모든 머신에서 원격 클라이언트 비밀(`gateway.remote.token` / `.password`)을 교체하십시오. 3. 제공자/API 자격 증명(WhatsApp 자격 증명, Slack/Discord 토큰, `auth-profiles.json`의 모델/API 키 및 사용 중인 암호화된 비밀 페이로드 값)을 교체하십시오. ### 감사 1. Gateway 로그를 확인하십시오: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`(또는 `logging.file`). 2. 관련 트랜스크립트를 검토하십시오: `~/.openclaw/agents//sessions/*.jsonl`. 3. 접근 범위를 넓혔을 수 있는 최근 구성 변경 사항을 검토하십시오: `gateway.bind`, `gateway.auth`, DM/그룹 정책, `tools.elevated`, 플러그인 변경 사항. 4. `openclaw security audit --deep`을 다시 실행하고 심각한 발견 사항이 해결되었는지 확인하십시오. ### 보고서용 정보 수집 - 타임스탬프, Gateway 호스트 OS + OpenClaw 버전. - 세션 트랜스크립트 + 짧은 로그 뒷부분(민감 정보 삭제 후). - 공격자가 보낸 내용과 에이전트가 수행한 작업. - Gateway가 루프백 외부에 노출되었는지 여부(LAN/Tailscale Funnel/Serve). ## 비밀 스캔 CI는 저장소 전체에서 pre-commit `detect-private-key` 훅을 실행합니다. 실패하면 커밋된 키 자료를 제거하거나 교체한 후 로컬에서 재현하십시오. ```bash pre-commit run --all-files detect-private-key ``` ## 보안 문제 신고 OpenClaw에서 취약점을 발견하셨습니까? 책임감 있게 신고하십시오. 1. 이메일: [security@openclaw.ai](mailto:security@openclaw.ai) 2. 수정되기 전에는 공개적으로 게시하지 마십시오. 3. 익명을 원하지 않는 한 기여자로 이름을 명시하겠습니다.